Module /fusion/number

(* num ...)

Returns the product of the numbers, which must be int or decimal. With no arguments, returns integer 1.

(+ num ...)

Returns the sum of the numbers, which must be int or decimal. With no arguments, returns integer 0.

(- num ...+)

With two or more int or decimal numbers, returns their difference, associating to the left. With one int or decimal argument, returns its negation.

(/ dividend divisor)

Returns a decimal whose numeric value is (dividend / divisor). Both arguments must be decimals. An exception is thrown if the result cannot be represented exactly.

(< a b)

Returns true if a is less than b. Numbers are compared without regard to precision or negative zeros; if the values have different concrete types they are both coerced to decimal. Timestamps are compared to each other without regard to precision or local offset. Annotations are ignored.

Warning: The behavior of this procedure is undefined for values +inf, -inf, and nan. See issue #64.

(<= a b)

Returns true if a is less than or equal to b. Numbers are compared without regard to precision or negative zeros; if the values have different concrete types they are both coerced to decimal. Timestamps are compared to each other without regard to precision or local offset. Annotations are ignored.

Warning: The behavior of this procedure is undefined for values +inf, -inf, and nan. See issue #64.

(= left right)

Returns true if the arguments are equivalent in shape and content, possibly by coercing values to a common type. Annotations and precision are ignored.

• Any value is = to itself.
• Nulls of any type are = to each other.
• Bools are = in the obvious way.
• Numbers are = when they represent the same numeric value, without regard to precision or negative zeros. When a float is compared to an int or decimal, it is coerced to a decimal.
• Timestamps are = when they represent the same point-in-time, without regard to precision or local offset.
• Strings and symbols are = (interchangably) when they contain the same sequence of code points.
• Blobs and clobs are = (interchangably) when they contain the same sequence of bytes.
• Pairs are = when their heads and tails are =.
• Sequences are = when they have the same size, and elements at the same index are =.
• Structs are = when they have the same set of field names, and each name maps to a set of elements that are =.
• Void is = only to itself.
• Exceptions are not thrown due to mismatched types; instead the result is false.

For example:

(= null (quote a::null))             --> true
(= null null.clob)                   --> true
(= 1 1.00)                           --> true
(= 0 -0e-3)                          --> true
(= 2014T 2014-01-01T02:00+02:00)     --> true
(= 2014T 2014)                       --> false

(= "text" (quote text))              --> true
(= "text" (quote a::"text"))         --> true

(= [1, 2] (sexp 1 2.00))             --> true
(= null.list [])                     --> false

(= (struct "f" 1) (mutable_struct "f" 1.0))   --> true
(= {f:1, f:1} {f:1})                          --> false

At present, the coercion of float to decimal is precise, without rounding to approximate a prettier decimal form. This may lead to strange behavior since most decimal numbers don't have a precise binary representation:

(= 1.2 1.2e0)  --> false
(= 1.5 1.5e0)  --> true

It's possible this may change in a future release.

Warning: The behavior of this procedure is undefined for values +inf, -inf, and nan. See issue #64.

(== left right)

Like = but does not coerce values to a common abstract supertype. Annotations and precision are ignored.

• Any value is == to itself.
• Nulls are only == to nulls of the same type.
• Numbers are == when they have the same type and numeric value, without regard to precision or negative zeros.
• Strings are only == to strings, and symbols to symbols.
• Blobs are only == to blobs, and clobs to clobs.
• Pairs are == when their heads and tails are ==.
• Lists (and sexps) are == when they have the same type and size, and elements at the same index are ==.
• Structs are == when they have the same set of field names, and each name maps to a set of elements that are ==.

For example:

(== null (quote a::null))             --> true
(== null null.clob)                   --> false
(== 1  1.)                            --> false
(== 1. 1.0)                           --> true
(=== 0. -0.)                          --> true
(== 2014T 2014-01-01T02:00+02:00)     --> true
(== 2014T 2014)                       --> false

