XUIMaths

Description

This module exposes a wide range of mathematical methods.

Properties

Name	Type	Read-Only
DOUBLE_EXP_BIAS	`Int32`	✔
DOUBLE_EXP_BIT_MASK	`Int64`	✔
DOUBLE_MAX_EXPONENT	`Int32`	✔
DOUBLE_MIN_EXPONENT	`Int32`	✔
DOUBLE_MIN_SUB_EXPONENT	`Int32`	✔
DOUBLE_SIGNIFICAND_WIDTH	`Int32`	✔
DOUBLE_SIGNIF_BIT_MASK	`Int64`	✔
DOUBLE_SIGN_BIT_MASK	`Int64`	✔
Epsilon	`Double`	✔
NAN	`Double`	✔
NEGATIVE_INFINITY	`Double`	✔
POSITIVE_INFINITY	`Double`	✔
TWO_PI	`Double`	✔
TWO_TO_THE_DOUBLE_SCALE_DOWN	`Double`	✔
TWO_TO_THE_DOUBLE_SCALE_UP	`Double`	✔

Methods

Name	Parameters	Returns
Assert	condition As `Boolean`, message As `String`
BitsToDouble	bits As `Int64`	`Double`
Clamp	value As `Double`, minimum As `Double`, maximum As `Double`	`Double`
CoinToss	trueBias As `Double`	`Boolean`
Compare	d1 As `Double`, d2 As `Double`	`Integer`
ComputeEpsilon		`Double`
CopySign	magnitude As `Double`, sign As `Double`	`Double`
CubeRoot	d As `Double`	`Double`
DoubleToBits	d As `Double`	`Int64`
DoubleToRawBits	d As `Double`	`Int64`
GetExponent	d As `Double`	`Int32`
HalfPlaneSign	p1 As `Point`, p2 As `Point`, p3 As `Point`	`Double`
Hypotenuse	x As `Double`, y As `Double`	`Double`
IsCloseTo	d1 As `Double`, d2 As `Double`, decimalPoints As `Integer`	`Boolean`
IsEven	i As `Integer`	`Boolean`
IsInteger	d As `Double`	`Boolean`
IsOdd	i As `Integer`	`Boolean`
IsZero	d As `Double`	`Boolean`
Lerp	a As `Double`, b As `Double`, f As `Double`	`Double`
LShift32	v As `Int32`, s As `Integer`	`Int32`
LShift64	v As `Int64`, s As `Integer`	`Int64`
Modulo	a As `Integer`, b As `Integer`	`Integer`
NextDown	d As `Double`	`Double`
NextUp	d As `Double`	`Double`
NumberOfLeadingZeros	i As `Int64`	`Int32`
NumberOfTrailingZeros	i As `Int64`	`Int32`
PointInTriangle	p As `Point`, v1 As `Point`, v2 As `Point`, v3 As `Point`	`Boolean`
PowerOfTwoD	n As `Int32`	`Double`
Random	low As `Double`, high As `Double`	`Double`
RShift	v As `Int64`, s As `Integer`	`Int64`
RShiftU32	v As `Int32`, s As `Integer`	`Int32`
RShiftU64	v As `Int64`, shift As `Integer`	`Int64`
Scalb	d As `Double`, scaleFactor As `Integer`	`Double`
Signum	d As `Double`	`Double`
ToBinaryString	currencyValue As `Currency`	`String`
ToBinaryString	doubleValue As `Double`	`String`
ToBinaryString	i16 As `Int16`	`String`
ToBinaryString	i32 As `Int32`	`String`
ToBinaryString	i64 As `Int64`	`String`
ToBinaryString	i8 As `Int8`	`String`
ToBinaryString	singleValue As `Single`	`String`
ToBinaryString	i16 As `UInt16`	`String`
ToBinaryString	i32 As `UInt32`	`String`
ToBinaryString	i64 As `UInt64`	`String`
ToBinaryString	i8 As `UInt8`	`String`
ToDegrees	radians As `Double`	`Double`
ToRadians	degrees As `Double`	`Double`
WrapInteger	i As `Integer`, maxValue As `Integer`	`Integer`

Constants

Name	Type
DOUBLE_MAX_VALUE	`Double`
DOUBLE_MIN_NORMAL	`Double`
DOUBLE_MIN_VALUE	`Double`
INT32_MAX_VALUE	`Double`
INT32_MIN_VALUE	`Double`
INT64_MAX_VALUE	`Double`
PI	`Double`

DOUBLE_MAX_VALUE As Double The largest positive finite value of type Double.

