EContext (Numbers 0.3.0 API)

java.lang.Object
- com.upokecenter.numbers.EContext

```
public final class EContext
extends Object
```
Contains parameters for controlling the precision, rounding, and exponent range of arbitrary-precision numbers. (The "E" stands for "extended", and has this prefix to group it with the other classes common to this library, particularly EDecimal, EFloat, and ERational.).
Thread safety: With one exception, instances of this class are immutable and are safe to use among multiple threads. The one exception involves the Flags property. If the context's HasFlags property (a read-only property) is true, the Flags property is mutable, thus making the context mutable. This class doesn't synchronize access to such mutable contexts, so applications should provide their own synchronization if a context with the HasFlags property set to true will be shared among multiple threads and at least one of those threads needs to write the Flags property (which can happen, for example, by passing the context to most methods of EDecimal such as Add).

Field Summary

Fields
Modifier and Type	Field and Description
`static EContext`	`Basic` A basic arithmetic context, 9 digits precision, rounding mode half-up, unlimited exponent range.
`static EContext`	`BigDecimalJava` An arithmetic context for Java's BigDecimal format.
`static EContext`	`Binary128` An arithmetic context for the IEEE-754-2008 binary128 format, 113 bits precision.
`static EContext`	`Binary16` An arithmetic context for the IEEE-754-2008 binary16 format, 11 bits precision.
`static EContext`	`Binary32` An arithmetic context for the IEEE-754-2008 binary32 format, 24 bits precision.
`static EContext`	`Binary64` An arithmetic context for the IEEE-754-2008 binary64 format, 53 bits precision.
`static EContext`	`CliDecimal` An arithmetic context for the .NET Framework decimal format (see `"Forms of numbers"`), 96 bits precision, and a valid exponent range of -28 to 0.
`static EContext`	`Decimal128` An arithmetic context for the IEEE-754-2008 decimal128 format.
`static EContext`	`Decimal32` An arithmetic context for the IEEE-754-2008 decimal32 format.
`static EContext`	`Decimal64` An arithmetic context for the IEEE-754-2008 decimal64 format.
`static int`	`FlagClamped` Signals that the exponent was adjusted to fit the exponent range.
`static int`	`FlagDivideByZero` Signals a division of a nonzero number by zero.
`static int`	`FlagInexact` Signals that the result was rounded to a different mathematical value, but as close as possible to the original.
`static int`	`FlagInvalid` Signals an invalid operation.
`static int`	`FlagLostDigits` Signals that an operand was rounded to a different mathematical value before an operation.
`static int`	`FlagOverflow` Signals that the result is non-zero and the exponent is higher than the highest exponent allowed.
`static int`	`FlagRounded` Signals that the result was rounded to fit the precision; either the value or the exponent may have changed from the original.
`static int`	`FlagSubnormal` Signals that the result's exponent, before rounding, is lower than the lowest exponent allowed.
`static int`	`FlagUnderflow` Signals that the result's exponent, before rounding, is lower than the lowest exponent allowed, and the result was rounded to a different mathematical value, but as close as possible to the original.
`static EContext`	`Unlimited` No specific (theoretical) limit on precision.
`static EContext`	`UnlimitedHalfEven` No specific (theoretical) limit on precision.

Constructor Summary

