Next: , Previous: MPIR.Net Rationals, Up: .Net Interface   [Index]


13.5 MPIR.Net Floats

Class: HugeFloat : FloatExpression, IDisposable

The MPIR.Net class for multi-precision floating point numbers is HugeFloat, and its corresponding expression class is FloatExpression, which is returned from all operators and methods whose value semantics are to compute another number from the source instance and any arguments. HugeFloat derives from FloatExpression, and many operations are defined on the expression class. Operations defined on HugeFloat but not on FloatExpression are typically those that modify the value of the source number itself, and thus performing them on an expression is meaningless. Because through inheritance all operations are available on HugeFloat, the descriptions below do not specifically indicate whether each operator or method is defined for expressions, or just for HugeFloat instances. For the sake of brevity, they are listed as if they were methods of the HugeFloat class. Visual Studio provides Intellisense and immediate feedback to help sort out which operations are available on expressions.

Below is a brief summary of the supported multi-precision rational methods and operators. To avoid repetition, implementation details are ommitted. Since MPIR native functions are called behind the scenes, review Floating-point Functions for further details about the native implementations.

Static Property: static uint/ulong DefaultPrecision

Gets or sets the default precision of the floating point mantissa, in bits. If the value is not a multiple of limb size, the actual precision will be rounded up. All newly constructed HugeFloat objects that don’t explicitly specify precision will use this default. Previously constructed objects are unaffected. The initial default precision is 2 limbs.

When an expression is evaluated, it is either because it is being assigned to some destination variable (e.g. a.Value = b + c;) or a primitive-computing method is being called (e.g. int s = (b + c).Sign();) In the former case, the precision of the destination is used for all computations and temporaries during expression evaluation. In the latter case, there is no destination so the DefaultPrecision is used.

Constructor: HugeFloat ()
Constructor: HugeFloat (int/long value)
Constructor: HugeFloat (uint/ulong value)
Constructor: HugeFloat (double n)

Constructs a HugeFloat object. Single-limb constructors vary by architecture, 32-bit builds take int or uint arguments, 64-bit builds take long or ulong. Any necessary conversion follows the corresponding C function, for example double follows mpf_set_d (see Initializing Floats).

Constructor: HugeFloat (string s)
Constructor: HugeFloat (string s, int base)
Constructor: HugeFloat (string s, int base, bool exponentInDecimal)

Constructs a HugeFloat converted from a string using mpf_set_str (see Initializing Floats). If the string is not a valid integer or floating point number, an exception is thrown.

Constructor: HugeFloat (IntegerExpression value)
Constructor: HugeFloat (RationalExpression value)
Constructor: HugeFloat (FloatExpression value)

Evaluates the supplied expression and saves its result to the new instance. Because multi-precision classes are derived from their corresponding expression classes, these constructors can be used to make a copy of an existing variable, i.e. HugeFloat a = new HugeFloat(b); without creating any permanent association between them.

Static Method: static HugeRational Allocate (uint/ulong precision)
Method: void Reallocate (uint/ulong precision)

Controls the allocated precision in bits of the new or existing HugeFloat.

Property: uint/ulong AllocatedPrecision

Gets the precision in bits that is currently allocated for internal storage of the mantissa. The precision actually in effect, used in calculations, is initially the same but may be reduced by setting the Precision property.

Property: uint/ulong Precision

Gets or sets the effective precision of the number without changing the memory allocated. The number of bits cannot exceed the precision with which the variable was initialized or last reallocated. The value of the number is unchanged, and in particular if it previously had a higher precision it will retain that higher precision. New values assigned to the Value property will use the new precision. The number can be safely disposed after modifying its Precision (unlike the native MPIR, which requires you to restore the precision to the allocated value before the memory can be freed).

Method: bool FitsUlong () //64-bit builds only
Method: bool FitsLong () //64-bit builds only
Method: bool FitsUint ()
Method: bool FitsInt ()
Method: bool FitsUshort ()
Method: bool FitsShort ()

Checks whether the number would fit in one of the built-in .Net types.

Method: bool IsInteger ()

Checks whether the number is a whole integer.