DOUBLE_MIN_NORMAL As Double The smallest positive normal Double value, 2^-1022. It's equal to MathsKit.BitsToDouble(&h0010000000000000).

DOUBLE_MIN_VALUE As Double The smallest positive non-zero value of type Double: 2^-1074.

INT32_MAX_VALUE As Double The maximum value of an Int32.

INT32_MIN_VALUE As Double The minimum value of an Int32.

INT64_MAX_VALUE As Double The maximum value of an Int64.

PI As Double The value of π to 11 decimal places.

Property Descriptions

DOUBLE_EXP_BIAS As Int32

Bias used in representing a Double exponent.

DOUBLE_EXP_BIT_MASK As Int64

Bit mask to isolate the exponent field of a Double.

DOUBLE_MAX_EXPONENT As Int32

Maximum exponent a finite Double variable may have. It is equal to the value returned by MathsKit.GetExponent(DOUBLE_MAX_VALUE).

DOUBLE_MIN_EXPONENT As Int32

Minimum exponent a normalised Double variable may have. It is equal to the value returned by MathsKit.GetExponent(DOUBLE_MIN_NORMAL).

DOUBLE_MIN_SUB_EXPONENT As Int32

The exponent the smallest positive Double subnormal value would have if it could be normalised.

DOUBLE_SIGNIFICAND_WIDTH As Int32

The width (in bits) of the significand of a double.

DOUBLE_SIGNIF_BIT_MASK As Int64

Bit mask to isolate the significand field of a Double.

DOUBLE_SIGN_BIT_MASK As Int64

Bit mask to isolate the sign bit of a Double.

Epsilon As Double

An approximation of machine epsilon.

NAN As Double

Returns NaN (not a number).

NEGATIVE_INFINITY As Double

The value of negative infinity.

POSITIVE_INFINITY As Double

The value of positive infinity.

TWO_PI As Double

A precomputed value of 2 * π.

TWO_TO_THE_DOUBLE_SCALE_DOWN As Double

A constant used in Scalb().

TWO_TO_THE_DOUBLE_SCALE_UP As Double

A constant used in Scalb().

Method Descriptions

Assert(condition As Boolean, message As String)

Asserts that condition is True, otherwise raises an exception.

BitsToDouble(bits As Int64) As Double

Returns the double value corresponding to a given bit representation.

The argument is considered to be a representation of a floating-point value according to the IEEE 754 floating-point "double format" bit layout.

If the argument is &h7ff0000000000000L, the result is positive infinity. If the argument is &hfff0000000000000, the result is negative infinity. If the argument is any value in the range &h7ff0000000000001 through &h7fffffffffffffff or in the range &hfff0000000000001 through &hffffffffffffffff, the result is a NaN.

No IEEE 754 floating-point operation can distinguish between two NaN values of the same type with different bit patterns. Distinct values of NaN are only distinguishable by use of the DoubleToRaw method.

In all other cases, let s, e, and m be three * values that can be computed from the argument:

 int s = ((bits >> 63) = 0) ? 1 : -1
 int e = (int)((bits >> 52) & 0x7ffL)
 long m = (e = 0) ?
                (bits & 0xfffffffffffffL) << 1 :
                (bits & 0xfffffffffffffL) | 0x10000000000000L

Then the floating-point result equals the value of the mathematical expression s·m·2^e-1075

Note that this method may not be able to return double NaN with exactly the same bit pattern as the argument. IEEE 754 distinguishes between two kinds of NaNs, quiet NaNs and signaling NaNs. The differences between the two kinds of NaN are generally not visible. Arithmetic operations on signaling NaNs turn them into quiet NaNs with a different, but often similar, bit pattern. However, on some processors merely copying a signaling NaN also performs that conversion. In particular, copying a signaling NaN to return it to the calling method may perform this conversion. So BitsToDouble may not be able to return a double with a signaling NaN bit pattern. Consequently, for some UInt64 values, DoubleToRawBits(BitsToDouble(start)) may not equal start. Moreover, which particular bit patterns represent signaling NaNs is platform dependent although all NaN bit patterns, quiet or signaling, must be in the NaN range identified above.

Clamp(value As Double, minimum As Double, maximum As Double) As Double

Returns the passed value clamped between minimum and maximum.

CoinToss(trueBias As Double) As Boolean

Returns True or False.

Simulates a coin toss by returning a random boolean. The optional trueBias determines the chance of True being returned. This value should be between 0 and 1. If 0 then there is a 0% chance that True will be returned, if 1 then the chance is 100%.

