Core API: Repeaters

construct.Array(count, subcon, discard=False)

Homogenous array of elements, similar to C# generic T[].

Parses into a ListContainer (a list). Parsing and building processes an exact amount of elements. If given list has more or less than count elements, raises RangeError. Size is defined as count multiplied by subcon size, but only if subcon is fixed size.

Operator [] can be used to make Array instances (recommended syntax).

Parameters:

  • count – integer or context lambda, strict amount of elements

  • subcon – Construct instance, subcon to process individual elements

  • discard – optional, bool, if set then parsing returns empty list

Raises:

  • StreamError – requested reading negative amount, could not read enough bytes, requested writing different amount than actual data, or could not write all bytes

  • RangeError – specified count is not valid

  • RangeError – given object has different length than specified count

Can propagate any exception from the lambdas, possibly non-ConstructError.

Example:

>>> d = Array(5, Byte) or Byte[5]
>>> d.build(range(5))
b'\x00\x01\x02\x03\x04'
>>> d.parse(_)
[0, 1, 2, 3, 4]
construct.GreedyRange(subcon, discard=False)

Homogenous array of elements, similar to C# generic IEnumerable<T>, but works with unknown count of elements by parsing until end of stream.

Parses into a ListContainer (a list). Parsing stops when an exception occured when parsing the subcon, either due to EOF or subcon format not being able to parse the data. Either way, when GreedyRange encounters either failure it seeks the stream back to a position after last successful subcon parsing. Builds from enumerable, each element as-is. Size is undefined.

This class supports stopping. If StopIf field is a member, and it evaluates its lambda as positive, this class ends parsing or building as successful without processing further fields.

Parameters:

  • subcon – Construct instance, subcon to process individual elements

  • discard – optional, bool, if set then parsing returns empty list

Raises:

  • StreamError – requested reading negative amount, could not read enough bytes, requested writing different amount than actual data, or could not write all bytes

  • StreamError – stream is not seekable and tellable

Can propagate any exception from the lambdas, possibly non-ConstructError.

Example:

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

Homogenous array of elements, similar to C# generic IEnumerable<T>, that repeats until the predicate indicates it to stop. Note that the last element (that predicate indicated as True) is included in the return list.

Parse iterates indefinately until last element passed the predicate. Build iterates indefinately over given list, until an element passed the precicate (or raises RepeatError if no element passed it). Size is undefined.

Parameters:

  • predicate – lambda that takes (obj, list, context) and returns True to break or False to continue (or a truthy value)

  • subcon – Construct instance, subcon used to parse and build each element

  • discard – optional, bool, if set then parsing returns empty list

Raises:

  • StreamError – requested reading negative amount, could not read enough bytes, requested writing different amount than actual data, or could not write all bytes

  • RepeatError – consumed all elements in the stream but neither passed the predicate

Can propagate any exception from the lambda, possibly non-ConstructError.

Example:

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

>>> d = RepeatUntil(lambda x,lst,ctx: lst[-2:] == [0,0], Byte)
>>> d.parse(b"\x01\x00\x00\xff")
[1, 0, 0]