Number

Source: standard-library. Raw markdown: /raw/docs/standard-library/4-plugins/number.md

Number

The number plugin provides numeric conversion and representation helpers through the Simorg vibration API. Each vibration key maps to one number runtime function. Inputs are validated for type, range, and format, and the plugin returns either a converted value or no vibration for invalid arguments.

Functions

toU8

Converts input to unsigned 8-bit integer.

255  number.toU8 ? // 255

Out-of-range values no vibration will happen.

256  number.toU8 ? // no vibration
  • Type: ERROR
  • Code: RANGE_OVERFLOW
  • Message: Value is outside u8 range [0,255].

toU16

Converts input to unsigned 16-bit integer.

65535  number.toU16 ? // 65535

Negative values no vibration will happen.

-1  number.toU16 ? // no vibration
  • Type: ERROR
  • Code: RANGE_UNDERFLOW
  • Message: Unsigned conversion cannot accept negative values.

toU32

Converts input to unsigned 32-bit integer.

4294967295  number.toU32 ? // 4294967295

Fractional values no vibration will happen.

12.5  number.toU32 ? // no vibration
  • Type: ERROR
  • Code: INVALID_INTEGER_VALUE
  • Message: Integer conversions require whole numbers.

toU64

Converts input to unsigned 64-bit integer.

42  number.toU64 ? // 42

Invalid numeric strings no vibration will happen.

"abc"  number.toU64 ? // no vibration
  • Type: ERROR
  • Code: INVALID_NUMBER_FORMAT
  • Message: Input must be numeric or a numeric string.

toI8

Converts input to signed 8-bit integer.

-128  number.toI8 ? // -128

Values above 127 no vibration will happen.

128  number.toI8 ? // no vibration
  • Type: ERROR
  • Code: RANGE_OVERFLOW
  • Message: Value is outside i8 range [-128,127].

toI16

Converts input to signed 16-bit integer.

-32768  number.toI16 ? // -32768

Non-numeric input no vibration will happen.

"x"  number.toI16 ? // no vibration
  • Type: ERROR
  • Code: INVALID_NUMBER_FORMAT
  • Message: Input must be numeric or a numeric string.

toI32

Converts input to signed 32-bit integer.

1024  number.toI32 ? // 1024

NaN-like values no vibration will happen.

"nan"  number.toI32 ? // no vibration
  • Type: ERROR
  • Code: INVALID_NUMBER_FORMAT
  • Message: Input must be a finite integer-compatible value.

toI64

Converts input to signed 64-bit integer.

9000000000  number.toI64 ? // 9000000000

Values outside i64 range no vibration will happen.

"999999999999999999999"  number.toI64 ? // no vibration
  • Type: ERROR
  • Code: RANGE_OVERFLOW
  • Message: Value is outside i64 range.

toDouble

Converts input to double precision number.

"3.14"  number.toDouble ? // 3.14

Non-numeric strings no vibration will happen.

"abc"  number.toDouble ? // no vibration
  • Type: ERROR
  • Code: INVALID_NUMBER_FORMAT
  • Message: Input must be a valid numeric value.

toFixed

Formats a number with fixed decimal precision using [value, precision].

(3.14159,2)  number.toFixed ? // "3.14"

Precision outside [0,15] no vibration will happen.

(3.14,20)  number.toFixed ? // no vibration
  • Type: ERROR
  • Code: INVALID_PRECISION
  • Message: Precision must be between 0 and 15.

inRange

Checks whether value is in inclusive [min,max].

(5,1,10)  number.inRange ? // true

Invalid bounds no vibration will happen.

(5,10,1)  number.inRange ? // no vibration
  • Type: ERROR
  • Code: INVALID_RANGE_BOUNDS
  • Message: Minimum bound must be less than or equal to maximum bound.

isInteger

Checks whether input is a finite integer value.

12.0  number.isInteger ? // true

Invalid input no vibration will happen.

"hello"  number.isInteger ? // no vibration
  • Type: ERROR
  • Code: INVALID_NUMBER_FORMAT
  • Message: Input must be numeric.

fromString

Parses a numeric string into best-fit numeric JSON type.

"42"  number.fromString ? // 42

Empty strings no vibration will happen.

"   "  number.fromString ? // no vibration
  • Type: ERROR
  • Code: EMPTY_INPUT
  • Message: Input string must not be empty.

toHex

Converts integer input to lowercase hexadecimal string.

255  number.toHex ? // "ff"

Negative values no vibration will happen.

-1  number.toHex ? // no vibration
  • Type: ERROR
  • Code: INVALID_UNSIGNED_VALUE
  • Message: Hex conversion expects a non-negative integer.

toBinary

Converts integer input to binary string.

10  number.toBinary ? // "1010"

Non-integer input no vibration will happen.

3.5  number.toBinary ? // no vibration
  • Type: ERROR
  • Code: INVALID_INTEGER_VALUE
  • Message: Binary conversion requires a whole number.

fromHex

Parses hexadecimal string into unsigned integer.

"ff"  number.fromHex ? // 255

Invalid hex strings no vibration will happen.

"xz"  number.fromHex ? // no vibration
  • Type: ERROR
  • Code: INVALID_HEX_STRING
  • Message: Input must be a valid hexadecimal string.

fromBinary

Parses binary string into unsigned integer.

"1010"  number.fromBinary ? // 10

Strings with characters other than 0/1 no vibration will happen.

"1021"  number.fromBinary ? // no vibration
  • Type: ERROR
  • Code: INVALID_BINARY_STRING
  • Message: Input must contain only '0' or '1'.