BigFloat

The BigFloat class allows you to create and manipulate floating-point numbers of arbitrary size and precision.

The BigFloat class stores a single floating-point number as x = M · 10^exponent where M is the mantissa stored as a BigInteger, and exponent is a long integer. The mantissa has a default precision of up to 30 digits (plus the sign), but this can be increased to a maximum of 1000 digits. The exponent can range from -1000000 to +1000000.

All math operations involving BigFloat numbers work by operating on the mantissa and exponent separately. Since all of the basic math operations for BigInteger are written in C code, these are highly performant. However, the BigFloat class and many of its methods are written in the IDL language. You can find the source code in the file lib/datatypes/bigfloat__define.pro in your IDL installation.

Examples

Constructors

You can create BigFloats from regular numbers or from strings. For example, all of the following statements produce the same BigFloat value:

b = BigFloat(3.14d)

b = -BigFloat('3.14')

b = BigFloat(314, -2)

Tip: Due to IEEE precision limits, you should be careful creating BigFloats from floating-point numbers. For example, BigFloat(0.1) is not equal to BigFloat('0.1'). It is almost always better to use a string or separate out the mantissa and exponent. For example, instead of BigFloat(0.1), use BigFloat('0.1') or BigFloat(1, -1).

You can also use keywords to create BigFloats with special values. For example:

b = BigFloat(/infinity)

c = BigFloat(/infinity, /negative)

d = BigFloat(/nan)

Math Expressions

You can use BigFloats in mathematical expressions in combination with other BigFloats, BigIntegers, or regular numbers. For example, let's compute the Rydberg constant:

IDL> fine_struct = 1 / BigFloat('137.035999177')

IDL> bohr_radius = BigFloat('5.29177210544e-11')

IDL> rydberg = fine_struct / (4 * BigFloat.pi * bohr_radius)

IDL> rydberg

10973731.5681425741417208047492

BigFloat Constructor

Syntax

Result = BigFloat( Value )

Result = BigFloat( Value, Exponent )

Result = BigFloat( /INFINITY, /NEGATIVE, /NAN )

Return Value

Returns a reference to the newly-created BigFloat.

Arguments

Value

Set this argument to an integer, BigInteger, float, or string representing the BigFloat mantissa (and possibly the exponent). For floats or strings the value may be written in scientific notation. For example, BigFloat(1e23) or BigFloat('1e23').

Exponent

Set this optional argument to a positive or negative integer containing the exponent. Exponent may be in the range -1000000 to +1000000. If Value is a float which already contains an exponent, then this Exponent is combined with it. If Value is a string then an error will be thrown if this argument is supplied.

Keywords

INFINITY

Set this keyword to return a special BigFloat infinity value. This may be combined with the NEGATIVE keyword to return negative infinity.

NAN

Set this keyword to return a special BigFloat "not a number" value.

NEGATIVE

Set this keyword in combination with the INFINITY keyword to return a special BigFloat negative infinity value.

Properties

You can retrieve the following properties using "dot" notation. For example:

IDL> b = -BigFloat(2)^10000

IDL> help, b.mantissa

IDL> help, b.exponent

IDL> help, b.negative

<Expression>    BIGINTEGER <ID=542253 LENGTH=364 bits> = 0.19950631168807584...x10^109

<Expression>    LONG      =         2901

<Expression>    BOOLEAN   = true (1)

Note: BigFloat objects are immutable: You cannot set the MANTISSA or EXPONENT properties.

MANTISSA

This property contains a BigInteger representing the mantissa.

EXPONENT

This property contains an integer representing the exponent.

INFINITY

This property is a boolean indicating whether the BigFloat is infinity (either positive or negative).

NAN

This property is a boolean indicating whether the BigFloat is the special "not a number" value.

NEGATIVE

This property is a boolean indicating whether the BigFloat is negative (either negative infinity or a negative value).

PRECISION

Get this property to retrieve the current precision value for all BigFloat calculations. You can use the SetPrecision method to change the precision.

PI

This property retrieves a BigFloat containing the value of Pi. To improve the accuracy of computations, the returned value will have 10 extra digits of precision compared to the current precision level.