Compare(d1 As Double, d2 As Double) As Integer

Compares the two specified double values.

The value 0 if d1 is numerically equal to d2, a value less than 0 if d1 is numerically less than d2 and a value greater than 0 if d1 is numerically greater than d2.

ComputeEpsilon() As Double

Computes an approximation of machine epsilon.

CopySign(magnitude As Double, sign As Double) As Double

Returns magnitude with the sign of sign.

CubeRoot(d As Double) As Double

Returns the cube root of d.

If the argument is NaN, then the result Is NaN. If the argument is infinite, Then the result is an infinity with the same sign as the argument. If the argument is zero, then the result is a zero with the same sign as the argument. For positive finite x, Cbrt(-x) = -cbrt(x) That is, the cube root of a negative value is the negative of the cube root of that value's magnitude.

DoubleToBits(d As Double) As Int64

Returns a representation of d according to the IEEE 754 floating-point "double format" bit layout.

Bit 63 (the bit that is selected by the mask 0x8000000000000000) represents the sign of the double number. Bits 62-52 (the bits that are selected by the mask 0x7ff0000000000000) represent the exponent. Bits 51-0 (the bits that are selected by the mask 0x000fffffffffffff) represent the significand (sometimes called the mantissa) of the floating-point number.

If the argument is positive infinity, the result is &h7ff0000000000000. If the argument is negative infinity, the result is &hfff0000000000000. If the argument is NaN, the result is &h7ff8000000000000.

In all cases, the result is an Int64 integer that, when given to the BitsToDouble(UInt64) method, will produce a Double the same as the

DoubleToRawBits(d As Double) As Int64

Returns a representation of d according to the IEEE 754 floating-point "double format" bit layout, preserving NaN values.

Bit 63 (the bit that is selected by the mask &h8000000000000000) represents the sign of the floating-point number. Bits 62-52 (the bits that are selected by the mask &h7ff0000000000000) represent the exponent. Bits 51-0 (the bits that are selected by the mask &h000fffffffffffff) represent the significand (sometimes called the mantissa) of the floating-point number.

If the argument is positive infinity, the result is &h7ff0000000000000. If the argument is negative infinity, the result is &hfff0000000000000. If the argument is NaN, the result is the Int64 integer representing the actual NaN value. Unlike the DoubleToBits method, this method does not collapse all the bit patterns encoding a NaN to a single "canonical" NaN value.

In all cases, the result is a UInt64 integer that, when given to the BitsToDouble(Int64) method, will produce a floating-point value the same as d.

GetExponent(d As Double) As Int32

Returns the unbiased exponent used in the representation of d.

If the argument is NaN or infinite, then the result is MAX_EXPONENT + 1.
If the argument is zero or subnormal, then the result is MIN_EXPONENT - 1.

HalfPlaneSign(p1 As Point, p2 As Point, p3 As Point) As Double

Part of the PointInTriangle algorithm.

See here.

Hypotenuse(x As Double, y As Double) As Double

Returns the hypotenuse (sqrt(x2 +y2)) without intermediate overflow or underflow.

Adapted from: here.

Special cases:

If either argument is infinite, then the result is positive infinity.
If either argument is NaN and neither argument is infinite, then the result is NaN.

The computed result must be within 1 ulp of the exact result. If one parameter is held constant, the results must be semi-monotonic in the other parameter.

IsCloseTo(d1 As Double, d2 As Double, decimalPoints As Integer) As Boolean

Returns True if the arguments are "close enough" to be considered equal.

Thanks to Graham Busch.

decimalPoints is the number of decimal points of accuracy.

IsEven(i As Integer) As Boolean

Returns True if i is even.

IsInteger(d As Double) As Boolean

Returns True if d is a whole number.

IsOdd(i As Integer) As Boolean

Returns True if i is odd.

IsZero(d As Double) As Boolean

Returns True if d is considered to be zero.

Exists as a workaround to the buggy Xojo Double.Equals method.

Returns True if d is within Tolerance of 0.0.

Based on code by Graham Busch.

Modified from the code in IsCloseTo.

Lerp(a As Double, b As Double, f As Double) As Double

Linearly interpolates between a and b by the fraction f.

Assumes f is clamped between 0 and 1.

LShift32(v As Int32, s As Integer) As Int32

Shifts left the 32-bit bit pattern of v by s bits.

Equivalent to Java's int << x operator.

LShift64(v As Int64, s As Integer) As Int64

