Hex

A set of Ethereum-related utility functions for working with hexadecimal string values (e.g. "0xdeadbeef").

Examples

Below are some examples demonstrating common usages of the Hex module:

Instantiating Hex

Values can be instantiated as Hex.Hex using:

import { Bytes, Hex } from 'ox'
 
const value_boolean = Hex.fromBoolean(true)
'0x1'
 const value_bytes = Hex.fromBytes(Bytes.from([1, 2, 3]))
'0x010203'
 const value_number = Hex.fromNumber(1234567890)
'0x499602d2'
 const value_string = Hex.fromString('Hello World!')
'0x48656c6c6f20576f726c6421'

Converting from Hex

Values can be converted from Hex.Hex using:

import { Hex } from 'ox'
 
const value_boolean = Hex.toBoolean('0x1')
true
 const value_bytes = Hex.toBytes('0x010203')
Uint8Array [1, 2, 3]
 const value_number = Hex.toNumber('0x499602d2')
1234567890
 const value_string = Hex.toString('0x48656c6c6f20576f726c6421')
'Hello World!'

Concatenating Hex

Hex values can be concatenated using Hex.concat:

import { Hex } from 'ox'
 
const a = Hex.fromString('0x1234567890abcdef')
const b = Hex.fromString('0xdeadbeef')
const c = Hex.concat(a, b)
'0x1234567890abcdefdeadbeef'

Slicing Hex

Hex values can be sliced using Hex.slice:

import { Hex } from 'ox'
 
const value = Hex.slice('0x1234567890abcdefdeadbeef', 2, 8)
'0x34567890'

Padding Hex

Hex values can be padded with zeroes using Hex.padLeft or Hex.padRight:

import { Hex } from 'ox'
 
const value = Hex.padLeft('0x1234567890abcdef', 16)
'0x00000000000000001234567890abcdef'

Trimming Hex

Hex values can be trimmed of zeroes using Hex.trimLeft or Hex.trimRight:

import { Hex } from 'ox'
 
const value = Hex.trimLeft('0x00000000000000001234567890abcdef')
'0x1234567890abcdef'

Functions

Name	Description
`Hex.assert`	Asserts if the given value is `Hex.Hex`.
`Hex.concat`	Concatenates two or more `Hex.Hex`.
`Hex.from`	Instantiates a `Hex.Hex` value from a hex string or `Bytes.Bytes` value.
`Hex.fromBoolean`	Encodes a boolean into a `Hex.Hex` value.
`Hex.fromBytes`	Encodes a `Bytes.Bytes` value into a `Hex.Hex` value.
`Hex.fromNumber`	Encodes a number or bigint into a `Hex.Hex` value.
`Hex.fromString`	Encodes a string into a `Hex.Hex` value.
`Hex.isEqual`	Checks if two `Hex.Hex` values are equal.
`Hex.padLeft`	Pads a `Hex.Hex` value to the left with zero bytes until it reaches the given `size` (default: 32 bytes).
`Hex.padRight`	Pads a `Hex.Hex` value to the right with zero bytes until it reaches the given `size` (default: 32 bytes).
`Hex.random`	Generates a random `Hex.Hex` value of the specified length.
`Hex.size`	Retrieves the size of a `Hex.Hex` value (in bytes).
`Hex.slice`	Returns a section of a `Bytes.Bytes` value given a start/end bytes offset.
`Hex.toBigInt`	Decodes a `Hex.Hex` value into a BigInt.
`Hex.toBoolean`	Decodes a `Hex.Hex` value into a boolean.
`Hex.toBytes`	Decodes a `Hex.Hex` value into a `Bytes.Bytes`.
`Hex.toNumber`	Decodes a `Hex.Hex` value into a number.
`Hex.toString`	Decodes a `Hex.Hex` value into a string.
`Hex.trimLeft`	Trims leading zeros from a `Hex.Hex` value.
`Hex.trimRight`	Trims trailing zeros from a `Hex.Hex` value.
`Hex.validate`	Checks if the given value is `Hex.Hex`.

Errors

Name	Description
`Hex.IntegerOutOfRangeError`	Thrown when the provided integer is out of range, and cannot be represented as a hex value.
`Hex.InvalidHexBooleanError`	Thrown when the provided hex value cannot be represented as a boolean.
`Hex.InvalidHexTypeError`	Thrown when the provided value is not a valid hex type.
`Hex.InvalidHexValueError`	Thrown when the provided hex value is invalid.
`Hex.InvalidLengthError`	Thrown when the provided hex value is an odd length.
`Hex.SizeExceedsPaddingSizeError`	Thrown when the size of the value exceeds the pad size.
`Hex.SizeOverflowError`	Thrown when the size of the value exceeds the expected max size.
`Hex.SliceOffsetOutOfBoundsError`	Thrown when the slice offset exceeds the bounds of the value.

Types

Name	Description
`Hex.Hex`	Root type for a Hex string.