Method: string ToString ()
Method: string ToString (int base)
Method: string ToString (int base, bool lowercase)
Method: string ToString (int base, bool lowercase, bool exponentInDecimal)

Returns the string representation of the number. The default base is 10, and the parameterless overload is limited to 256 mantissa digits by default. This is done to prevent huge numbers from unexpectedly consuming large amounts of memory in the debugger. The maximum number of digits output is configurable via the MpirSettings.ToStringDigits property, where zero means unlimited. MpirSettings.ToStringDigits applies to integers and rationals as well. The other overloads always output all digits.

Method: int ToInt () //32-bit builds
Method: uint ToUint () //32-bit builds
Method: long ToLong () //64-bit builds
Method: ulong ToUlong () //64-bit builds
Method: double ToDouble ()
Method: double ToDouble (out int/long exp)

Converts the number to a primitive (built-in) .Net type, assuming it fits, which can be determined by calling one of the Fits... methods.

Property: FloatExpression Value

Getting this property is essentially a no-op, as it returns the object instance itself. This never needs to be done explicitly, but is used implicitly in statements like a.Value += 5;

Setting the Value property evaluates the assigned expression and saves the result to the object.

Method: void SetTo (int/long value) // 32/64-bit builds
Method: void SetTo (uint/ulong value) // 32/64-bit builds
Method: void SetTo (double value)
Method: void SetTo (string value)
Method: void SetTo (string value, int base)
Method: void SetTo (string value, int base, bool exponentInDecimal)
Method: void SetTo (IntegerExpression value)
Method: void SetTo (RationalExpression value)

Sets the value of existing variable from types other than FloatExpression.

Method: void Swap (HugeFloat a)

Swaps the values (and precisions) of the two objects. This is an O(1) operation.

Arithmetic operators (+, -, *, /) and bit shifts (<<, >>) are overloaded to allow floats to participate in expressions much like primitive types can. Single-limb primitive types can be used. These operators do not accept integer or rational expressions. There is some cost of instantiating a floating point number from another multi-precision type, so to make this point clear MPIR.Net forces you to use explicit constructors or assignments for this conversion.

The modulo operator (%) and the bitwise operators (&, |, ^, ~) are not defined.

Operator ^ raises the source number to the specified power.

Comparison operators (==, !=, <, <=, >, >=) accept FloatExpression, single-limb, or double arguments, but do not accept integer or rational expressions because that would require an awkward explicit cast when comparing with null.

Method: int CompareTo (FloatExpression a)
Method: bool Equals (FloatExpression a)

Implement IComparable<FloatExpression> and IEquatable<FloatExpression> for strongly-typed comparisons.

Method: int CompareTo (object a)
Method: bool Equals (object a)

Implement IComparable and equality check for any object. These support only float expressions or .Net primitive types. When this method is called on a HugeFloat object, comparison is performed to the precision of the object. When called on an expression, comparison is performed to the default precision.

Method: int GetHashCode ()

This object override computes the hash code. This is an O(N) operation where N is the number of limbs allocated. Changing a number’s Value changes its hash code, so this should not be done on any object that has been added to a hash table or dictionary.

Method: bool Equals (object a, uint/ulong precision)

Checks for equality using the specified precision. The argument a can be a FloatExpression or a primitive type.

Method: FloatExpression RelativeDifferenceFrom (FloatExpression a)

Returns an expression that computes abs(this-a)/this

Method: FloatExpression Abs ()
Method: FloatExpression SquareRoot ()
Static Method: static FloatExpression SquareRoot (uint/ulong a)
Method: FloatExpression Floor ()
Method: FloatExpression Ceiling ()
Method: FloatExpression Truncate ()
Method: int Sign ()

Perform various floating-point operations.

Method: long Write (TextWriter writer)
Method: long Write (TextWriter writer, int base)
Method: long Write (TextWriter writer, int base, int maxDigits, bool lowercase, bool exponentInDecimal)
Method: long Read (TextReader reader)
Method: long Read (TextReader reader, int base)
Method: long Read (TextReader reader, int base, bool exponentInDecimal)

Writes and reads floats as text.


Next: , Previous: MPIR.Net Rationals, Up: .Net Interface   [Index]