getArrayCodec

Call Signature

function getArrayCodec<TFrom, TTo>(
    item,
    config,
): FixedSizeCodec<TFrom[], TTo[], 0>;

Returns a codec for encoding and decoding arrays of values.

This codec serializes arrays by encoding each element using the provided item codec. By default, a u32 size prefix is included to indicate the number of items in the array. The size option can be used to modify this behaviour.

Type Parameters

Type Parameter	Default type	Description
`TFrom`	-	The type of the elements to encode.
`TTo`	`TFrom`	The type of the decoded elements.

Parameters

Parameter	Type	Description
`item`	`Codec`<`TFrom`, `TTo`>	The codec for each item in the array.
`config`	`ArrayCodecConfig`<`NumberCodec`> & `object`	Optional configuration for the size encoding/decoding strategy.

Returns

FixedSizeCodec<TFrom[], TTo[], 0>

A VariableSizeCodec<TFrom[], TTo[]> for encoding and decoding arrays.

Examples

Encoding and decoding an array of u8 numbers.

const codec = getArrayCodec(getU8Codec());
const bytes = codec.encode([1, 2, 3]);
// 0x03000000010203
//   |       └-- 3 items of 1 byte each.
//   └-- 4-byte prefix telling us to read 3 items.
 
const array = codec.decode(bytes);
// [1, 2, 3]

Using a u16 size prefix instead of u32.

const codec = getArrayCodec(getU8Codec(), { size: getU16Codec() });
const bytes = codec.encode([1, 2, 3]);
// 0x0300010203
//   |   └-- 3 items of 1 byte each.
//   └-- 2-byte prefix telling us to read 3 items.

Using a fixed-size array of 3 items.

const codec = getArrayCodec(getU8Codec(), { size: 3 });
codec.encode([1, 2, 3]);
// 0x010203
//   └-- 3 items of 1 byte each. There must always be 3 items in the array.

Using the "remainder" size strategy.

const codec = getArrayCodec(getU8Codec(), { size: 'remainder' });
codec.encode([1, 2, 3]);
// 0x010203
//   └-- 3 items of 1 byte each. The size is inferred from the remainder of the bytes.

Remarks

The size of the array can be controlled using the size option:

A Codec<number> (e.g. getU16Codec()) stores a size prefix before the array.
A number enforces a fixed number of elements.
"remainder" uses all remaining bytes to infer the array length.

Separate getArrayEncoder and getArrayDecoder functions are available.

const bytes = getArrayEncoder(getU8Encoder()).encode([1, 2, 3]);
const array = getArrayDecoder(getU8Decoder()).decode(bytes);

See

Call Signature

function getArrayCodec<TFrom, TTo>(
    item,
    config,
): FixedSizeCodec<TFrom[], TTo[]>;

Returns a codec for encoding and decoding arrays of values.

Type Parameters

Type Parameter	Default type	Description
`TFrom`	-	The type of the elements to encode.
`TTo`	`TFrom`	The type of the decoded elements.

Parameters

Parameter	Type	Description
`item`	`FixedSizeCodec`<`TFrom`, `TTo`>	The codec for each item in the array.
`config`	`ArrayCodecConfig`<`NumberCodec`> & `object`	Optional configuration for the size encoding/decoding strategy.

Returns

FixedSizeCodec<TFrom[], TTo[]>

A VariableSizeCodec<TFrom[], TTo[]> for encoding and decoding arrays.

Examples

Encoding and decoding an array of u8 numbers.

const codec = getArrayCodec(getU8Codec());
const bytes = codec.encode([1, 2, 3]);
// 0x03000000010203
//   |       └-- 3 items of 1 byte each.
//   └-- 4-byte prefix telling us to read 3 items.
 
const array = codec.decode(bytes);
// [1, 2, 3]

Using a u16 size prefix instead of u32.

const codec = getArrayCodec(getU8Codec(), { size: getU16Codec() });
const bytes = codec.encode([1, 2, 3]);
// 0x0300010203
//   |   └-- 3 items of 1 byte each.
//   └-- 2-byte prefix telling us to read 3 items.

Using a fixed-size array of 3 items.

const codec = getArrayCodec(getU8Codec(), { size: 3 });
codec.encode([1, 2, 3]);
// 0x010203
//   └-- 3 items of 1 byte each. There must always be 3 items in the array.

Using the "remainder" size strategy.

const codec = getArrayCodec(getU8Codec(), { size: 'remainder' });
codec.encode([1, 2, 3]);
// 0x010203
//   └-- 3 items of 1 byte each. The size is inferred from the remainder of the bytes.

Remarks

The size of the array can be controlled using the size option:

A Codec<number> (e.g. getU16Codec()) stores a size prefix before the array.
A number enforces a fixed number of elements.
"remainder" uses all remaining bytes to infer the array length.

Separate getArrayEncoder and getArrayDecoder functions are available.

const bytes = getArrayEncoder(getU8Encoder()).encode([1, 2, 3]);
const array = getArrayDecoder(getU8Decoder()).decode(bytes);

See

Call Signature

function getArrayCodec<TFrom, TTo>(
    item,
    config?,
): VariableSizeCodec<TFrom[], TTo[]>;

Returns a codec for encoding and decoding arrays of values.

Type Parameters

Type Parameter	Default type	Description
`TFrom`	-	The type of the elements to encode.
`TTo`	`TFrom`	The type of the decoded elements.

Parameters

Parameter	Type	Description
`item`	`Codec`<`TFrom`, `TTo`>	The codec for each item in the array.
`config?`	`ArrayCodecConfig`<`NumberCodec`>	Optional configuration for the size encoding/decoding strategy.

Returns

VariableSizeCodec<TFrom[], TTo[]>

A VariableSizeCodec<TFrom[], TTo[]> for encoding and decoding arrays.

Examples

Encoding and decoding an array of u8 numbers.

const codec = getArrayCodec(getU8Codec());
const bytes = codec.encode([1, 2, 3]);
// 0x03000000010203
//   |       └-- 3 items of 1 byte each.
//   └-- 4-byte prefix telling us to read 3 items.
 
const array = codec.decode(bytes);
// [1, 2, 3]

Using a u16 size prefix instead of u32.

const codec = getArrayCodec(getU8Codec(), { size: getU16Codec() });
const bytes = codec.encode([1, 2, 3]);
// 0x0300010203
//   |   └-- 3 items of 1 byte each.
//   └-- 2-byte prefix telling us to read 3 items.

Using a fixed-size array of 3 items.

const codec = getArrayCodec(getU8Codec(), { size: 3 });
codec.encode([1, 2, 3]);
// 0x010203
//   └-- 3 items of 1 byte each. There must always be 3 items in the array.

Using the "remainder" size strategy.

const codec = getArrayCodec(getU8Codec(), { size: 'remainder' });
codec.encode([1, 2, 3]);
// 0x010203
//   └-- 3 items of 1 byte each. The size is inferred from the remainder of the bytes.

Remarks

The size of the array can be controlled using the size option:

A Codec<number> (e.g. getU16Codec()) stores a size prefix before the array.
A number enforces a fixed number of elements.
"remainder" uses all remaining bytes to infer the array length.

Separate getArrayEncoder and getArrayDecoder functions are available.

const bytes = getArrayEncoder(getU8Encoder()).encode([1, 2, 3]);
const array = getArrayDecoder(getU8Decoder()).decode(bytes);

getArrayCodec

On this page