ESC
No recent searches
Search by
Standard Library  /  Number

Grain Docs

Welcome to Grain! Editor Setup Getting Grain

The Guide

Hello World The Basics Conditionals Functions Shadowing and Mutation Loops Lists and arrays Custom Data Types Modules Pattern Matching

Reference

Building for Production Built-in Types The Grain CLI Graindoc

Standard Library

Pervasives BigInt Array Buffer Bytes Char Exception Float32 Float64 Hash Int16 Int32 Int64 Int8 Json List Map Marshal Number Option Path PriorityQueue Queue Random Range Rational Regex Result Stack Set String Uint16 Uint32 Uint64 Uint8 Uri wasi / File wasi / Process wasi / Random wasi / Time

Number

Utilities for working with numbers.

Edit on GitHub
Added in 0.4.0 No other changes yet. 
from "number" include Number
1
-1
0.5
1/2
Infinity
NaN

Types

Type declarations included in the Number module.

Number.ParseIntError

Added in 0.6.0 No other changes yet. 
enum ParseIntError {
  ParseIntEmptyString,
  ParseIntInvalidDigit,
  ParseIntInvalidRadix,
}

Represents an error that occurred trying to parse an integer.

Variants:

ParseIntEmptyString

Represents an error caused by trying to parse an empty string.

ParseIntInvalidDigit

Represents an error caused by trying to parse a string with an invalid character.

ParseIntInvalidRadix

Represents an error caused by trying to parse with an invalid radix.

Values

Functions and constants included in the Number module.

Number.pi

Added in 0.5.2 No other changes yet. 
pi : Number

Pi represented as a Number value.

Number.tau

Added in 0.5.2 No other changes yet. 
tau : Number

Tau represented as a Number value.

Number.e

Added in 0.5.2 No other changes yet. 
e : Number

Euler’s number represented as a Number value.

Number.(+)

Added in 0.6.0
versionchanges
0.4.0Originally named `add`
 
(+) : (num1: Number, num2: Number) => Number

Computes the sum of its operands.

Parameters:

num1: The first operand
num2: The second operand

Returns:

Number: The sum of the two operands

Examples:

from Number use { (+) }
assert 1 + 2 == 3

Number.(-)

Added in 0.6.0
versionchanges
0.4.0Originally named `sub`
 
(-) : (num1: Number, num2: Number) => Number

Computes the difference of its operands.

Parameters:

num1: The first operand
num2: The second operand

Returns:

Number: The difference of the two operands

Examples:

from Number use { (-) }
assert 5 - 2 == 3

Number.(*)

Added in 0.6.0
versionchanges
0.4.0Originally named `mul`
 
(*) : (num1: Number, num2: Number) => Number

Computes the product of its operands.

Parameters:

num1: The first operand
num2: The second operand

Returns:

Number: The product of the two operands

Examples:

from Number use { (*) }
assert 5 * 4 == 20

Number.(/)

Added in 0.6.0
versionchanges
0.4.0Originally named `div`
 
(/) : (num1: Number, num2: Number) => Number

Computes the quotient of its operands.

Parameters:

num1: The dividend
num2: The divisor

Returns:

Number: The quotient of the two operands

Examples:

from Number use { (/) }
assert 10 / 2.5 == 4

Number.(**)

Added in 0.6.0
versionchanges
0.5.4Originally named `pow`
 
(**) : (base: Number, power: Number) => Number

Computes the exponentiation of the given base and power.

Parameters:

base: The base number
power: The exponent number

Returns:

Number: The base raised to the given power

Examples:

from Number use { (**) }
assert 10 ** 2 == 100

Number.exp

Added in 0.5.4 No other changes yet. 
exp : (power: Number) => Number

Computes the exponentiation of Euler’s number to the given power.

Parameters:

power: The exponent number

Returns:

Number: The Number.e value raised to the given power

Examples:

Number.exp(1) == Number.e
Number.exp(10) == 22026.465794806703

Number.sqrt

Added in 0.4.0 No other changes yet. 
sqrt : (x: Number) => Number

Computes the square root of its operand.

Parameters:

x: The number to square root

Returns:

Number: The square root of the operand

Examples:

Number.sqrt(25) == 5

Number.sign

Added in 0.5.0 No other changes yet. 
sign : (x: Number) => Number

Determine the positivity or negativity of a Number.

Parameters:

x: The number to inspect

