Codec for array types.

Internal to minato. The supported surface is minato_codec.

Wire format

The binary representation is a header followed by one length prefixed value per element, in row-major order:

int32   ndim          number of dimensions, 0 for an empty array
int32   flags         bit 0 set when any element is NULL
uint32  element_oid   the type OID of the elements
        per dimension:
int32     size        number of elements along that dimension
int32     lower_bound index of the first element, 1 by default
        per element:
int32     length      byte length, or -1 for NULL
bytes     value       absent when the length is -1

An empty array carries ndim = 0 and no dimension headers at all.

The text representation is {1,2,3}, with {} for empty, an unquoted NULL for a null element, and {{1,2},{3,4}} for nesting. Elements are quoted with " when they are empty, when they would read as the literal NULL, or when they contain a brace, a comma, a quote, a backslash or whitespace; inside quotes, " and \ are backslash escaped. A leading [1:3]= dimension prefix is skipped when decoding and never produced when encoding.

Erlang representation

Arrays are plain lists.

Encoding always produces a one dimensional array with a lower bound of 1. A nested list is not treated as a nested array: it is handed to the element codec, so [[1,2]] encodes as an _int8 only if the element codec accepts [1,2], which it does not. This is deliberate. For _text a list is valid iodata(), so guessing at nesting would silently change the meaning of a list of strings.

Decoding handles any number of dimensions, returning nested lists in row-major order, so a 2 by 2 array decodes to [[1,2],[3,4]]. Such a value cannot be encoded back without flattening it first.

Lower bounds are not represented in the Erlang term. An array with a lower bound other than 1 decodes to the same list as one with a lower bound of 1.

The element type OID in the binary header is written when encoding and ignored when decoding: the element type follows from the array type OID, which is the only thing the text format carries as well.