Class EContext
- java.lang.Object
-
- com.upokecenter.numbers.EContext
-
public final class EContext extends java.lang.ObjectContains 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
Flagsproperty. If the context'sHasFlagsproperty (a read-only property) istrue, theFlagsproperty 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 theHasFlagsproperty set totruewill be shared among multiple threads and at least one of those threads needs to write theFlagsproperty (which can happen, for example, by passing the context to most methods ofEDecimalsuch asAdd).
-
-
Field Summary
Fields Modifier and Type Field Description static EContextBasicA basic arithmetic context, 9 digits precision, rounding mode half-up, unlimited exponent range.static EContextBigDecimalJavaAn arithmetic context for Java's BigDecimal format.static EContextBinary128An arithmetic context for the IEEE-754-2008 binary128 format, 113 bits precision.static EContextBinary16An arithmetic context for the IEEE-754-2008 binary16 format, 11 bits precision.static EContextBinary32An arithmetic context for the IEEE-754-2008 binary32 format, 24 bits precision.static EContextBinary64An arithmetic context for the IEEE-754-2008 binary64 format, 53 bits precision.static EContextCliDecimalAn 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 EContextDecimal128An arithmetic context for the IEEE-754-2008 decimal128 format.static EContextDecimal32An arithmetic context for the IEEE-754-2008 decimal32 format.static EContextDecimal64An arithmetic context for the IEEE-754-2008 decimal64 format.static intFlagClampedSignals that the exponent was adjusted to fit the exponent range.static intFlagDivideByZeroSignals a division of a nonzero number by zero.static intFlagInexactSignals that the result was rounded to a different mathematical value, but as close as possible to the original.static intFlagInvalidSignals an invalid operation.static intFlagLostDigitsSignals that an operand was rounded to a different mathematical value before an operation.static intFlagOverflowSignals that the result is non-zero and the exponent is higher than the highest exponent allowed.static intFlagRoundedSignals that the result was rounded to fit the precision; either the value or the exponent may have changed from the original.static intFlagSubnormalSignals that the result's exponent, before rounding, is lower than the lowest exponent allowed.static intFlagUnderflowSignals 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 EContextUnlimitedNo specific (theoretical) limit on precision.static EContextUnlimitedHalfEvenNo specific (theoretical) limit on precision.
-
Constructor Summary
Constructors Constructor Description EContext(int precision, ERounding rounding, int exponentMinSmall, int exponentMaxSmall, boolean clampNormalExponents)Initializes a new instance of theEContextclass.EContext(EInteger bigintPrecision, ERounding rounding, EInteger exponentMin, EInteger exponentMax, boolean clampNormalExponents)Initializes a new instance of theEContextclass, using arbitrary-precision integers to hold the precision and exponent range.
-
Method Summary
All Methods Static Methods Instance Methods Concrete Methods Modifier and Type Method Description EContextCopy()Initializes a new EContext that is a copy of another EContext.booleanExponentWithinRange(EInteger exponent)Determines whether a number can have the given Exponent property under this arithmetic context.static EContextForPrecision(int precision)Creates a new arithmetic context using the given maximum number of digits, an unlimited exponent range, and the HalfUp rounding mode.static EContextForPrecisionAndRounding(int precision, ERounding rounding)Creates a new EContext object initialized with an unlimited exponent range, and the given rounding mode and maximum precision.static EContextForRounding(ERounding rounding)Creates a new EContext object initialized with an unlimited precision, an unlimited exponent range, and the given rounding mode.booleangetAdjustExponent()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.booleangetClampNormalExponents()Gets a value indicating whether a converted number's Exponent property will not be higher than EMax + 1 - Precision.EIntegergetEMax()Gets the highest exponent possible when a converted number is expressed in scientific notation with one nonzero digit before the radix point.EIntegergetEMin()Gets the lowest exponent possible when a converted number is expressed in scientific notation with one nonzero digit before the radix point.intgetFlags()Gets the flags that are set from converting numbers according to this arithmetic context.booleangetHasExponentRange()Gets a value indicating whether this context defines a minimum and maximum exponent.booleangetHasFlags()Gets a value indicating whether this context has a mutable Flags field.booleangetHasFlagsOrTraps()Gets a value indicating whether this context has a mutable Flags field, one or more trap enablers, or both.booleangetHasMaxPrecision()Gets a value indicating whether this context defines a maximum precision.EIntegergetPrecision()Gets the maximum length of a converted number in digits, ignoring the radix point and exponent.ERoundinggetRounding()Gets the desired rounding mode when converting numbers that can't be represented in the given precision and exponent range.intgetTraps()Gets the traps that are set for each flag in the context.booleanisPrecisionInBits()Gets a value indicating whether this context's Precision property is in bits, rather than digits.booleanisSimplified()Gets a value indicating whether to use a "simplified" arithmetic.voidsetFlags(int value)java.lang.StringtoString()Gets a string representation of this object.EContextWithAdjustExponent(boolean adjustExponent)Copies this EContext and sets the copy's "AdjustExponent" property to the given value.EContextWithBigExponentRange(EInteger exponentMin, EInteger exponentMax)Copies this arithmetic context and sets the copy's exponent range.EContextWithBigPrecision(EInteger bigintPrecision)Copies this EContext and gives it a particular precision value.EContextWithBlankFlags()Copies this EContext withHasFlagsset to true and a Flags value of 0.EContextWithExponentClamp(boolean clamp)Copies this arithmetic context and sets the copy's "ClampNormalExponents" flag to the given value.EContextWithExponentRange(int exponentMinSmall, int exponentMaxSmall)Copies this arithmetic context and sets the copy's exponent range.EContextWithNoFlags()Copies this EContext withHasFlagsset to false and a Flags value of 0.EContextWithNoFlagsOrTraps()Copies this EContext withHasFlagsset to false, a Traps value of 0, and a Flags value of 0.EContextWithPrecision(int precision)Copies this EContext and gives it a particular precision value.EContextWithPrecisionInBits(boolean isPrecisionBits)Copies this EContext and sets the copy's "IsPrecisionInBits" property to the given value.EContextWithRounding(ERounding rounding)Copies this EContext with the specified rounding mode.EContextWithSimplified(boolean simplified)Copies this EContext and sets the copy's "IsSimplified" property to the given value.EContextWithTraps(int traps)Copies this EContext with Traps set to the given value.EContextWithUnlimitedExponents()Copies this EContext with an unlimited exponent range.
-
-
-
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 theEContextclass.- Parameters:
precision- Maximum precision, in decimal digits, of a number's significand.rounding- The rounding mode for this context.exponentMinSmall- Smallest exponent of a number, as a power of 10.exponentMaxSmall- Largest exponent of a number, as a power of 10.clampNormalExponents- The value of the "ClampNormalExponents" property for this context.
-
EContext
public EContext(EInteger bigintPrecision, ERounding rounding, EInteger exponentMin, EInteger exponentMax, boolean clampNormalExponents)
Initializes a new instance of theEContextclass, using arbitrary-precision integers to hold the precision and exponent range.- Parameters:
bigintPrecision- Maximum precision, in decimal digits, of a number's significand.rounding- The rounding mode for this context.exponentMin- Smallest exponent of a number, as a power of 10.exponentMax- Largest exponent of a number, as a power of 10.clampNormalExponents- The value of the "ClampNormalExponents" property for this context.
-
-
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:
trueif 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 nonzero 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 nonzero 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.
-
getEMin
public final EInteger getEMin()
Gets the lowest exponent possible when a converted number is expressed in scientific notation with one nonzero 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 nonzero 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.
-
getFlags
public final int getFlags()
Gets the flags that are set from converting numbers according to this arithmetic context. IfHasFlagsis 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) != 0returnstrueif the Inexact flag is set.- Returns:
- The flags that are set from converting numbers according to this
arithmetic context. If
HasFlagsis 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) != 0returnstrueif the Inexact flag is set.
-
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:
trueif this context defines a minimum and maximum exponent; otherwise,false.. If false, converted exponents can have any exponent and operations can't cause overflow or underflow.trueif 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:
trueif 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:
trueif 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:
trueif this context's Precision property is in bits, rather than digits; otherwise,false.. The default is false.trueif 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, seehttp://speleotrove.com/decimal/dax3274.html.- Returns:
trueif to use a "simplified" arithmetic; otherwise,falseIn 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 .trueif 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.Not-a-number (NaN) values can carry an optional number, its payload, that serves as its "diagnostic information", In general, if an operation requires copying an NaN's payload, only up to as many digits of that payload as the precision given in this context, namely the least significant digits, are copied.
- Returns:
- 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.
-
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 ifHasFlagsis false, and the flag's trap is enabled, the operation will throw a TrapException.For example, if Traps equals
FlagInexactand 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. Whenever a flag
is signaled, even if
HasFlagsis false, and the flag's trap is enabled, the operation will throw a TrapException. For example, if Traps equals .
-
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- The parameterroundingis 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:
trueif 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:
java.lang.NullPointerException- The parameterexponentis null.
-
toString
public java.lang.String toString()
Gets a string representation of this object. Note that the string's format is not intended to be parsed and may change at any time.- Overrides:
toStringin classjava.lang.Object- Returns:
- A string representation of this object.
-
getHasFlagsOrTraps
public final boolean getHasFlagsOrTraps()
Gets a value indicating whether this context has a mutable Flags field, one or more trap enablers, or both.- Returns:
trueif this context has a mutable Flags field, one or more trap enablers, or both; otherwise,false.
-
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:
java.lang.NullPointerException- The parameterexponentMinis null.java.lang.IllegalArgumentException- ExponentMin greater than exponentMax".
-
WithNoFlagsOrTraps
public EContext WithNoFlagsOrTraps()
Copies this EContext withHasFlagsset to false, a Traps value of 0, and a Flags value of 0.- Returns:
- A context object for arbitrary-precision arithmetic settings.
-
WithBigPrecision
public EContext WithBigPrecision(EInteger bigintPrecision)
Copies this EContext and gives it a particular precision value.- Parameters:
bigintPrecision- Desired precision. 0 means unlimited precision.- Returns:
- A context object for arbitrary-precision arithmetic settings.
- Throws:
java.lang.NullPointerException- The parameterbigintPrecisionis null.
-
WithBlankFlags
public EContext WithBlankFlags()
Copies this EContext withHasFlagsset 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 desired value of the "ClampNormalExponents" flag.- 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 withHasFlagsset 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- Desired value of the IsSimplified property.- 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. (Also sets HasFlags on the copy toTrue, but this may change in version 2.0 of this library.).- 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.
-
-