--- title: "Number" source: standard-library version: genesis-0-1-0 id: standard-library/4-plugins/number canonical: /docs/standard-library/4-plugins/number --- # 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'.