BigFloat::Abs

The BigFloat::Abs method returns the absolute value of the number.

Example

IDL> x = BigFloat(-100)

IDL> help, x.Abs()

<Expression>    BIGFLOAT <ID=7516> = 100

Syntax

Result = bigfloat.Abs( )

Return Value

Returns a BigFloat containing the absolute value.

Arguments

None

Keywords

None

BigFloat::Cos

The BigFloat::Cos method uses a Taylor series expansion to compute the cosine of the number.

Example

IDL> x = BigFloat(0.5)

IDL> x.cos()

0.877582561890372716116281582604

IDL> x = BigFloat(45)

IDL> x.cos(/degrees)

0.707106781186547524400844362105

Syntax

Result = bigfloat.Cos( /DEGREES )

Return Value

Returns a BigFloat containing the cosine of bigfloat. The bigfloat number is assumed to be in radians unless the DEGREES keyword is set.

Arguments

None

Keywords

None

BigFloat::Exp

The BigFloat::Exp method uses a Taylor series expansion to compute the exponential of the number.

Example

IDL> x = BigFloat(100)

IDL> x.Exp()

2.68811714181613544841262555158e43

IDL> x = BigFloat('1e-10')

IDL> x.Exp()

1.000000000100000000005

Syntax

Result = bigfloat.Exp( )

Return Value

Returns a BigFloat containing the exponential.

Arguments

None

Keywords

DEGREES

By default the big float is assumed to be in radians. Set the DEGREES keyword to indicate that the big float is in degrees.

BigFloat::Log

The BigFloat::Log method uses the arctanh expansion to compute the natural logarithm of the number. If the number is negative then BigFloat(NaN) is returned.

Example

IDL> x = BigFloat('1e1000')

IDL> x.log()

2302.58509299404568401799145468

Syntax

Result = bigfloat.Log( )

Return Value

A BigFloat equal to the natural logarithm.

Arguments

None

Keywords

None

BigFloat::Log2

The BigFloat::Log2 method returns the base-2 logarithm of the number. If the number is negative then BigFloat(NaN) is returned.

Example

IDL> x = BigFloat('1e1000')

IDL> x.log2()

3321.92809488736234787031942949

Syntax

Result = bigfloat.Log2( )

Return Value

A BigFloat equal to the base-2 logarithm.

Arguments

None

Keywords

None

BigFloat::Log10

The BigFloat::Log10 method returns the base-10 logarithm of the number. If the number is negative then BigFloat(NaN) is returned.

Example

pi = BigFloat.Pi

PRINT, pi.Log10()

IDL prints:

0.497149872694133854351268288291

Syntax

Result = bigfloat.Log10( )

Return Value

A BigFloat equal to the base-10 logarithm.

Arguments

None

Keywords

None

BigFloat::SetPrecision

The BigFloat::SetPrecision static method sets the number of digits of precision for all BigFloat calculations. The default is 30 digits.

Syntax

BigFloat.SetPrecision, value

Arguments

Value

Set this argument to an integer giving the digits of precision for all future calculations. The default is 30, and the valid range is between 30 and 1000.

Keywords

None

BigFloat::Signum

The BigFloat::Signum method returns –1 if the number is negative, 0 if the number is zero, and 1 if the number is positive.

Syntax

Result = bigfloat.Signum( )

Return Value

Returns –1, 0, or +1.

Arguments

None

Keywords

None

BigFloat::Sin

The BigFloat::Sin method uses a Taylor series expansion to compute the sine of the number.

Example

IDL> x = BigFloat(0.5)

IDL> x.sin()

0.479425538604203000273287935216

IDL> x = BigFloat(45)

IDL> x.sin(/degrees)

0.707106781186547524400844362105

Syntax

Result = bigfloat.Sin( /DEGREES )

Return Value

Returns a BigFloat containing the sine of bigfloat. The bigfloat number is assumed to be in radians unless the DEGREES keyword is set.

Arguments

None

Keywords

None

BigFloat::Sqrt

