# 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](#instantiating-hex)

* [Converting from Hex](#converting-from-hex)

* [Concatenating Hex](#concatenating-hex)

* [Slicing Hex](#slicing-hex)

* [Padding Hex](#padding-hex)

* [Trimming Hex](#trimming-hex)

### Instantiating Hex

Values can be instantiated as [`Hex.Hex`](/api/Hex/types#hex) using:

* [`Hex.fromBoolean`](/api/Hex/fromBoolean)

* [`Hex.fromBytes`](/api/Hex/fromBytes)

* [`Hex.fromNumber`](/api/Hex/fromNumber)

* [`Hex.fromString`](/api/Hex/fromString)

```ts twoslash
import { Bytes, Hex } from 'ox'

const value_boolean = Hex.fromBoolean(true)
// @log: '0x1'

const value_bytes = Hex.fromBytes(Bytes.from([1, 2, 3]))
// @log: '0x010203'

const value_number = Hex.fromNumber(1234567890)
// @log: '0x499602d2'

const value_string = Hex.fromString('Hello World!')
// @log: '0x48656c6c6f20576f726c6421'
```

### Converting from Hex

Values can be converted from [`Hex.Hex`](/api/Hex/types#hex) using:

* [`Hex.toBoolean`](/api/Hex/toBoolean)

* [`Hex.toBytes`](/api/Hex/toBytes)

* [`Hex.toNumber`](/api/Hex/toNumber)

* [`Hex.toString`](/api/Hex/toString)

```ts twoslash
import { Hex } from 'ox'

const value_boolean = Hex.toBoolean('0x1')
// @log: true

const value_bytes = Hex.toBytes('0x010203')
// @log: Uint8Array [1, 2, 3]

const value_number = Hex.toNumber('0x499602d2')
// @log: 1234567890

const value_string = Hex.toString(
  '0x48656c6c6f20576f726c6421'
)
// @log: 'Hello World!'
```

### Concatenating Hex

Hex values can be concatenated using [`Hex.concat`](/api/Hex/concat):

```ts twoslash
import { Hex } from 'ox'

const a = Hex.fromString('0x1234567890abcdef')
const b = Hex.fromString('0xdeadbeef')
const c = Hex.concat(a, b)
// @log: '0x1234567890abcdefdeadbeef'
```

### Slicing Hex

Hex values can be sliced using [`Hex.slice`](/api/Hex/slice):

```ts twoslash
import { Hex } from 'ox'

const value = Hex.slice('0x1234567890abcdefdeadbeef', 2, 8)
// @log: '0x34567890'
```

### Padding Hex

Hex values can be padded with zeroes using [`Hex.padLeft`](/api/Hex/padLeft) or [`Hex.padRight`](/api/Hex/padRight):

```ts twoslash
import { Hex } from 'ox'

const value = Hex.padLeft('0x1234567890abcdef', 16)
// @log: '0x00000000000000001234567890abcdef'
```

### Trimming Hex

Hex values can be trimmed of zeroes using [`Hex.trimLeft`](/api/Hex/trimLeft) or [`Hex.trimRight`](/api/Hex/trimRight):

```ts twoslash
import { Hex } from 'ox'

const value = Hex.trimLeft(
  '0x00000000000000001234567890abcdef'
)
// @log: '0x1234567890abcdef'
```

## Functions

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

## Errors

| Name                | Description                         |
| ------------------- | ----------------------------------- |
| [`Hex.InvalidHexBooleanError`](/api/Hex/errors#hexinvalidhexbooleanerror) | Thrown when the provided hex value cannot be represented as a boolean. |
| [`Hex.InvalidHexTypeError`](/api/Hex/errors#hexinvalidhextypeerror) | Thrown when the provided value is not a valid hex type. |
| [`Hex.SizeExceedsPaddingSizeError`](/api/Hex/errors#hexsizeexceedspaddingsizeerror) | Thrown when the size of the value exceeds the pad size. |
| [`Hex.SizeOverflowError`](/api/Hex/errors#hexsizeoverflowerror) | Thrown when the size of the value exceeds the expected max size. |
| [`Hex.SliceOffsetOutOfBoundsError`](/api/Hex/errors#hexsliceoffsetoutofboundserror) | Thrown when the slice offset exceeds the bounds of the value. |

## Types

| Name                | Description                         |
| ------------------- | ----------------------------------- |
| [`Hex.Hex`](/api/Hex/types#hexhex) | Root type for a Hex string. |
| [`Hex.IntegerOutOfRangeError`](/api/Hex/types#hexintegeroutofrangeerror) | Re-exported from `internal/codec/int.ts`. |
| [`Hex.InvalidHexValueError`](/api/Hex/types#hexinvalidhexvalueerror) | Re-exported from `internal/codec/hex.ts`. |
| [`Hex.InvalidLengthError`](/api/Hex/types#hexinvalidlengtherror) | Re-exported from `internal/codec/hex.ts`. |