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)
```