Returns:

Number: -1 if the number is negative, 1 if positive, or 0 otherwise; signedness of -0.0 is preserved

Examples:

Number.sign(-10000) == -1
Number.sign(222222) == 1
Number.sign(0) == 0

Number.min

Added in 0.4.0
versionchanges
0.5.4Handle NaN properly
 
min : (x: Number, y: Number) => Number

Returns the smaller of its operands.

Parameters:

x: The first operand
y: The second operand

Returns:

Number: The smaller of the two operands

Examples:

Number.min(5, 2) == 2

Number.max

Added in 0.4.0
versionchanges
0.5.4Handle NaN properly
 
max : (x: Number, y: Number) => Number

Returns the larger of its operands.

Parameters:

x: The first operand
y: The second operand

Returns:

Number: The larger of the two operands

Examples:

Number.max(5, 2) == 5

Number.ceil

Added in 0.4.0
versionchanges
0.5.4Handle NaN and Infinity properly
 
ceil : (x: Number) => Number

Rounds its operand up to the next largest integer.

Parameters:

x: The number to round

Returns:

Number: The next largest integer of the operand

Examples:

Number.ceil(5.5) == 6
Number.ceil(-5.5) == -5

Number.floor

Added in 0.4.0
versionchanges
0.5.4Handle NaN and Infinity properly
 
floor : (x: Number) => Number

Rounds its operand down to the largest integer less than the operand.

Parameters:

x: The number to round

Returns:

Number: The previous integer of the operand

Examples:

Number.floor(5.5) == 5
Number.floor(-5.5) == -6

Number.trunc

Added in 0.4.0
versionchanges
0.5.4Handle NaN and Infinity properly
 
trunc : (x: Number) => Number

Returns the integer part of its operand, removing any fractional value.

Parameters:

x: The number to truncate

Returns:

Number: The integer part of the operand

Examples:

Number.trunc(5.5) == 5

Number.round

Added in 0.4.0
versionchanges
0.5.4Handle NaN and Infinity properly
 
round : (x: Number) => Number

Returns its operand rounded to its nearest integer.

Parameters:

x: The number to round

Returns:

Number: The nearest integer to the operand

Examples:

Number.round(5.5) == 6
Number.round(5.4) == 5
Number.round(-5.5) == -6
Number.round(-5.4) == -5

Number.abs

Added in 0.4.0 No other changes yet. 
abs : (x: Number) => Number

Returns the absolute value of a number. That is, it returns x if x is positive or zero and the negation of x if x is negative.

Parameters:

x: The operand

Returns:

Number: The absolute value of the operand

Examples:

Number.abs(-1) == 1
Number.abs(5) == 5

Number.neg

Added in 0.4.0 No other changes yet. 
neg : (x: Number) => Number

Returns the negation of its operand.

Parameters:

x: The number to negate

Returns:

Number: The negated operand

Examples:

Number.neg(-1) == 1
Number.neg(1) == -1

Number.isFloat

Added in 0.5.3 No other changes yet. 
isFloat : (x: Number) => Bool

Checks if a number is a floating point value.

Parameters:

x: The number to check

Returns:

Bool: true if the value is a floating point number or false otherwise

Examples:

Number.isFloat(0.5)
Number.isFloat(1.0)
Number.isFloat(Infinity)
Number.isFloat(NaN)
Number.isFloat(1/2) == false
Number.isFloat(1) == false

Number.isInteger

Added in 0.5.3 No other changes yet. 
isInteger : (x: Number) => Bool

Checks if a number is an integer.

Parameters:

x: The number to check

Returns:

Bool: true if the value is an integer or false otherwise

Examples:

Number.isInteger(1)
Number.isInteger(0.5) == false
Number.isInteger(1.0) == false
Number.isInteger(1/2) == false
Number.isInteger(Infinity) == false
Number.isInteger(NaN) == false

Number.isRational

Added in 0.5.3 No other changes yet. 
isRational : (x: Number) => Bool

Checks if a number is a non-integer rational value.

Parameters:

x: The number to check

Returns:

Bool: true if the value is a non-integer rational number or false otherwise

Examples:

Number.isRational(1/2)
Number.isRational(0.5) == false
Number.isRational(1.0) == false
Number.isRational(1) == false
Number.isRational(Infinity) == false
Number.isRational(NaN) == false

Number.isFinite