(== "text" (quote text))              --> false
(== "text" (quote a::"text"))         --> true

(== [1, 2] (sexp 1 2   ))             --> false
(== [1, 2] (list 1 2.00))             --> false
(== [1, 2] (list 1 2   ))             --> true
(== [1, 2] (mutable_list 1 2))        --> true

Warning: The behavior of this procedure is undefined for values +inf, -inf, and nan. See issue #64.

(=== left right)

Like == but annotations and precision are not ignored.

• Values are === only when their annotations are equal.
• Decimals are === only when they have the same numeric value and precision. Negative zeros are not === to positive zeros.
• Timestamps are === only when they represent the same point-in-time and have the same precision and local offset.

For example:

(=== null (quote a::null))             --> false
(=== (quote a::null) (quote a::null))  --> true
(=== null null.clob)                   --> false
(=== 1   1.)                           --> false
(=== 1.  1.0)                          --> false
(=== 1.0 1.0)                          --> true
(=== 0. -0.)                           --> false

(=== 2014T 2014-01-01T02:00+02:00)     --> false
(=== 2014-01-01T00:00+00:00
     2014-01-01T00:00-00:00)           --> false

(=== (quote    a::1) (quote a::a::1))  --> false
(=== (quote b::a::1) (quote a::b::1))  --> false

Warning: The behavior of this procedure is undefined for values +inf, -inf, and nan. See issue #64.

(> a b)

Returns true if a is greater than b. Numbers are compared without regard to precision or negative zeros; if the values have different concrete types they are both coerced to decimal. Timestamps are compared to each other without regard to precision or local offset. Annotations are ignored.

Warning: The behavior of this procedure is undefined for values +inf, -inf, and nan. See issue #64.

(>= a b)

Returns true if a is greater than or equal to b. Numbers are compared without regard to precision or negative zeros; if the values have different concrete types they are both coerced to decimal. Timestamps are compared to each other without regard to precision or local offset. Annotations are ignored.

Warning: The behavior of this procedure is undefined for values +inf, -inf, and nan. See issue #64.

(ceiling number)

Returns the smallest int greater than or equal to number (that is, truncate toward positive infinity). The input must be a non-null int or decimal, and the result is an int.

(decimal coefficient)
(decimal coefficient exponent)

Returns the decimal value from the coefficient and optional exponent. The coefficient must be a number. The exponent, if supplied, must be a non-null int. Returns null.decimal when coefficient is null.

Examples:

(decimal null.float) // null.decimal
(decimal 1234e-2)    // 12.34
(decimal 1.21e1 0)   // 12.1
(decimal 4.2 1)      // 42.
(decimal 1234 -2)    // 12.34

(floor number)

Returns the largest int less than or equal to number (that is, truncate toward negative infinity). The input must be a non-null int or decimal, and the result is an int.

(int_to_string int)

Converts an int to a string. Returns null.string when given null.int.

(is_actual_decimal value)

Determines whether value is a non-null decimal, returning true or false.

(is_actual_float value)

Determines whether value is a non-null float, returning true or false.

(is_actual_int value)

Determines whether value is a non-null int, returning true or false.

(is_decimal value)

Determines whether a value is of type decimal, returning true or false.

(is_float value)

Determines whether a value is of type float, returning true or false.

(is_int value)

Determines whether a value is of type int, returning true or false.

(random)
(random max)

Returns a random float value between 0.0 (inclusive) and 1.0 (exclusive) when no additional arguments are provided. When max is provided, it must be a positive integer, and the result is a random number between 0 (inclusive) and max (exclusive).

Examples:

(random)    // Returns a decimal value: 0.0 <= value < 1.0
(random 45) // Returns an int value:    0   <= value < 45

(string_to_int string)

Converts a string to an int. The string must contain an optional minus sign ("-" aka "\x2D") followed by one or more ASCII digits. Returns null.int when given null.string. An exception is raised if the string is of invalid format.