Numeric functions ​

Numeric functions round numbers and test numeric values. Rounding functions help prevent precision mismatches between systems, such as accounting totals that differ by fractions of a cent.

Round to a whole number ​

The following functions round a number to the nearest, next, or previous integer:

round ​

Rounds to the nearest integer.

round(number)

round(3.5)

4

round(2.4)

2

ceil ​

Rounds up to the next integer.

ceil(number)

ceil(3.2)

4

floor ​

Rounds down to the previous integer.

floor(number)

floor(3.9)

3

Round to a precision ​

The following functions round a Decimal to a fixed number of decimal places or significant digits:

round_places ​

Rounds a Decimal to a given number of decimal places.

round_places(decimal, places, options)

An unrecognized option key raises E222 rather than being ignored.

round_places(Decimal('11.545'), 2)

11.55

round_places(Decimal('11.545'), 2, {mode: 'half_even'})

11.54

round_places(Decimal('11.545'), 2, {mode: 'floor'})

11.54

round_significant ​

Rounds a Decimal to a number of significant digits rather than decimal places, without padding.

round_significant(decimal, digits, options)

round_significant(Decimal('1234.5'), 3)

1230

Use case: Round each invoice line to cents ​

Unit prices arrive with three decimal places, but the destination accounting system accepts only two. Use round_places to round each invoice line to two decimal places:

Input

{
  "lines": [
    {"sku": "WID-1", "unit_price": "12.335", "qty": 3},
    {"sku": "GAD-7", "unit_price": "99.005", "qty": 1}
  ]
}

Formula

_.lines >> map_by(l ~> {
  sku: l.sku,
  total: round_places(Decimal(l.unit_price) * l.qty, 2)
})

Output

[
  {"sku": "WID-1", "total": 37.01},
  {"sku": "GAD-7", "total": 99.01}
]

The prices stay Decimal from the start, so the multiplication is exact and only the final rounding loses anything. A Float reading first would round twice instead, applying the second rounding to an already-approximate number.

Absolute value ​

The following function returns a number's magnitude, discarding its sign:

abs ​

Returns the magnitude of a number, discarding its sign. Also accepts a Duration.

abs(value)

abs(-42)

42

Test a number ​

The following functions distinguish an ordinary number from the special Float values. A non-numeric argument raises E100 rather than returning false.

finite? ​

Returns true for an Integer, a Decimal, or a Float that is an ordinary number.

finite?(number)

finite?(1.0)

true

finite?(Float('Infinity'))

false

infinite? ​

Returns true if the value is positive or negative infinity.

infinite?(number)

infinite?(Float('Infinity'))

true

nan? ​

Returns true if the value is the Float "not a number".

nan?(number)

nan?(1.0)

false

Bit width ​

The following function measures how many bits an integer needs to represent:

int_bit_size ​

Returns the number of bits needed to represent an integer in bit-complementary encoding.

int_bit_size(integer)

int_bit_size(255)

9

Related ​

• Conversion functions: How to construct each data type.
• Formatting functions: Render a number for display.
• Data types: Why Decimal and Float behave differently.
• Common functions: Information about present? and presence.
• Temporal functions: Information about Duration, which abs also accepts.