Added in 0.4.0 No other changes yet. 
isFinite : (x: Number) => Bool

Checks if a number is finite. All values are finite exept for floating point NaN, infinity or negative infinity.

Parameters:

x: The number to check

Returns:

Bool: true if the value is finite or false otherwise

Examples:

Number.isFinite(1/2)
Number.isFinite(0.5)
Number.isFinite(1.0)
Number.isFinite(1)
Number.isFinite(Infinity) == false
Number.isFinite(-Infinity) == false
Number.isFinite(NaN) == false

Number.isNaN

Added in 0.4.0 No other changes yet. 
isNaN : (x: Number) => Bool

Checks if a number is the float NaN value (Not A Number).

Parameters:

x: The number to check

Returns:

Bool: true if the value is NaN, otherwise false

Examples:

Number.isNaN(NaN)
Number.isNaN(Infinity) == false
Number.isNaN(-Infinity) == false
Number.isNaN(1/2) == false
Number.isNaN(0.5) == false
Number.isNaN(1.0) == false
Number.isNaN(1) == false

Number.isInfinite

Added in 0.4.0 No other changes yet. 
isInfinite : (x: Number) => Bool

Checks if a number is infinite, that is either of floating point positive or negative infinity. Note that this function is not the exact opposite of isFinite(Number) in that it doesn’t return true for NaN.

Parameters:

x: The number to check

Returns:

Bool: true if the value is infinite or false otherwise

Examples:

Number.isInfinite(Infinity)
Number.isInfinite(-Infinity)
Number.isInfinite(NaN) == false
Number.isInfinite(1/2) == false
Number.isInfinite(0.5) == false
Number.isInfinite(1.0) == false
Number.isInfinite(1) == false

Number.isClose

Added in 0.6.0 No other changes yet. 
isClose :
  (a: Number, b: Number, ?relativeTolerance: Number,
   ?absoluteTolerance: Number) => Bool

Determines whether two values are considered close to each other using a relative and absolute tolerance.

Parameters:

a: The first value
b: The second value
?relativeTolerance: The maximum tolerance to use relative to the larger absolute value a or b
?absoluteTolerance: The absolute tolerance to use, regardless of the values of a or b

Returns:

Bool: true if the values are considered close to each other or false otherwise

Examples:

Number.isClose(1.233, 1.233)
Number.isClose(1.233, 1.233000001)
Number.isClose(8.005, 8.450, absoluteTolerance=0.5)
Number.isClose(4, 4.1, relativeTolerance=0.025)
Number.isClose(1.233, 1.24) == false
Number.isClose(1.233, 1.4566) == false
Number.isClose(8.005, 8.450, absoluteTolerance=0.4) == false
Number.isClose(4, 4.1, relativeTolerance=0.024) == false

Number.parseInt

Added in 0.4.5
versionchanges
0.6.0Switched from a string-based error message to a structured error enum
 
parseInt :
  (string: String, radix: Number) => Result<Number, Atoi.ParseIntError>

Parses a string representation of an integer into a Number using the specified radix (also known as a number system “base”).

If the string has a radix prefix (i.e. “0x”/“0X”, “0o”/“0O”, or “0b”/“0B” for radixes 16, 8, or 2 respectively), the supplied radix is ignored in favor of the prefix. Underscores that appear in the numeric portion of the input are ignored.

Parameters:

string: The string to parse
radix: The number system base to use when parsing the input string

Returns:

Result<Number, Atoi.ParseIntError>: Ok(value) containing the parsed number on a successful parse or Err(err) containing a variant of ParseIntError

Examples:

Number.parseInt("1", radix=10) == Ok(1)
Number.parseInt("-1", radix=10) == Ok(-1)
Number.parseInt("0xf0", radix=16) == Ok(0x0f0)

Number.parseFloat

Added in 0.5.5 No other changes yet. 
parseFloat : (string: String) => Result<Number, String>

Parses a string representation of a float into a Number. Underscores that appear in numeric portions of the input are ignored.

Parameters:

string: The string to parse

Returns:

Result<Number, String>: Ok(value) containing the parsed number on a successful parse or Err(msg) containing an error message string otherwise

Examples:

Number.parseFloat("1") == Ok(1.0)
Number.parseFloat("-1") == Ok(-1.0)
Number.parseFloat("-1.5") == Ok(-1.5)

Number.parse