Constructors
Constructor and Description
`EContext(int precision, ERounding rounding, int exponentMinSmall, int exponentMaxSmall, boolean clampNormalExponents)` Initializes a new instance of the `EContext` class.

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`EContext`	`Copy()` Initializes a new EContext that is a copy of another EContext.
`boolean`	`ExponentWithinRange(EInteger exponent)` Determines whether a number can have the given Exponent property under this arithmetic context.
`static EContext`	`ForPrecision(int precision)` Creates a new arithmetic context using the given maximum number of digits, an unlimited exponent range, and the HalfUp rounding mode.
`static EContext`	`ForPrecisionAndRounding(int precision, ERounding rounding)` Creates a new EContext object initialized with an unlimited exponent range, and the given rounding mode and maximum precision.
`static EContext`	`ForRounding(ERounding rounding)` Creates a new EContext object initialized with an unlimited precision, an unlimited exponent range, and the given rounding mode.
`boolean`	`getAdjustExponent()` Gets a value indicating whether the EMax and EMin properties refer to the number's Exponent property adjusted to the number's precision, or just the number's Exponent property.
`boolean`	`getClampNormalExponents()` Gets a value indicating whether a converted number's Exponent property will not be higher than EMax + 1 - Precision.
`EInteger`	`getEMax()` Gets the highest exponent possible when a converted number is expressed in scientific notation with one digit before the radix point.
`EInteger`	`getEMin()` Gets the lowest exponent possible when a converted number is expressed in scientific notation with one digit before the radix point.
`int`	`getFlags()` Gets the flags that are set from converting numbers according to this arithmetic context.
`boolean`	`getHasExponentRange()` Gets a value indicating whether this context defines a minimum and maximum exponent.
`boolean`	`getHasFlags()` Gets a value indicating whether this context has a mutable Flags field.
`boolean`	`getHasMaxPrecision()` Gets a value indicating whether this context defines a maximum precision.
`EInteger`	`getPrecision()` Gets the maximum length of a converted number in digits, ignoring the radix point and exponent.
`ERounding`	`getRounding()` Gets the desired rounding mode when converting numbers that can't be represented in the given precision and exponent range.
`int`	`getTraps()` Gets the traps that are set for each flag in the context.
`boolean`	`isPrecisionInBits()` Gets a value indicating whether this context's Precision property is in bits, rather than digits.
`boolean`	`isSimplified()` Gets a value indicating whether to use a "simplified" arithmetic.
`void`	`setFlags(int value)`
`String`	`toString()` Gets a string representation of this object.
`EContext`	`WithAdjustExponent(boolean adjustExponent)` Copies this EContext and sets the copy's "AdjustExponent" property to the given value.
`EContext`	`WithBigExponentRange(EInteger exponentMin, EInteger exponentMax)` Copies this arithmetic context and sets the copy's exponent range.
`EContext`	`WithBigPrecision(EInteger bigintPrecision)` Copies this EContext and gives it a particular precision value.
`EContext`	`WithBlankFlags()` Copies this EContext with `HasFlags` set to true and a Flags value of 0.
`EContext`	`WithExponentClamp(boolean clamp)` Copies this arithmetic context and sets the copy's "ClampNormalExponents" flag to the given value.
`EContext`	`WithExponentRange(int exponentMinSmall, int exponentMaxSmall)` Copies this arithmetic context and sets the copy's exponent range.
`EContext`	`WithNoFlags()` Copies this EContext with `HasFlags` set to false and a Flags value of 0.
`EContext`	`WithPrecision(int precision)` Copies this EContext and gives it a particular precision value.
`EContext`	`WithPrecisionInBits(boolean isPrecisionBits)` Copies this EContext and sets the copy's "IsPrecisionInBits" property to the given value.
`EContext`	`WithRounding(ERounding rounding)` Copies this EContext with the specified rounding mode.
`EContext`	`WithSimplified(boolean simplified)` Copies this EContext and sets the copy's "IsSimplified" property to the given value.
`EContext`	`WithTraps(int traps)` Copies this EContext with Traps set to the given value.
`EContext`	`WithUnlimitedExponents()` Copies this EContext with an unlimited exponent range.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

- Field Detail
  - FlagClamped
```
public static final int FlagClamped
```
    Signals that the exponent was adjusted to fit the exponent range.
    
    See Also:
    
    Constant Field Values
  - FlagDivideByZero
```
public static final int FlagDivideByZero
```
    Signals a division of a nonzero number by zero.
    
    See Also:
    
    Constant Field Values
  - FlagInexact
```
public static final int FlagInexact
```
    Signals that the result was rounded to a different mathematical value, but as close as possible to the original.
    
    See Also:
    
    Constant Field Values
  - FlagInvalid
```
public static final int FlagInvalid
```
    Signals an invalid operation.
    
    See Also:
    
    Constant Field Values
  - FlagLostDigits
```
public static final int FlagLostDigits
```
    Signals that an operand was rounded to a different mathematical value before an operation.
    
    See Also:
    
    Constant Field Values
  - FlagOverflow
