# Bytes

A set of Ethereum-related utility functions for working with [`Uint8Array`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Uint8Array) instances.

## Examples

Below are some examples demonstrating common usages of the `Bytes` module:

* [Instantiating Bytes](#instantiating-bytes)

* [Converting from Bytes](#converting-from-bytes)

* [Concatenating Bytes](#concatenating-bytes)

* [Slicing Bytes](#slicing-bytes)

* [Padding Bytes](#padding-bytes)

* [Trimming Bytes](#trimming-bytes)

### Instantiating Bytes

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

* [`Bytes.fromArray`](/api/Bytes/fromArray)

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

* [`Bytes.fromHex`](/api/Bytes/fromHex)

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

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

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

const value_array = Bytes.from([1, 2, 3, 4, 5])
// @log: Uint8Array [1, 2, 3, 4, 5]

const value_boolean = Bytes.fromBoolean(true)
// @log: Uint8Array [1]

const value_hex = Bytes.fromHex('0x1234567890abcdef')
// @log: Uint8Array [18, 52, 86, 120, 144, 175, 207, 15]

const value_number = Bytes.fromNumber(1234567890)
// @log: Uint8Array [4, 160, 216]

const value_string = Bytes.fromString('Hello World!')
// @log: Uint8Array [72, 101, 108, 108, 111, 32, 87, 111, 114, 108, 100, 33]
```

### Converting from Bytes

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

* [`Bytes.toBigInt`](/api/Bytes/toBigInt)

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

* [`Bytes.toHex`](/api/Bytes/toHex)

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

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

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

const value_bigint = Bytes.toBigInt(
  Bytes.from([4, 160, 216])
)
// @log: 1234567890n

const value_boolean = Bytes.toBoolean(Bytes.from([1]))
// @log: true

const value_hex = Bytes.toHex(
  Bytes.from([222, 173, 190, 239])
)
// @log: '0xdeadbeef'

const value_number = Bytes.toNumber(
  Bytes.from([4, 160, 216])
)
// @log: 1234567890

const value_string = Bytes.toString(
  Bytes.from([
    72, 101, 108, 108, 111, 32, 87, 111, 114, 108, 100, 33
  ])
)
// @log: 'Hello World!'
```

### Concatenating Bytes

Values can be concatenated using [`Bytes.concat`](/api/Bytes/concat):

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

const a = Bytes.from([1, 2, 3])
const b = Bytes.from([4, 5, 6])
const c = Bytes.concat(a, b)
// @log: Uint8Array [1, 2, 3, 4, 5, 6]
```

### Slicing Bytes

Values can be sliced using [`Bytes.slice`](/api/Bytes/slice):

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

const value = Bytes.slice(
  Bytes.from([1, 2, 3, 4, 5, 6]),
  2,
  4
)
// @log: Uint8Array [3, 4]
```

### Padding Bytes

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

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

const value_1 = Bytes.padLeft(Bytes.from([1, 2, 3]), 5)
// @log: Uint8Array [0, 0, 1, 2, 3]

const value_2 = Bytes.padRight(Bytes.from([1, 2, 3]), 5)
// @log: Uint8Array [1, 2, 3, 0, 0]
```

### Trimming Bytes

Zeroes in values can be trimmed using [`Bytes.trimLeft`](/api/Bytes/trimLeft) or [`Bytes.trimRight`](/api/Bytes/trimRight):

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

const value = Bytes.trimLeft(Bytes.from([0, 0, 1, 2, 3]))
// @log: Uint8Array [1, 2, 3]
```

## Functions

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

## Errors

| Name                | Description                         |
| ------------------- | ----------------------------------- |
| [`Bytes.InvalidBytesBooleanError`](/api/Bytes/errors#bytesinvalidbytesbooleanerror) | Thrown when the bytes value cannot be represented as a boolean. |
| [`Bytes.InvalidBytesTypeError`](/api/Bytes/errors#bytesinvalidbytestypeerror) | Thrown when a value cannot be converted to bytes. |
| [`Bytes.SizeExceedsPaddingSizeError`](/api/Bytes/errors#bytessizeexceedspaddingsizeerror) | Thrown when a the padding size exceeds the maximum allowed size. |
| [`Bytes.SizeOverflowError`](/api/Bytes/errors#bytessizeoverflowerror) | Thrown when a size exceeds the maximum allowed size. |
| [`Bytes.SliceOffsetOutOfBoundsError`](/api/Bytes/errors#bytessliceoffsetoutofboundserror) | Thrown when a slice offset is out-of-bounds. |

## Types

| Name                | Description                         |
| ------------------- | ----------------------------------- |
| [`Bytes.Bytes`](/api/Bytes/types#bytesbytes) | Root type for a Bytes array. |