BinaryFormat.Group
BinaryReturns a binary format that reads a group of items with a key-value structure.
Syntax
BinaryFormat.Group(binaryFormat as function, group as list, optional extra as nullable function, optional lastKey as any) as functionParameters
| Name | Type | Required | Description |
|---|---|---|---|
binaryFormat | function | Yes | The binary format of the key value. |
group | list | Yes | A list of item definitions. Each item is a list of 3-5 values: key value, item format, BinaryOccurrence type, optional default value, and optional transform function. |
extra | nullable function | No | A function that returns a binary format for values following unexpected keys. If not specified, unexpected keys raise an error. |
lastKey | any | No | The key value of the last item in the group. |
Return Value
function — A binary format function that reads key-value pairs and returns a list of the item values in the order they were defined.
Remarks
BinaryFormat.Group returns a binary format that reads a group of keyed items from binary data. Each item in the stream is preceded by a key, and the group definition maps keys to their binary formats and occurrence rules.
The group parameter is a list of item definitions. Each definition is itself a list with 3-5 elements:
1. Key value -- The expected key that identifies this item. Must be unique within the group. 2. Item format -- The binary format used to read the item's value. 3. Occurrence -- A BinaryOccurrence.Type value: BinaryOccurrence.Required, BinaryOccurrence.Optional, or BinaryOccurrence.Repeating. 4. Default value (optional) -- Used when the item is not found. Defaults to null for optional items and {} for repeating items. 5. Transform function (optional) -- Applied to the item's value before returning. Only called when the item is actually read, never on defaults.
The optional extra function handles unexpected keys. It receives the unexpected key value and should return a binary format to read and discard the associated data. If omitted, unexpected keys raise an error.
Examples
Example 1: Read a group of keyed byte values
let
b = #binary({
1, 11,
2, 22,
2, 22,
5, 55,
1, 11
}),
f = BinaryFormat.Group(
BinaryFormat.Byte,
{
{1, BinaryFormat.Byte, BinaryOccurrence.Required},
{2, BinaryFormat.Byte, BinaryOccurrence.Repeating},
{3, BinaryFormat.Byte, BinaryOccurrence.Optional},
{4, BinaryFormat.Byte, BinaryOccurrence.Repeating}
},
(extra) => BinaryFormat.Byte
)
in
f(b)Example 2: Use default values and transforms
let
b = #binary({
1, 101,
1, 102
}),
f = BinaryFormat.Group(
BinaryFormat.Byte,
{
{1, BinaryFormat.Byte, BinaryOccurrence.Repeating,
0, (list) => List.Sum(list)},
{2, BinaryFormat.Byte, BinaryOccurrence.Optional, 123}
}
)
in
f(b)