Core API: Repeaters

construct.Array(count, subcon)

A homogenous array of elements. The array will iterate through exactly count elements. Will raise RangeError if less elements are found.

See also

Base Range() construct.

Parameters

  • count – int or a function that takes context and returns the number of elements

  • subcon – the subcon to process individual elements

Example:

>>> Byte[5].build(range(5))
b'\x00\x01\x02\x03\x04'
>>> Byte[5].parse(_)
[0, 1, 2, 3, 4]

>>> Array(5, Byte).build(range(5))
b'\x00\x01\x02\x03\x04'
>>> Array(5, Byte).parse(_)
[0, 1, 2, 3, 4]
construct.PrefixedArray(lengthfield, subcon)

An array prefixed by a length field.

See also

Analog Array() construct.

Parameters

  • lengthfield – a field parsing and building an integer

  • subcon – the subcon to process individual elements

Example:

>>> PrefixedArray(Byte, Byte).build(range(5))
b'\x05\x00\x01\x02\x03\x04'
>>> PrefixedArray(Byte, Byte).parse(_)
[0, 1, 2, 3, 4]
construct.Range(min, max, subcon)

A homogenous array of elements. The array will iterate through between min to max times. If an exception occurs (EOF, validation error), the repeater exits cleanly. If less than min units have been successfully parsed, a RangeError is raised.

See also

Analog GreedyRange() that parses until end of stream.

Note

This object requires a seekable stream for parsing.

Parameters

  • min – the minimal count

  • max – the maximal count

  • subcon – the subcon to process individual elements

Example:

>>> Range(3, 5, Byte).build([1,2,3,4])
b'\x01\x02\x03\x04'
>>> Range(3, 5, Byte).parse(_)
[1, 2, 3, 4]

>>> Range(3, 5, Byte).build([1,2])
construct.core.RangeError: expected from 3 to 5 elements, found 2
>>> Range(3, 5, Byte).build([1,2,3,4,5,6])
construct.core.RangeError: expected from 3 to 5 elements, found 6
construct.GreedyRange(subcon)

A homogenous array of elements that parses until end of stream and builds from all elements.

Parameters

subcon – the subcon to process individual elements

Example:

>>> GreedyRange(Byte).build(range(10))
b'\x00\x01\x02\x03\x04\x05\x06\x07\x08\t'
>>> GreedyRange(Byte).parse(_)
[0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
construct.RepeatUntil(predicate, subcon)

An array that repeats until the predicate indicates it to stop. Note that the last element (which caused the repeat to exit) is included in the return value.

Parameters

  • predicate – a predicate function that takes (obj, context) and returns True to break, or False to continue

  • subcon – the subcon used to parse and build each element

Example:

>>> RepeatUntil(lambda x,ctx: x>7, Byte).build(range(20))
b'\x00\x01\x02\x03\x04\x05\x06\x07\x08'
>>> RepeatUntil(lambda x,ctx: x>7, Byte).parse(b"\x01\xff\x02")
[1, 255]