```
public static final int FlagOverflow
```
    Signals that the result is non-zero and the exponent is higher than the highest exponent allowed.
    
    See Also:
    
    Constant Field Values
  - FlagRounded
```
public static final int FlagRounded
```
    Signals that the result was rounded to fit the precision; either the value or the exponent may have changed from the original.
    
    See Also:
    
    Constant Field Values
  - FlagSubnormal
```
public static final int FlagSubnormal
```
    Signals that the result's exponent, before rounding, is lower than the lowest exponent allowed.
    
    See Also:
    
    Constant Field Values
  - FlagUnderflow
```
public static final int FlagUnderflow
```
    Signals that the result's exponent, before rounding, is lower than the lowest exponent allowed, and the result was rounded to a different mathematical value, but as close as possible to the original.
    
    See Also:
    
    Constant Field Values
  - Basic
```
public static final EContext Basic
```
    A basic arithmetic context, 9 digits precision, rounding mode half-up, unlimited exponent range. The default rounding mode is HalfUp.
  - BigDecimalJava
```
public static final EContext BigDecimalJava
```
    An arithmetic context for Java's BigDecimal format. The default rounding mode is HalfUp.
  - Binary128
```
public static final EContext Binary128
```
    An arithmetic context for the IEEE-754-2008 binary128 format, 113 bits precision. The default rounding mode is HalfEven.
  - Binary16
```
public static final EContext Binary16
```
    An arithmetic context for the IEEE-754-2008 binary16 format, 11 bits precision. The default rounding mode is HalfEven.
  - Binary32
```
public static final EContext Binary32
```
    An arithmetic context for the IEEE-754-2008 binary32 format, 24 bits precision. The default rounding mode is HalfEven.
  - Binary64
```
public static final EContext Binary64
```
    An arithmetic context for the IEEE-754-2008 binary64 format, 53 bits precision. The default rounding mode is HalfEven.
  - CliDecimal
```
public static final EContext CliDecimal
```
    An arithmetic context for the .NET Framework decimal format (see "Forms of numbers"), 96 bits precision, and a valid exponent range of -28 to 0. The default rounding mode is HalfEven. (The "Cli" stands for "Common Language Infrastructure", which defined this format as the .NET Framework decimal format in version 1, but leaves it unspecified in later versions.).
  - Decimal128
```
public static final EContext Decimal128
```
    An arithmetic context for the IEEE-754-2008 decimal128 format. The default rounding mode is HalfEven.
  - Decimal32
```
public static final EContext Decimal32
```
    An arithmetic context for the IEEE-754-2008 decimal32 format. The default rounding mode is HalfEven.
  - Decimal64
```
public static final EContext Decimal64
```
    An arithmetic context for the IEEE-754-2008 decimal64 format. The default rounding mode is HalfEven.
  - Unlimited
```
public static final EContext Unlimited
```
    No specific (theoretical) limit on precision. Rounding mode HalfUp.
  - UnlimitedHalfEven
```
public static final EContext UnlimitedHalfEven
```
    No specific (theoretical) limit on precision. Rounding mode HalfEven.
- Constructor Detail
  - EContext
```
public EContext(int precision,
                ERounding rounding,
                int exponentMinSmall,
                int exponentMaxSmall,
                boolean clampNormalExponents)
```
    Initializes a new instance of the EContext class. HasFlags will be set to false.
    
    Parameters:
    
    precision - The maximum number of digits a number can have, or 0 for an unlimited number of digits.
    
    rounding - The rounding mode to use when a number can't fit the given precision.
    
    exponentMinSmall - The minimum exponent.
    
    exponentMaxSmall - The maximum exponent.
    
    clampNormalExponents - Whether to clamp a number's significand to the given maximum precision (if it isn't zero) while remaining within the exponent range.
- Method Detail
  - getAdjustExponent
```
public final boolean getAdjustExponent()
```
    Gets a value indicating whether the EMax and EMin properties refer to the number's Exponent property adjusted to the number's precision, or just the number's Exponent property. The default value is true, meaning that EMax and EMin refer to the adjusted exponent. Setting this value to false (using WithAdjustExponent) is useful for modeling floating point representations with an integer mantissa (significand) and an integer exponent, such as Java's BigDecimal.
    
    Returns:
    
    true if the EMax and EMin properties refer to the number's Exponent property adjusted to the number's precision, or false if they refer to just the number's Exponent property.
  - getClampNormalExponents
