Tonum

tonum( value, [format_flags] )

Attempts to return the given value as a number. Result is empty on failure.

value

The value to be converted: strings, booleans, and numbers are accepted.

format_flags

A bitfield which allows different operations to occur in the conversion.

return-value

The provided value converted to a native number format, if possible; otherwise an empty result.

Returns a number if value can be converted to a number, or value already is a number. If not, the result will be empty, which for most purposes will work as if nil had been returned.

If value is a string, tonum() will try to parse it as one of these supported number formats:

• Decimal, e.g.: "255", "3.14159"

• Hexadecimal, e.g.: "0xff", "0x3.243f"

• Binary, e.g.: "0b11111111", "0b11.0010010000111111"

• Scientific/exponential, e.g.: "2.55e2", "3.14159e0"

Note that leading or trailing 0s are ignored, as one would expect, which may be useful when extracting fixed-width fields from a string.

If value is a boolean, it will return 0 for false and 1 for true, thus providing a simple way to convert booleans to numbers.

If value is already a number, it will be returned as-is.

The format_flags parameter is composed of individual bits that control the conversion process:

 0x1: Read using hexadecimal notation, without requiring the "0x" prefix.
      Note: Non-hexadecimal characters, including '.' and '-', are taken to be '0'.

 0x2: Shift the value right 16 bits to create a 16.16 fixed-point number.
      This works with all formats, even booleans: true becomes 0x.0001.

 0x4: When value cannot be converted to a number, return 0 instead of nothing.

Technical Notes

• If the string represents a number outside of the range of PICO-8 numbers, it wraps the number to that range before returning. Effectively, the result is bitwise-anded with 0xffff.ffff to fit in the PICO-8 16.16 fixed-point number format.

• When presented with a non-number, e.g. tonum("xyz"), the result will technically be empty to indicate that the string can't be parsed as a number. In Lua, the concept of empty is technically distinct from nil, but when empty is assigned to a variable, the variable becomes nil, and if empty is directly tested (e.g. if tonum("xyz") then ... end) it will be considered false.

Examples

x = tonum('12345')          -- 12345
x = tonum('-12345.67')      -- -12345.67
x = tonum('-1.23456789e4')  -- -12345.6789

x = tonum('0x0f')           -- 15
x = tonum('0x0f.abc')       -- 15.6709
x = tonum('0b1001')         -- 9

x = tonum('32767')          -- 32767
x = tonum('99999')          -- -31073 (wrapped)
x = tonum('xyz')            -- nil

-- Examples with format_flags bitfield

x = tonum("ff",       0x1)  -- 255
x = tonum("1146880",  0x2)  -- 17.5
x = tonum("1234abcd", 0x3)  -- 0x1234.abcd
x = tonum("xyz",      0x4)  -- 0 (instead of nil)

See also

• tostr()
• Lua