The BigFloat::Sqrt method uses Newton's iterative method to compute the square root of the number. If the number is negative then BigFloat(NaN) is returned.

Example

IDL> BigFloat.SetPrecision, 100

IDL> x = BigFloat(2)

IDL> x.Sqrt()

1.414213562373095048801688724209698078569671875376948073176679737990732478462107038850387534327641573

Syntax

Result = bigfloat.Sqrt( REMAINDER=variable )

Return Value

Returns a BigFloat containing the square root.

Arguments

None

Keywords

None

BigFloat::Tan

The BigFloat::Sin method uses a Taylor series expansion to compute the tangent of the number.

Example

IDL> x = BigFloat(1)

IDL> x.tan()

1.55740772465490223050697480746

IDL> x = BigFloat(45)

IDL> x.tan(/degrees)

Syntax

Result = bigfloat.Tan( /DEGREES )

Return Value

Returns a BigFloat containing the tangent of bigfloat. The bigfloat number is assumed to be in radians unless the DEGREES keyword is set.

Arguments

None

Keywords

None

BigFloat::ToDouble

The BigFloat::ToDouble method converts the number to a double-precision value. If the BigFloat is too small or large, then toDouble returns zero or Infinity.

Examples

IDL> x = BigFloat('303117847695258070278031236')

IDL> x.toDouble()

3.0311784769525807e+26

IDL> y = BigFloat(x.toDouble()) ; we will lose precision

IDL> y.toString(/EXPONENTIAL)

303117847695258080000000000

DL> x = BigFloat('3e500')

IDL> x.toDouble()

Infinity

IDL> x = BigFloat('3e-500')

IDL> x.toDouble()

0.0000000000000000

Syntax

Result = bigfloat.ToDouble( EXPONENT=variable )

Return Value

Returns a double-precision value.

Arguments

None

Keywords

None

BigFloat::ToInteger

The BigFloat::ToInteger method converts the BigFloat to a signed 64-bit integer value. If the value is greater than 9223372036854775807 (or is +Infinity) then IDL will return that value. Similarly, if the value is less than –9223372036854775807 (or is –Infinity) then IDL will return that value. If the value is NaN then IDL will return –9223372036854775808.

Examples

The largest power of two that will still fit in a 64-bit integer without rolling over:

IDL> x = BigFloat(2)^62

IDL> x.toInteger()

4611686018427387904

Syntax

Result = bigfloat.ToInteger( )

Return Value

Returns a 64-bit signed integer value.

Arguments

None

Keywords

None

BigFloat::ToString

The BigFloat::ToString method converts the BigFloat to its string representation.

Examples

IDL> x = BigFloat('303117847695258070278031236')

IDL> x.toString()

303117847695258070278031236

IDL> x.toString(/EXPONENTIAL)

3.03117847695258070278031236000e26

IDL> x = BigFloat(1)

IDL> x.toString()

IDL> x.toString(/EXPONENTIAL)

1.00000000000000000000000000000e0

Syntax

Result = bigfloat.ToString( /EXPONENTIAL )

Return Value

Returns the string representation of the number.

Arguments

None

Keywords

EXPONENTIAL

By default, the toString method prints the number with the smallest number of necessary digits, using normal notation for numbers smaller than the BigFloat precision (default 30 digits), and scientific notation for larger numbers. Any trailing zeroes are dropped. Set the EXPONENTIAL keyword to always use scientific notation when converting the number to a string, and always keep trailing zeroes.

Additional Information

Operators

Name	Operators	Operands	Result
Math	+ – * / ^ mod	BigFloats, BigIntegers, or numbers	A new BigFloat
Increment, Decrement	++ ––	BigFloat	The BigFloat is incremented or decremented
Comparisons	EQ, NE, GT, GE, LT, LE	BigFloats, BigIntegers, or numbers	Boolean 0 or 1
Bitwise	AND	BigFloats, BigIntegers, or numbers	If arg1 not zero, then BigFloat(arg2), otherwise BigFloat(0)
	OR	BigFloats, BigIntegers, or numbers	If arg1 not zero, then BigFloat(arg1), otherwise BigFloat(arg2)
	NOT	BigFloat	BigFloat(0) or BigFloat(1)
	XOR	N/A	Illegal for BigFloat
