Big

big converts a value to a precise decimal number.

Overview

Use big when a calculation needs decimal values without ordinary floating-point rounding:

price | "19.99".big
shipping | "4.50".big
total | price + shipping

:say(total)  /// 24.49

price | "19.99".big
shipping | "4.50".big
total | price + shipping

:say(total)  /// 24.49

big accepts numbers and numeric strings. It returns a big decimal number.

Method Style

The usual casting style places .big after the value:

price | "19.99".big
quantity | 12.big

price | "19.99".big
quantity | 12.big

The method form does not need parentheses.

The equivalent free-call form is:

price | big("19.99")

price | big("19.99")

Both forms behave the same way.

Exact Decimal Values

Use a string when the exact decimal digits matter:

rate | "0.075".big
balance | "1249.99".big

rate | "0.075".big
balance | "1249.99".big

A string is read directly as a decimal value. Converting a float instead begins with the float value that Goblin already has:

from_string | "19.99".big
from_float | 19.99.big

from_string | "19.99".big
from_float | 19.99.big

Prefer the string form for prices, measurements, rates, and other values where preserving the written decimal is important.

Converting Numbers

big accepts integers, floats, percentages, and values that are already big numbers:

whole | 250.big
decimal | 12.5.big

whole | 250.big
decimal | 12.5.big

Converting an existing big number returns the same numeric value.

Numeric Strings

A numeric string may contain an optional sign and one decimal point:

"1250".big
"-42.75".big
"+8.5".big

"1250".big
"-42.75".big
"+8.5".big

Whitespace around the number is ignored:

"  19.99  ".big  /// same as "19.99".big

"  19.99  ".big  /// same as "19.99".big

Underscores are ignored, so they may be used to group digits:

population | "1_250_000".big

population | "1_250_000".big

Percent strings are not accepted by big. Use Pct to convert text such as "12.5%".

Arrays and Maps

When given an array, big converts every value in the array:

prices | ["4.99", "12.50", "8.25"].big

prices | ["4.99", "12.50", "8.25"].big

When given a map, big converts every value and keeps the keys unchanged:

costs | {
    food: "24.50",
    travel: "80.00"
}.big

costs | {
    food: "24.50",
    travel: "80.00"
}.big

Every value inside the collection must be convertible to a big number. The original collection is not changed; big returns a converted collection.

Short Alias

b is the short form of big:

long_method | "123.45".big
short_method | "123.45".b
long_call | big("123.45")
short_call | b("123.45")

long_method | "123.45".big
short_method | "123.45".b
long_call | big("123.45")
short_call | b("123.45")

All four forms perform the same conversion. See B for the alias page.

Signature

value.big
big(value)

value.big
big(value)

big returns a big number, or a collection whose values have been converted to big numbers.

Errors

big requires exactly one value:

big()
/// error: R0301 wrong-arity

big()
/// error: R0301 wrong-arity

The value must be convertible to a big number:

true.big
/// error: R0215 type-lock-cast

true.big
/// error: R0215 type-lock-cast

A string must contain a valid decimal number:

"twelve".big
/// error: R0215 type-lock-cast

"twelve".big
/// error: R0215 type-lock-cast

Percent strings must be converted with pct instead:

"12.5%".big
/// error: R0215 type-lock-cast

"12.5%".big
/// error: R0215 type-lock-cast

A float must be finite and representable as a big decimal value.