```
public final boolean getClampNormalExponents()
```
    Gets a value indicating whether a converted number's Exponent property will not be higher than EMax + 1 - Precision. If a number's exponent is higher than that value, but not high enough to cause overflow, the exponent is clamped to that value and enough zeros are added to the number's mantissa (significand) to account for the adjustment. If HasExponentRange is false, this value is always false.
    
    Returns:
    
    If true, a converted number's Exponent property will not be higher than EMax + 1 - Precision.
  - getEMax
```
public final EInteger getEMax()
```
    Gets the highest exponent possible when a converted number is expressed in scientific notation with one digit before the radix point. For example, with a precision of 3 and an EMax of 100, the maximum value possible is 9.99E + 100. (This is not the same as the highest possible Exponent property.) If HasExponentRange is false, this value will be 0.
    
    Returns:
    
    The highest exponent possible when a converted number is expressed in scientific notation with one digit before the decimal point. For example, with a precision of 3 and an EMax of 100, the maximum value possible is 9.99E + 100. (This is not the same as the highest possible Exponent property.) If HasExponentRange is false, this value will be 0.
  - getEMin
```
public final EInteger getEMin()
```
    Gets the lowest exponent possible when a converted number is expressed in scientific notation with one digit before the radix point. For example, with a precision of 3 and an EMin of -100, the next value that comes after 0 is 0.001E-100. (If AdjustExponent is false, this property specifies the lowest possible Exponent property instead.) If HasExponentRange is false, this value will be 0.
    
    Returns:
    
    The lowest exponent possible when a converted number is expressed in scientific notation with one digit before the decimal point.
  - getFlags
```
public final int getFlags()
```
    Gets the flags that are set from converting numbers according to this arithmetic context. If HasFlags is false, this value will be 0. This value is a combination of bit fields. To retrieve a particular flag, use the AND operation on the return value of this method. For example: (this.getFlags() & EContext.FlagInexact) != 0 returns true if the Inexact flag is set.
    
    Returns:
    
    The flags that are set from converting numbers according to this arithmetic context. If. HasFlags is false, this value will be 0.
  - setFlags
```
public final void setFlags(int value)
```
  - getHasExponentRange
```
public final boolean getHasExponentRange()
```
    Gets a value indicating whether this context defines a minimum and maximum exponent. If false, converted exponents can have any exponent and operations can't cause overflow or underflow.
    
    Returns:
    
    true if this context defines a minimum and maximum exponent; otherwise, false.
  - getHasFlags
```
public final boolean getHasFlags()
```
    Gets a value indicating whether this context has a mutable Flags field.
    
    Returns:
    
    true if this context has a mutable Flags field; otherwise, false.
  - getHasMaxPrecision
```
public final boolean getHasMaxPrecision()
```
    Gets a value indicating whether this context defines a maximum precision.
    
    Returns:
    
    true if this context defines a maximum precision; otherwise, false.
  - isPrecisionInBits
```
public final boolean isPrecisionInBits()
```
    Gets a value indicating whether this context's Precision property is in bits, rather than digits. The default is false.
    
    Returns:
    
    true if this context's Precision property is in bits, rather than digits; otherwise, false. The default is false.
  - isSimplified
```
public final boolean isSimplified()
```
    Gets a value indicating whether to use a "simplified" arithmetic. In the simplified arithmetic, infinity, not-a-number, and subnormal numbers are not allowed, and negative zero is treated the same as positive zero. For further details, see http://speleotrove.com/decimal/dax3274.html
    
    Returns:
    
    true if a "simplified" arithmetic will be used; otherwise, false.
  - getPrecision
```
public final EInteger getPrecision()
```
    Gets the maximum length of a converted number in digits, ignoring the radix point and exponent. For example, if precision is 3, a converted number's mantissa (significand) can range from 0 to 999 (up to three digits long). If 0, converted numbers can have any precision.
    
    Returns:
    
    The maximum length of a converted number in digits, ignoring the radix point and exponent.
  - getRounding
