XUIMaths
Description
This module exposes a wide range of mathematical methods.
Properties
Name  Type  ReadOnly 

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 nonzero 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 floatingpoint value according to the IEEE 754 floatingpoint "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 floatingpoint 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 floatingpoint result equals the value of the mathematical
expression s·m·2^e1075
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 NaN
s, quiet NaN
s and signaling NaNs. The differences
between the two kinds of NaN
are generally not visible. Arithmetic
operations on signaling NaN
s 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 floatingpoint
"double format" bit layout.
Bit 63 (the bit that is selected by the mask 0x8000000000000000
)
represents the sign of the double number.
Bits 6252 (the bits that are selected by the mask 0x7ff0000000000000
)
represent the exponent.
Bits 510 (the bits that are selected by the mask 0x000fffffffffffff
)
represent the significand (sometimes called the mantissa) of the
floatingpoint 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 floatingpoint
"double format" bit layout, preserving NaN
values.
Bit 63 (the bit that is selected by the mask &h8000000000000000
)
represents the sign of the floatingpoint number.
Bits 6252 (the bits that are selected by the mask &h7ff0000000000000
)
represent the exponent.
Bits 510 (the bits that are selected by the mask &h000fffffffffffff
)
represent the significand (sometimes called the mantissa) of the
floatingpoint 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 floatingpoint 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 semimonotonic 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 32bit 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 64bit 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 floatingpoint 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 floatingpoint 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 highestorder
("leftmost") onebit in the two's complement binary representation of i
.
Returns 64
if i
has no onebits 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 lowestorder ("rightmost")
onebit in the two's complement binary representation of i
.
Returns 64
if i
has no onebits 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 floatingpoint 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 leftmost 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 leftmost 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 floatingpoint 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 nonNaN
, 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 multiplystore 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 multiplystore operations are sequenced so that it is not possible for two consecutive multiplystores to return subnormal results. If one multiplystore 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 doubleextendedexponent 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:
 Zero if the argument is zero
1.0
if the argument is greater than zero1.0
if the argument is less than zero. If the argument is NaN, then the result is NaN.
ToBinaryString(currencyValue As Currency) As String
Returns a binary string representation of a currency value.
Credit to Norman Palardy.
ToBinaryString(doubleValue As Double) As String
Returns a binary string representation of a double value.
Credit to Norman Palardy.
ToBinaryString(i16 As Int16) As String
Returns a binary string representation of a signed 16bit integer value.
Credit to Norman Palardy.
ToBinaryString(i32 As Int32) As String
Returns a binary string representation of a signed 32bit integer value.
Credit to Norman Palardy.
ToBinaryString(i64 As Int64) As String
Returns a binary string representation of a signed 64bit integer value.
Credit to Norman Palardy.
ToBinaryString(i8 As Int8) As String
Returns a binary string representation of a signed 8bit integer value.
Credit to Norman Palardy.
ToBinaryString(singleValue As Single) As String
Returns a binary string representation of a Xojo Single
value.
Credit to Norman Palardy.
ToBinaryString(i16 As UInt16) As String
Returns a binary string representation of an unsigned 16bit integer value.
Credit to Norman Palardy.
ToBinaryString(i32 As UInt32) As String
Returns a binary string representation of an unsigned 32bit integer value.
Credit to Norman Palardy.
ToBinaryString(i64 As UInt64) As String
Returns a binary string representation of an unsigned 64bit integer value.
Credit to Norman Palardy.
ToBinaryString(i8 As UInt8) As String
Returns a binary string representation of an unsigned 8bit integer value.
Credit to Norman Palardy.
ToDegrees(radians As Double) As Double
Returns radians
in degrees.
ToRadians(degrees As Double) As Double
Returns degrees
in radians.
WrapInteger(i As Integer, maxValue As Integer) As Integer
Wraps i
between zero and maxValue
.