Core API: Repeaters

construct.Array(count, subcon)

Homogenous array of elements. The array will iterate through exactly count elements. This is just a macro around Range.

Operator [] can be used to make instances.

Parameters:
  • count – an integer or a context function that returns such an integer
  • subcon – the subcon to process individual elements

Example:

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

Alternative syntax (recommended):
>>> Byte[3:5], Byte[3:], Byte[:5], Byte[:]
construct.PrefixedArray(lengthfield, subcon)

Homogenous array prefixed by item count (as opposed to prefixed by byte count, see Prefixed()).

Parameters:
  • lengthfield – field parsing and building an integer
  • subcon – subcon to process individual elements

Example:

>>> Prefixed(VarInt, GreedyRange(Int32ul)).parse(b"\x08abcdefgh")
[1684234849, 1751606885]

>>> PrefixedArray(VarInt, Int32ul).parse(b"\x02abcdefgh")
[1684234849, 1751606885]
construct.Range(min, max, subcon)

Homogenous array of elements. The array will iterate through between min to max times. If an exception occurs (EOF, validation error) then repeater exits cleanly. If less than min or more than max elements have been successfully processed, error is raised.

Operator [] can be used to make instances.

See also

Analog to GreedyRange() that parses until end of stream.

Parameters:
  • min – the minimal count, an integer or a context lambda
  • max – the maximal count, an integer or a context lambda
  • subcon – the subcon to process individual elements
Raises:

RangeError – when consumed or produced too little or too many elements

Example:

>>> d = Range(3,5,Byte) or Byte[3:5]
>>> d.parse(b'\x01\x02\x03\x04')
[1,2,3,4]
>>> d.build([1,2,3,4])
b'\x01\x02\x03\x04'
>>> d.build([1,2])
construct.core.RangeError: expected from 3 to 5 elements, found 2
>>> d.build([1,2,3,4,5,6])
construct.core.RangeError: expected from 3 to 5 elements, found 6

Alternative syntax (recommended):
>>> Byte[3:5], Byte[3:], Byte[:5], Byte[:]
construct.GreedyRange(subcon)

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

Operator [] can be used to make instances.

Parameters:subcon – the subcon to process individual elements

Example:

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

Alternative syntax (recommended):
>>> Byte[3:5], Byte[3:], Byte[:5], Byte[:]
construct.RepeatUntil(predicate, subcon)

Homogenous 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 list.

Parameters:
  • predicate – a predicate function that takes (obj, list, context) and returns True to break or False to continue (or a truthy value)
  • subcon – the subcon used to parse and build each element

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]