```
public final ERounding getRounding()
```
    Gets the desired rounding mode when converting numbers that can't be represented in the given precision and exponent range.
    
    Returns:
    
    The desired rounding mode when converting numbers that can't be represented in the given precision and exponent range.
  - getTraps
```
public final int getTraps()
```
    Gets the traps that are set for each flag in the context. Whenever a flag is signaled, even if HasFlags is false, and the flag's trap is enabled, the operation will throw a TrapException.
    For example, if Traps equals FlagInexact and FlagSubnormal, a TrapException will be thrown if an operation's return value is not the same as the exact result (FlagInexact) or if the return value's exponent is lower than the lowest allowed (FlagSubnormal).
    
    Returns:
    
    The traps that are set for each flag in the context.
  - ForPrecision
```
public static EContext ForPrecision(int precision)
```
    Creates a new arithmetic context using the given maximum number of digits, an unlimited exponent range, and the HalfUp rounding mode.
    
    Parameters:
    
    precision - Maximum number of digits (precision).
    
    Returns:
    
    A context object for arbitrary-precision arithmetic settings.
  - ForPrecisionAndRounding
```
public static EContext ForPrecisionAndRounding(int precision,
                                               ERounding rounding)
```
    Creates a new EContext object initialized with an unlimited exponent range, and the given rounding mode and maximum precision.
    
    Parameters:
    
    precision - Maximum number of digits (precision).
    
    rounding - An ERounding object.
    
    Returns:
    
    A context object for arbitrary-precision arithmetic settings.
  - ForRounding
```
public static EContext ForRounding(ERounding rounding)
```
    Creates a new EContext object initialized with an unlimited precision, an unlimited exponent range, and the given rounding mode.
    
    Parameters:
    
    rounding - The rounding mode for the new precision context.
    
    Returns:
    
    A context object for arbitrary-precision arithmetic settings.
  - Copy
```
public EContext Copy()
```
    Initializes a new EContext that is a copy of another EContext.
    
    Returns:
    
    A context object for arbitrary-precision arithmetic settings.
  - ExponentWithinRange
```
public boolean ExponentWithinRange(EInteger exponent)
```
    Determines whether a number can have the given Exponent property under this arithmetic context.
    
    Parameters:
    
    exponent - An arbitrary-precision integer indicating the desired exponent.
    
    Returns:
    
    true if a number can have the given Exponent property under this arithmetic context; otherwise, false. If this context allows unlimited precision, returns true for the exponent EMax and any exponent less than EMax.
    
    Throws:
    
    NullPointerException - The parameter exponent is null.
  - toString
```
public String toString()
```
    Gets a string representation of this object. Note that the format is not intended to be parsed and may change at any time.
    
    Overrides:
    
    toString in class Object
    
    Returns:
    
    A string representation of this object.
  - WithAdjustExponent
```
public EContext WithAdjustExponent(boolean adjustExponent)
```
    Copies this EContext and sets the copy's "AdjustExponent" property to the given value.
    
    Parameters:
    
    adjustExponent - The new value of the "AdjustExponent" property for the copy.
    
    Returns:
    
    A context object for arbitrary-precision arithmetic settings.
  - WithBigExponentRange
```
public EContext WithBigExponentRange(EInteger exponentMin,
                                     EInteger exponentMax)
```
    Copies this arithmetic context and sets the copy's exponent range.
    
    Parameters:
    
    exponentMin - Desired minimum exponent (EMin).
    
    exponentMax - Desired maximum exponent (EMax).
    
    Returns:
    
    A context object for arbitrary-precision arithmetic settings.
    
    Throws:
    
    NullPointerException - The parameter exponentMin is null.
    
    NullPointerException - The parameter exponentMax is null.
  - WithBigPrecision
```
public EContext WithBigPrecision(EInteger bigintPrecision)
```
    Copies this EContext and gives it a particular precision value.
    
    Parameters:
    
    bigintPrecision - The parameter bigintPrecision is not documented yet.
    
    Returns:
    
    A context object for arbitrary-precision arithmetic settings.
    
    Throws:
    
    NullPointerException - The parameter bigintPrecision is null.
  - WithBlankFlags