Shifts left the 64-bit bit pattern of v by s bits.

Equivalent to Java's int << x operator.

Modulo(a As Integer, b As Integer) As Integer

Returns the remainder of a/b yielding a result with the same sign as b.

Credit here.

Functions like Python's % operator.

NextDown(d As Double) As Double

Returns the floating-point value adjacent to d in the direction of negative infinity.

If the argument is NaN, the result is NaN. If the argument is negative infinity, the result is negative infinity. If the argument is zero, the result is -DOUBLE_MIN_VALUE.

NextUp(d As Double) As Double

Returns the floating-point value adjacent to d in the direction of positive infinity.

If the argument is NaN, the result is NaN. If the argument is positive infinity, the result is positive infinity. If the argument is zero, the result is DOUBLE_MIN_VALUE

NumberOfLeadingZeros(i As Int64) As Int32

Returns the number of zero bits preceding the highest-order ("leftmost") one-bit in the two's complement binary representation of i.

Returns 64 if i has no one-bits in its two's complement representation, in other words if it is equal to zero. This method is closely related to the logarithm base 2.

For all positive Int64 values x:

Floor(log₂(x)) = `63 - NumberOfLeadingZeros(x)`
Ceil(₂(x)) = `64 - NumberOfLeadingZeros(x - 1)`

NumberOfTrailingZeros(i As Int64) As Int32

Returns the number of zero bits following the lowest-order ("rightmost") one-bit in the two's complement binary representation of i.

Returns 64 if i has no one-bits in its two's complement representation, in other words if it is equal to zero.

PointInTriangle(p As Point, v1 As Point, v2 As Point, v3 As Point) As Boolean

Returns True if p is inside the triangle formed by the passed vertices.

Adapted from this StackOverflow answer.

PowerOfTwoD(n As Int32) As Double

Returns a floating-point power of two in the normal range.

Random(low As Double, high As Double) As Double

Returns a psuedo random number between low and high.

RShift(v As Int64, s As Integer) As Int64

Shifts v s places to the right, preserving the sign bit.

Equivalent to Java's >> operator.

Thanks to code from the Xojo forum by Rick Araujo.

RShiftU32(v As Int32, s As Integer) As Int32

Shifts v s bits to the right. Shifts a zero into the left-most position.

Equivalent to Java's int >>> x operation.

RShiftU64(v As Int64, shift As Integer) As Int64

Shifts v s bits to the right. Shifts a zero into the left-most position.

Equivalent to Java's long >>> x operation.

Scalb(d As Double, scaleFactor As Integer) As Double

Returns d × 2^scaleFactor rounded as if performed by a single correctly rounded floating-point multiply to a member of the double value set.

If the exponent of the result is between MIN_EXPONENT and MAX_EXPONENT, the answer is calculated exactly. If the exponent of the result would be larger than MAX_EXPONENT then infinity is returned. If the result is subnormal, precision may be lost. That is, when Scalb(x, n) is subnormal, Scalb(scalb(x, n), -n) may not equal x. When the result is non-NaN, the result has the same sign as d.

Special cases:

If the first argument is NaN, NaN is returned.
If the first argument is infinite, then an infinity of the same sign is returned.
If the first argument is zero, then a zero of the same sign is returned.

When scaling up, it does not matter what order the multiply-store operations are done, the result will be finite or overflow regardless of the operation ordering. However, to get the correct result when scaling down, a particular ordering must be used.

When scaling down, the multiply-store operations are sequenced so that it is not possible for two consecutive multiply-stores to return subnormal results. If one multiply-store result is subnormal, the next multiply will round it away to zero. This is done by first multiplying by 2 ^ (scaleFactor % n) and then multiplying several times by by 2^n as needed where n is the exponent of number that is a covenient power of two. In this way, at most one real rounding error occurs. If the double value set is being used exclusively, the rounding will occur on a multiply. If the double-extended-exponent value set is being used, the products will (perhaps) be exact but the stores to d are guaranteed to round to the double value set.

It is not a valid implementation to first multiply d by 2^MIN_EXPONENT and then by 2 ^ (scaleFactor % MIN_EXPONENT) since eduble ounding on underflow could occur e.g. if the scaleFactor argument was MIN_EXPONENT - n and the exponent of d was a little less than -(MIN_EXPONENT - n), meaning the final result would be subnormal.

Since exact reproducibility of this method can be achieved without any undue performance burden, there is no compelling reason to allow double rounding on underflow in scalb.

Signum(d As Double) As Double

Returns the sign of d.

Returns: