Cursors

The most basic element of this package is the Cursor. Roughly, a Cursor represents some data + a selection of it.

Let’s build our first Cursor:

from byteparsing import Cursor

data = b"Hello world!"

c = Cursor(data, begin=0, end=3)
print(c)

Cursor(data=b'Hello world!', begin=0, end=3, encoding='utf-8')

The Cursor is implemented as a dataclass. This means that it contains fields (particularly: data, begin, end, and encoding), and also methods.

For instance, the method content returns the subsetted data (i.e.: the data between begin and end):

c.content # This method is decorated as a property, so parentheses are not needed

b'Hel'

The method increment returns a new cursor where end has been increased (by default, to end + 1).

c = Cursor(data, begin=0, end=3)
print(c)
ci = c.increment()
print(ci)

Cursor(data=b'Hello world!', begin=0, end=3, encoding='utf-8')
Cursor(data=b'Hello world!', begin=0, end=4, encoding='utf-8')

An interesting property of cursors is that they can be evaluated to a boolean. Particularly, a Cursor is True if and only if end is not at the end of the data string.

cT = Cursor(data, begin=0, end=0)
cF = Cursor(data, begin=0, end=len(data))

assert(cT)
assert(not cF)

Wait a second. Why would we want a Cursor to be True or False? The reason is that it is very convenient for easily looping “to the end of the data”.

See for instance the loop below:

c = Cursor(data, begin=0, end=0)
while c:
    c = c.increment()
    print(c.content)

b'H'
b'He'
b'Hel'
b'Hell'
b'Hello'
b'Hello '
b'Hello w'
b'Hello wo'
b'Hello wor'
b'Hello worl'
b'Hello world'
b'Hello world!'