```
public EContext WithBlankFlags()
```
    Copies this EContext with HasFlags set to true and a Flags value of 0.
    
    Returns:
    
    A context object for arbitrary-precision arithmetic settings.
  - WithExponentClamp
```
public EContext WithExponentClamp(boolean clamp)
```
    Copies this arithmetic context and sets the copy's "ClampNormalExponents" flag to the given value.
    
    Parameters:
    
    clamp - The parameter clamp is not documented yet.
    
    Returns:
    
    A context object for arbitrary-precision arithmetic settings.
  - WithExponentRange
```
public EContext WithExponentRange(int exponentMinSmall,
                                  int exponentMaxSmall)
```
    Copies this arithmetic context and sets the copy's exponent range.
    
    Parameters:
    
    exponentMinSmall - Desired minimum exponent (EMin).
    
    exponentMaxSmall - Desired maximum exponent (EMax).
    
    Returns:
    
    A context object for arbitrary-precision arithmetic settings.
  - WithNoFlags
```
public EContext WithNoFlags()
```
    Copies this EContext with HasFlags set to false and a Flags value of 0.
    
    Returns:
    
    A context object for arbitrary-precision arithmetic settings.
  - WithPrecision
```
public EContext WithPrecision(int precision)
```
    Copies this EContext and gives it a particular precision value.
    
    Parameters:
    
    precision - Desired precision. 0 means unlimited precision.
    
    Returns:
    
    A context object for arbitrary-precision arithmetic settings.
  - WithPrecisionInBits
```
public EContext WithPrecisionInBits(boolean isPrecisionBits)
```
    Copies this EContext and sets the copy's "IsPrecisionInBits" property to the given value.
    
    Parameters:
    
    isPrecisionBits - The new value of the "IsPrecisionInBits" property for the copy.
    
    Returns:
    
    A context object for arbitrary-precision arithmetic settings.
  - WithRounding
```
public EContext WithRounding(ERounding rounding)
```
    Copies this EContext with the specified rounding mode.
    
    Parameters:
    
    rounding - Desired value of the Rounding property.
    
    Returns:
    
    A context object for arbitrary-precision arithmetic settings.
  - WithSimplified
```
public EContext WithSimplified(boolean simplified)
```
    Copies this EContext and sets the copy's "IsSimplified" property to the given value.
    
    Parameters:
    
    simplified - The parameter simplified is not documented yet.
    
    Returns:
    
    A context object for arbitrary-precision arithmetic settings.
  - WithTraps
```
public EContext WithTraps(int traps)
```
    Copies this EContext with Traps set to the given value.
    
    Parameters:
    
    traps - Flags representing the traps to enable. See the property "Traps".
    
    Returns:
    
    A context object for arbitrary-precision arithmetic settings.
  - WithUnlimitedExponents
```
public EContext WithUnlimitedExponents()
```
    Copies this EContext with an unlimited exponent range.
    
    Returns:
    
    A context object for arbitrary-precision arithmetic settings.

Class EContext

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

FlagClamped

FlagDivideByZero

FlagInexact

FlagInvalid

FlagLostDigits

FlagOverflow

FlagRounded

FlagSubnormal

FlagUnderflow

Basic

BigDecimalJava

Binary128

Binary16

Binary32

Binary64

CliDecimal

Decimal128

Decimal32

Decimal64

Unlimited

UnlimitedHalfEven

Constructor Detail

EContext

Method Detail

getAdjustExponent

getClampNormalExponents

getEMax

getEMin

getFlags

setFlags

getHasExponentRange

getHasFlags

getHasMaxPrecision

isPrecisionInBits

isSimplified

getPrecision

getRounding

getTraps

ForPrecision

ForPrecisionAndRounding

ForRounding

Copy

ExponentWithinRange

toString

WithAdjustExponent

WithBigExponentRange

WithBigPrecision

WithBlankFlags

WithExponentClamp

WithExponentRange

WithNoFlags

WithPrecision

WithPrecisionInBits

WithRounding

WithSimplified

WithTraps

WithUnlimitedExponents