bigint-pack

Simple BigInt to binary packer/unpacker.

How it works

BigInt is arbitrary integer type, and cannot be represented as a fixed-width integer. For example BigInt 1 can be represented in memory as an object as follows:

{
    "sign": 0,
    "bytes": [1]
}

Where sign is the integer sign and bytes is the number representation.

This packer uses 1 bit for integer sign + 7 bits for byte length, allowing up to 127 bytes to represent number.

Byte order is always little-endian.

For example, we have BigInt -5: Negative number that fits in 1 byte, will be represented as follows:

|Sign|Length|Bytes| |----|------|-----| | 1 | 1 | [5] |

And in binary form it will look like this:

10000001 00000101
^^       ^
||       |_byte_0_
||
||_7_bit_length_
|
|_1_bit_sign

API Reference

BigIntByteLength(bint) → {number}

Calculate length of packed BigInt.

Parameters:

| Name | Type | Description | |------|--------|--------------------------------| | bint | BigInt | BigInt to calculate length of. |

Throws:

BigIntTooBigError - BigInt too big to pack.

Returns:

Number of bytes contained within packed BigInt.

BigIntPack(bint, target, offset) → {number}

Pack BigInt to bytes.

Parameters:

| Name | Type | Default | Description | |--------|---------------------------|---------|-----------------------------------------------------| | bint | BigInt | | BigInt to pack. | | target | BufferLike | | A target to pack into. | | offset | Number | 0 | The offset within target at which to begin packing. |

Throws:

BigIntTooBigError - BigInt too big to pack.

BoundsError - Target not satisfy offset <= target.length - packed_length.

Returns:

Length of packed BigInt.

BigIntPackAlloc(bint) → {Buffer}

Pack BigInt to allocated Buffer.

| Name | Type | Description | |------|--------|-----------------| | bint | BigInt | BigInt to pack. |

Throws:

BigIntTooBigError - BigInt too big to pack.

Returns:

Packed BigInt.

BigIntUnpack(source, offset) → {BigInt}

Unpack BigInt from bytes.

Parameters:

| Name | Type | Default | Description | |--------|---------------------------|---------|-------------------------------------------------------| | source | BufferLike | | Source from which to unpack. | | offset | Number | 0 | The offset within source at which to begin unpacking. |

Throws:

BoundsError - Source not satisfy offset <= source.length - packed_length.

Returns:

Unpacked BigInt.

BigIntTooBigError

Error that occurs when BigInt value is too high.

BoundsError

Error that occurs when accessing invalid offset.

Members:

offset : number - Accessed offset.

BufferLike

Alias for Buffer or Uint8Array or Uint8ClampedArray.

(constant) MAX_PACKED_LENGTH : number

Max length of packed BigInt.

Author

Aikawa Yataro