Writing

Create the Byte Stream Provider

First, create the byte stream provider to access the data source.

>>> # Create the byte stream provider for the data source.
>>> provider = FileProvider('./_static/writing.bin')
>>> provider.cache
bytearray(b"\x0f\x00KonFoo is \'Fun\'")

Note

We use here a FileProvider but you can write your own provider class to access any kind of data source.

Create the Byte Stream Mapper

Second, create the byte stream mapper for the binary data to be mapped in the data source.

>>> # Create the byte stream mapper.
>>> mapper = Structure(length = Decimal16(), content = String(15))

Create the Byte Stream Writer

Third, create a writer for the byte stream mapper to the data source by attaching the byte stream mapper to the data object of a pointer field.

>>> # Create the byte stream writer.
>>> writer = Pointer(mapper)

>>> # List the field values of the pointer and data object.
>>> writer.to_list()
[('Pointer.field', '0x0'),
 ('Pointer.data.length', 0),
 ('Pointer.data.content', '')]

>>> # List the field values of the pointer and data object as a CSV list.
>>> writer.to_csv()
[{'id': 'Pointer.field', 'value': '0x0'},
 {'id': 'Pointer.data.length', 'value': 0},
 {'id': 'Pointer.data.content', 'value': ''}]

>>> # View the pointer and data object field values as a JSON string.
>>> writer.to_json()
'{"value": "0x0",
  "data": {"length": 0, "content": ""}}'

Read from the Data Source

Fourth, read the required byte stream for the data object attached to the pointer field with the byte stream provider from the data source by calling the method read_from() of the pointer field.

>>> # Read from the provider the byte stream
>>> writer.read_from(provider, null_allowed=True)
>>> bytes.fromhex(writer.bytestream)
b"\x0f\x00KonFoo is 'Fun'"

>>> # List the field values of the data object.
>>> writer.data.to_list()
[('Structure.length', 15),
 ('Structure.content', "KonFoo is 'Fun'")]

>>> # List the field values of the data object as a CSV list.
>>> writer.data.to_csv()
[{'id': 'Structure.length', 'value': 15},
 {'id': 'Structure.content', 'value': "KonFoo is 'Fun'"}]

>>> # View the data object field values as a JSON string.
>>> writer.data.to_json()
'{"length": 15, "content": "KonFoo is \'Fun\'"}'

Write to the Data Source

Fifth, write the field value of any field of the data object attached to a pointer to a data source with the byte stream provider by calling method write_to().

>>> writer.data.length.value = 0x0f00
>>> # Write to the provider the bytes represented by the field.
>>> writer.write_to(provider, writer.data.length)
>>> provider.cache
bytearray(b"\x00\x0fKonFoo is \'Fun\'")
>>> bytes.fromhex(writer.bytestream)
b"\x0f\x00KonFoo is 'Fun'"

or write the field values of any container of the data object attached to a pointer to a data source with the byte stream provider by calling method write_to().

>>> writer.data.length.value = 14
>>> writer.data.content.value = 'Konfoo is Fun'
>>> # Write to the provider the bytes represented by the container.
>>> writer.write_to(provider, writer.data)
>>> provider.cache
bytearray(b'\x0e\x00Konfoo is Fun\x00\x00')
>>> bytes.fromhex(writer.bytestream)
b"\x0f\x00KonFoo is 'Fun'"