Min/max	> <	BigFloats, BigIntegers, or numbers	A new BigFloat

Logical Truth and Negation

A BigFloat is considered "true" if the value is not zero, otherwise it is false. The "~" negation operator will return a boolean 0 if the BigFloat was nonzero, or 1 if the BigFloat was zero.

Help and Print

The PRINT procedure will output the BigFloat value to as many digits as necessary.

The HELP procedure will output the BigFloat's heap ID and a shortened version of the BigFloat value.

ISA and TYPENAME

You can use the ISA function to determine if a variable is a BigFloat:

if ISA(value, "BigFloat") then ...

You can use the TYPENAME function or the TYPENAME attribute to retrieve the class name:

if (TYPENAME(value) eq "BIGFLOAT") then ...

if (value.TYPENAME eq "BIGFLOAT") then ...

Copying BigFloats

If you assign a BigFloat variable to a new variable, you are creating a new reference to the same object. Since BigFloats are immutable (the value cannot be changed) this is usually not a problem. If for some reason you must have a new object, you can use the DIGITS and SIGN properties to create a new BigFloat. For example:

b = BigFloat(2)^1279 - 1

c = b

d = BigFloat(b.toString())

HELP, b, c, d

IDL prints:

B               BIGFLOAT <ID=356> = 1.040793219466439908...e385

C               BIGFLOAT <ID=356> = 1.040793219466439908...e385

D               BIGFLOAT <ID=362> = 1.040793219466439908...e385

Notice that both b and c have the same heap variable ID, while d has a new heap ID.

Precision

When you first construct a BigFloat number, the number retains all of the digits that you provide. As soon as any math operation is performed, then the precision is reduced to the current value of the BigFloat precision. If you want to perform calculations using a precision higher than the default value of 30 digits, you should call the SetPrecision method before doing any computations. The precision is a global value that affects all BigFloat calculations.

For example:

IDL> pi = BigFloat.pi

IDL> print, pi ; default precision is 30 digits + 10 digits for extra precision

3.141592653589793238462643383279502884197

IDL> print, pi + 0 ; we did some math, so the precision is clamped down to 30 digits

3.14159265358979323846264338328

Now let's increase the precision to 50, create a new number with 70 significant digits, and do some math:

IDL> BigFloat.SetPrecision, 50

IDL> x = BigFloat("1234567890123456789012345678901234567890123456789012345678901234567890")

IDL> print, x

1.23456789012345678901234567890123456789012345678901234567890123456789e69

IDL> print, strlen(x.toString()) ; note that we still have all 70 digits

IDL> y = x + 1

IDL> print, y

1.234567890123456789012345678901234567890123456789e69

IDL> print, strlen(y.toString()) ; back down to 50 digits of precision

Version History

9.3	Introduced

BigFloat

Examples

Constructors

Math Expressions

Static Constructors

Methods

Additional Information

BigFloat Constructor

Syntax

Return Value

Arguments

Value

Exponent

Keywords

INFINITY

NAN

NEGATIVE

Properties

MANTISSA

EXPONENT

INFINITY

NAN

NEGATIVE

PRECISION

PI

BigFloat::Abs

Example

Syntax

Return Value

Arguments

Keywords

BigFloat::Cos

Example

Syntax

Return Value

Arguments

Keywords

BigFloat::Exp

Example

Syntax

Return Value

Arguments

Keywords

DEGREES

BigFloat::Log

Example

Syntax

Return Value

Arguments

Keywords

BigFloat::Log2

Example

Syntax

Return Value

Arguments

Keywords

BigFloat::Log10

Example

Syntax

Return Value

Arguments

Keywords

BigFloat::SetPrecision

Syntax

Arguments

Value

Keywords

BigFloat::Signum

Syntax

Return Value

Arguments

Keywords

BigFloat::Sin

Example

Syntax

Return Value

Arguments

Keywords

BigFloat::Sqrt

Example