Added in 0.5.5 No other changes yet. 
parse : (input: String) => Result<Number, Atoi.ParseIntError>

Parses a string representation of an integer, float, or rational into a Number. Underscores that appear in the numeric portion of the input are ignored.

Parameters:

input: The string to parse

Returns:

Result<Number, Atoi.ParseIntError>: Ok(value) containing the parsed number on a successful parse or Err(msg) containing an error message string otherwise

Examples:

Number.parse("1") == Ok(1)
Number.parse("-1") == Ok(-1)
Number.parse("0xf0") == Ok(0x0f0)
Number.parse("-1.5") == Ok(-1.5)

Number.asin

Added in 0.6.0 No other changes yet. 
asin : (angle: Number) => Number

Computes the inverse sine of the given angle.

Parameters:

angle: A number between -1 and 1, representing the angle’s sine value

Returns:

Number: The inverse sine (angle in radians between -pi/2 and pi/2) of the given angle or NaN if the given angle is not between-1 and 1

Examples:

Number.asin(0) == 0
Number.asin(1) == 1.5707963267948966

Number.acos

Added in 0.6.0 No other changes yet. 
acos : (angle: Number) => Number

Computes the inverse cosine of the given angle.

Parameters:

angle: A number between -1 and 1, representing the angle’s cosine value

Returns:

Number: The inverse cosine (angle in radians between -pi/2 and pi/2) of the given angle or NaN if the given angle is not between-1 and 1

Examples:

Number.acos(1) == 0
Number.acos(0) == 1.5707963267948966

Number.atan

Added in 0.6.0 No other changes yet. 
atan : (angle: Number) => Number

Computes the inverse tangent of the given angle.

Parameters:

angle: A number between -1 and 1, representing the angle’s tangent value

Returns:

Number: The inverse tangent (angle in radians between -pi/2 and pi/2) of the given angle or NaN if the given angle is not between-1 and 1

Examples:

Number.atan(0) == 0
Number.atan(1) == 0.7853981633974483

Number.atan2

Added in 0.6.0 No other changes yet. 
atan2 : (y: Number, x: Number) => Number

Computes the angle between the positive x-axis and the ray from the origin to the point (x, y).

Parameters:

y: The given y coordinate
x: The given x coordinate

Returns:

Number: The angle in radians between the positive x-axis and the point (x, y)

Examples:

Number.atan2(0, 1) == Number.pi

Number.toRadians

Added in 0.5.4 No other changes yet. 
toRadians : (degrees: Number) => Number

Converts degrees to radians.

Parameters:

degrees: The value to convert

Returns:

Number: The value in radians

Examples:

Number.toRadians(180) == Number.pi

Number.toDegrees

Added in 0.5.4 No other changes yet. 
toDegrees : (radians: Number) => Number

Converts radians to degrees.

Parameters:

radians: The value to convert

Returns:

Number: The value in degrees

Examples:

Number.toRadians(Number.pi) == 180

Number.clamp

Added in 0.6.0 No other changes yet. 
clamp : (range: Range<Number>, input: Number) => Number

Constrains a number within the given inclusive range.

Parameters:

range: The inclusive range to clamp within
input: The number to clamp

Returns:

Number: The constrained number

Number.linearInterpolate

Added in 0.6.0 No other changes yet. 
linearInterpolate : (range: Range<Number>, weight: Number) => Number

Maps a weight between 0 and 1 within the given inclusive range.

Parameters:

range: The inclusive range to interpolate within
weight: The weight to interpolate

Returns:

Number: The blended value

Throws:

InvalidArgument(String)

  • When weight is not between 0 and 1
  • When range is not finite
  • When range includes NaN

Number.linearMap

Added in 0.6.0 No other changes yet. 
linearMap :
  (inputRange: Range<Number>, outputRange: Range<Number>, current: Number) =>
   Number

Scales a number from one inclusive range to another inclusive range. If the number is outside the input range, it will be clamped.

Parameters:

inputRange: The inclusive range you are mapping from
outputRange: The inclusive range you are mapping to
current: The number to map

Returns:

Number: The mapped number

Throws:

InvalidArgument(String)

  • When inputRange is not finite
  • When inputRange includes NaN
  • When outputRange is not finite
  • When outputRange includes NaN
Marshal Option

Sign up for farm-to-inbox developer news

You can unsubscribe at any time. Read our privacy policy.

Copyright © 2024 The Grain Programming Language