Integer Methods
Sia provides symmetric add/read method pairs for all standard integer sizes. All multi-byte integers use little-endian byte order, matching the native byte order of most modern hardware.
All integer methods are also available as standalone functions for tree-shaking:
// Class API
import { Sia } from "@timeleap/sia";
// Functional API
import {
Buffer,
addUInt8,
readUInt8,
addInt32,
readInt32,
} from "@timeleap/sia";
Unsigned Integers
addUInt8(n) / readUInt8()
Writes or reads a single unsigned 8-bit integer (0 to 255).
addUInt8(n: number): Sia
readUInt8(): number
| Parameter | Type | Range |
|---|---|---|
n | number | 0 to 255 |
Throws: "Not enough data to read uint8" if there are insufficient bytes to read.
const sia = new Sia();
sia.addUInt8(255);
sia.seek(0);
console.log(sia.readUInt8()); // 255
addUInt16(n) / readUInt16()
Writes or reads an unsigned 16-bit integer (0 to 65,535). Stored as 2 bytes in little-endian order.
addUInt16(n: number): Sia
readUInt16(): number
| Parameter | Type | Range |
|---|---|---|
n | number | 0 to 65,535 |
Throws: "Not enough data to read uint16" if there are insufficient bytes to read.
const sia = new Sia();
sia.addUInt16(65535);
sia.seek(0);
console.log(sia.readUInt16()); // 65535
addUInt32(n) / readUInt32()
Writes or reads an unsigned 32-bit integer (0 to 4,294,967,295). Stored as 4 bytes in little-endian order.
addUInt32(n: number): Sia
readUInt32(): number
| Parameter | Type | Range |
|---|---|---|
n | number | 0 to 4,294,967,295 |
Throws: "Not enough data to read uint32" if there are insufficient bytes to read.
const sia = new Sia();
sia.addUInt32(4294967295);
sia.seek(0);
console.log(sia.readUInt32()); // 4294967295
addUInt64(n) / readUInt64()
Writes or reads an unsigned 64-bit integer. The value is split into two 32-bit halves and stored in little-endian order (lower 32 bits first, then upper 32 bits).
addUInt64(n: number): Sia
readUInt64(): number
| Parameter | Type | Range |
|---|---|---|
n | number | 0 to 2^53 - 1 (Number.MAX_SAFE_INTEGER) |
Throws: "Not enough data to read uint64" if there are insufficient bytes to read.
number uses IEEE 754 double-precision floating point, which only
provides 53 bits of integer precision. Values above Number.MAX_SAFE_INTEGER
(9,007,199,254,740,991) will lose precision. For larger values, use
addBigInt instead.const sia = new Sia();
sia.addUInt64(Number.MAX_SAFE_INTEGER);
sia.seek(0);
console.log(sia.readUInt64()); // 9007199254740991
Signed Integers
addInt8(n) / readInt8()
Writes or reads a signed 8-bit integer (-128 to 127).
addInt8(n: number): Sia
readInt8(): number
| Parameter | Type | Range |
|---|---|---|
n | number | -128 to 127 |
Throws: "Not enough data to read int8" if there are insufficient bytes to read.
const sia = new Sia();
sia.addInt8(-120);
sia.seek(0);
console.log(sia.readInt8()); // -120
addInt16(n) / readInt16()
Writes or reads a signed 16-bit integer (-32,768 to 32,767). Stored as 2 bytes in little-endian order.
addInt16(n: number): Sia
readInt16(): number
| Parameter | Type | Range |
|---|---|---|
n | number | -32,768 to 32,767 |
Throws: "Not enough data to read int16" if there are insufficient bytes to read.
const sia = new Sia();
sia.addInt16(-32768);
sia.seek(0);
console.log(sia.readInt16()); // -32768
addInt32(n) / readInt32()
Writes or reads a signed 32-bit integer (-2,147,483,648 to 2,147,483,647). Stored as 4 bytes in little-endian order.
addInt32(n: number): Sia
readInt32(): number
| Parameter | Type | Range |
|---|---|---|
n | number | -2,147,483,648 to 2,147,483,647 |
Throws: "Not enough data to read int32" if there are insufficient bytes to read.
const sia = new Sia();
sia.addInt32(-2147483648);
sia.seek(0);
console.log(sia.readInt32()); // -2147483648
addInt64(n) / readInt64()
Writes or reads a signed 64-bit integer. The value is split into a lower unsigned 32-bit half and an upper signed 32-bit half, stored in little-endian order.
addInt64(n: number): Sia
readInt64(): number
| Parameter | Type | Range |
|---|---|---|
n | number | -(2^53 - 1) to 2^53 - 1 |
Throws: "Not enough data to read int64" if there are insufficient bytes to read.
addUInt64, precision is limited to Number.MIN_SAFE_INTEGER through
Number.MAX_SAFE_INTEGER due to JavaScript's floating-point number
representation. For arbitrary-precision integers, use
addBigInt.const sia = new Sia();
sia.addInt64(Number.MIN_SAFE_INTEGER);
sia.seek(0);
console.log(sia.readInt64()); // -9007199254740991
Byte Sizes
| Method | Bytes Written | Unsigned Range | Signed Range |
|---|---|---|---|
UInt8 / Int8 | 1 | 0 – 255 | -128 – 127 |
UInt16 / Int16 | 2 | 0 – 65,535 | -32,768 – 32,767 |
UInt32 / Int32 | 4 | 0 – 4,294,967,295 | -2,147,483,648 – 2,147,483,647 |
UInt64 / Int64 | 8 | 0 – 2^53-1 | -(2^53-1) – 2^53-1 |
Complete Example
A roundtrip demonstrating all integer types:
import { Sia } from "@timeleap/sia";
const sia = new Sia();
// Write various integer types
sia
.addUInt8(200)
.addInt8(-100)
.addUInt16(50000)
.addInt16(-30000)
.addUInt32(3000000000)
.addInt32(-1500000000)
.addUInt64(9007199254740991)
.addInt64(-9007199254740991);
// Read them back
sia.seek(0);
console.log(sia.readUInt8()); // 200
console.log(sia.readInt8()); // -100
console.log(sia.readUInt16()); // 50000
console.log(sia.readInt16()); // -30000
console.log(sia.readUInt32()); // 3000000000
console.log(sia.readInt32()); // -1500000000
console.log(sia.readUInt64()); // 9007199254740991
console.log(sia.readInt64()); // -9007199254740991