Class Cursor

source code

object --+
         |
        Cursor

Byte array cursor

Represents a position within a byte array.

encode_* operations write data at the current position and advance it by the number of bytes written.

decode_* operations read data at the current position, advance it by the number of bytes read, and return the result.

Cursors support in-place addition and subtraction (+=,-=) of integer values to manually adjust position, as well as ordinary addition and subtraction, which return a new cursor without modifiying the original.

Ordinary subtraction of two cursors will yield the difference between their positions as an integer. ==, !=, <, <=, >, and >= operators will also work to compare positions. The results will only be meaningful for cursors referencing the same underlying array.

For a given cursor, cursor.hole.encode_* will perform the same operation as cursor.encode_*, but will return a hole object. Calling this hole object with the same type of arguments as the original encode method will overwrite the original value. This mechanism is useful for backpatching values into fields that aren't known until later, such as internal packet lengths and offsets or checksum fields. For example:

   hole = cursor.hole.encode_uint32le(0)
   # Encode rest of packet
   ...
   # Overwrite value with calculated checksum
   hole(sum)

Cursors support slicing to extract sections of the underlying array. For example:

   # Extract array slice between cur1 and cur2
   subarray = cur1[:cur2]

Cursors also support establishing boundaries outside of which decoding will raise exceptions:

   with cur.bounded(startcur, endcur):
       # Within this block, attempts to decode data outside of
       # the range starting with startcur (inclusive) and ending
       # with endcur (exclusive) will raise BufferOverrun().
       # If the start and end paremeters are numbers rather than
       # other cursors, they will be taken to be relative to
       # cur itself.
       ...