cbytesparse.c.bytesparse¶

class cbytesparse.c.bytesparse(start: Optional[Address] = None, *args: Any, endex: Optional[Address] = None)¶

Wrapper for more bytearray compatibility.

This wrapper class can make Memory closer to the actual bytearray API.

For instantiation, please refer to bytearray.__init__().

With respect to Memory, negative addresses are not allowed. Instead, negative addresses are to consider as referred to endex.

Parameters

source –
The optional source parameter can be used to initialize the array in a few different ways:
- If it is a string, you must also give the encoding (and optionally, errors) parameters; it then converts the string to bytes using str.encode().
- If it is an integer, the array will have that size and will be initialized with null bytes.
- If it is an object conforming to the buffer interface, a read-only buffer of the object will be used to initialize the byte array.
- If it is an iterable, it must be an iterable of integers in the range 0 <= x < 256, which are used as the initial contents of the array.
encoding (str) – Optional string encoding.
errors (str) – Optional string error management.
start (int) – Optional memory start address. Anything before will be trimmed away. If source is provided, its data start at this address (0 if start is None).
endex (int) – Optional memory exclusive end address. Anything at or after it will be trimmed away.

Methods

`__init__`
`append`	Appends a single item.
`append_backup`	Backups an append() operation.
`append_restore`	Restores an append() operation.
`block_span`
`blocks`
`bound`
`clear`
`clear_backup`
`clear_restore`	Restores a clear() operation.
`content_items`	Iterates over content address and value pairs.
`content_keys`	Iterates over content addresses.
`content_values`	Iterates over content values.
`copy`	Creates a shallow copy.
`count`
`crop`
`crop_backup`
`crop_restore`	Restores a crop() operation.
`cut`
`delete`
`delete_backup`
`delete_restore`	Restores a delete() operation.
`equal_span`
`extend`	Concatenates items.
`extend_backup`	Backups an extend() operation.
`extend_restore`	Restores an extend() operation.
`extract`
`fill`
`fill_backup`
`fill_restore`	Restores a fill() operation.
`find`
`flood`
`flood_backup`
`flood_restore`	Restores a flood() operation.
`from_blocks`
`from_bytes`
`from_items`	Creates a virtual memory from a iterable address/byte mapping.
`from_memory`
`from_values`	Creates a virtual memory from a byte-like sequence.
`fromhex`	Creates a virtual memory from an hexadecimal string.
`gaps`
`get`
`hex`	Converts into an hexadecimal string.
`index`
`insert`
`insert_backup`
`insert_restore`	Restores an insert() operation.
`intervals`
`items`
`keys`
`ofind`
`peek`
`poke`
`poke_backup`
`poke_restore`	Restores a poke() operation.
`pop`
`pop_backup`
`pop_restore`	Restores a pop() operation.
`popitem`	Pops the last item.
`popitem_backup`	Backups a popitem() operation.
`popitem_restore`	Restores a popitem() operation.
`remove`
`remove_backup`
`remove_restore`	Restores a remove() operation.
`reserve`
`reserve_backup`
`reserve_restore`	Restores a reserve() operation.
`reverse`	Reverses the memory in-place.
`rfind`
`rindex`
`rofind`
`rvalues`
`setdefault`
`setdefault_backup`
`setdefault_restore`	Restores a setdefault() operation.
`shift`
`shift_backup`
`shift_restore`	Restores an shift() operation.
`to_blocks`	Exports into blocks.
`to_bytes`	Exports into bytes.
`update`	Updates data.
`update_backup`	Backups an update() operation.
`update_restore`	Restores an update() operation.
`validate`	Validates internal structure.
`values`
`view`
`write`
`write_backup`
`write_restore`	Restores a write() operation.

Attributes

`content_endex`	Exclusive content end address.
`content_endin`	Inclusive content end address.
`content_parts`	Number of blocks.
`content_size`	Actual content size.
`content_span`	Memory content address span.
`content_start`	Inclusive content start address.
`contiguous`	Contains contiguous data.
`endex`	Exclusive end address.
`endin`	Inclusive end address.
`span`	Memory address span.
`start`	Inclusive start address.
`trim_endex`
`trim_span`
`trim_start`

__add__(value, /)¶: Return self+value.

__bool__()¶: self != 0

__bytes__()¶

Creates a bytes clone.

Returns: bytes – Cloned data.
Raises: ValueError – Data not contiguous (see contiguous).

__contains__()¶

Checks if some items are contained.

Parameters: item (items) – Items to find. Can be either some byte string or an integer.
Returns: bool – Item is contained.

Examples

>>> from cbytesparse.c import Memory

0	1	2	3	4	5	6	7	8	9	10	11
	[A	B	C]		[1	2	3]		[x	y	z]

>>> memory = Memory.from_blocks([[1, b'ABC'], [5, b'123'], [9, b'xyz']])
>>> b'23' in memory
True
>>> ord('y') in memory
True
>>> b'$' in memory
False

__copy__()¶

Creates a shallow copy.

Note

The Cython implementation actually creates a deep copy.

Returns: ImmutableMemory – Shallow copy.

__deepcopy__()¶

Creates a deep copy.

Returns: ImmutableMemory – Deep copy.

__delitem__(key, /)¶: Delete self[key].

__eq__()¶

Equality comparison.

Parameters

other (Memory) –

Data to compare with self.

If it is a ImmutableMemory, all of its blocks must match.

If it is a bytes, a bytearray, or a memoryview, it is expected to match the first and only stored block.

Otherwise, it must match the first and only stored block, via iteration over the stored values.

Returns

bool – self is equal to other.

Examples

>>> from cbytesparse.c import Memory

>>> data = b'Hello, World!'
>>> memory = Memory.from_bytes(data)
>>> memory == data
True
>>> memory.shift(1)
>>> memory == data
True

>>> data = b'Hello, World!'
>>> memory = Memory.from_bytes(data)
>>> memory == list(data)
True
>>> memory.shift(1)
>>> memory == list(data)
True

__ge__(value, /)¶: Return self>=value.

__getitem__(key, /)¶: Return self[key].

__gt__(value, /)¶: Return self>value.

__hash__ = None¶

__iadd__(value, /)¶: Return self+=value.

__imul__(value, /)¶: Return self*=value.

__init__(*args, **kwargs)¶

__iter__()¶

Iterates over values.

Iterates over values between start and endex.

Yields: int – Value as byte integer, or None.

__le__(value, /)¶: Return self<=value.

__len__()¶

Actual length.

Computes the actual length of the stored items, i.e. (endex - start). This will consider any trimmings being active.

Returns: int – Memory length.

__lt__(value, /)¶: Return self<value.

__mul__(value, /)¶: Return self*value.

__ne__(value, /)¶: Return self!=value.

__new__(**kwargs)¶

__radd__(value, /)¶: Return value+self.

__reduce__()¶: bytesparse.__reduce_cython__(self)

__repr__()¶: Return repr(self).

__reversed__()¶

Iterates over values, reversed order.

Iterates over values between start and endex, in reversed order.

Yields: int – Value as byte integer, or None.

__rmul__(value, /)¶: Return value*self.

__setitem__(key, value, /)¶: Set self[key] to value.

__setstate__()¶: bytesparse.__setstate_cython__(self, __pyx_state)

__str__()¶

String representation.

If content_size is lesser than STR_MAX_CONTENT_SIZE, then the memory is represented as a list of blocks.

If exceeding, it is equivalent to __repr__().

Returns: str – String representation.

Examples

>>> from cbytesparse.c import Memory

0	1	2	3	4	5	6	7	8	9	10
	[A	B	C]				[x	y	z]

>>> memory = Memory.from_blocks([[1, b'ABC'], [7, b'xyz']])
>>> str(memory)
<[[1, b'ABC'], [7, b'xyz']]>

_block_index_at(address)¶

Locates the block enclosing an address.

Returns the index of the block enclosing the given address.

Parameters: address (int) – Address of the target item.
Returns: int – Block index if found, None otherwise.

Examples

>>> from cbytesparse.c import Memory

0	1	2	3	4	5	6	7	8	9	10	11
	[A	B	C	D]		[$]		[x	y	z]
	0	0	0	0		1		2	2	2

>>> memory = Memory.from_blocks([[1, b'ABCD'], [6, b'$'], [8, b'xyz']])
>>> [memory._block_index_at(i) for i in range(12)]
[None, 0, 0, 0, 0, None, 1, None, 2, 2, 2, None]

_block_index_endex(address)¶

Locates the last block before an address range.

Returns the index of the last block whose end address is lesser than or equal to address.

Useful to find the termination block index in a ranged search.

Parameters: address (int) – Exclusive end address of the scanned range.
Returns: int – First block index before address.

Examples

>>> from cbytesparse.c import Memory

0	1	2	3	4	5	6	7	8	9	10	11
	[A	B	C	D]		[$]		[x	y	z]
0	1	1	1	1	1	2	2	3	3	3	3

>>> memory = Memory.from_blocks([[1, b'ABCD'], [6, b'$'], [8, b'xyz']])
>>> [memory._block_index_endex(i) for i in range(12)]
[0, 1, 1, 1, 1, 1, 2, 2, 3, 3, 3, 3]

_block_index_start(address)¶

Locates the first block inside of an address range.

Returns the index of the first block whose start address is greater than or equal to address.

Useful to find the initial block index in a ranged search.

Parameters: address (int) – Inclusive start address of the scanned range.
Returns: int – First block index since address.

Examples

>>> from cbytesparse.c import Memory

0	1	2	3	4	5	6	7	8	9	10	11
	[A	B	C	D]		[$]		[x	y	z]
0	0	0	0	0	1	1	2	2	2	2	3

>>> memory = Memory.from_blocks([[1, b'ABCD'], [6, b'$'], [8, b'xyz']])
>>> [memory._block_index_start(i) for i in range(12)]
[0, 0, 0, 0, 0, 1, 1, 2, 2, 2, 2, 3]

_pretrim_endex(start_min, size)¶

Trims final data.

Low-level method to manage trimming of data starting from an address.

Parameters

start_min (int) – Starting address of the erasure range. If None, trim_endex minus size is considered.
size (int) – Size of the erasure range.

See also

_pretrim_endex_backup()

_pretrim_endex_backup(start_min, size)¶

Backups a _pretrim_endex() operation.

Parameters

start_min (int) – Starting address of the erasure range. If None, trim_endex minus size is considered.
size (int) – Size of the erasure range.

Returns

ImmutableMemory – Backup memory region.

See also

_pretrim_endex()

_pretrim_start(endex_max, size)¶

Trims initial data.

Low-level method to manage trimming of data starting from an address.

Parameters

endex_max (int) – Exclusive end address of the erasure range. If None, trim_start plus size is considered.
size (int) – Size of the erasure range.

See also

_pretrim_start_backup()

_pretrim_start_backup(endex_max, size)¶

Backups a _pretrim_start() operation.

Parameters

endex_max (int) – Exclusive end address of the erasure range. If None, trim_start plus size is considered.
size (int) – Size of the erasure range.

Returns

ImmutableMemory – Backup memory region.

See also

_pretrim_start()

_rectify_address(address)¶

Rectifies an address.

In case the provided address is negative, it is recomputed as referred to endex.

In case the rectified address would still be negative, an exception is raised.

Parameters: address (int) – Address to be rectified.
Returns: int – Rectified address.
Raises: IndexError – The rectified address would still be negative.

_rectify_span(start, endex)¶

Rectifies an address span.

In case a provided address is negative, it is recomputed as referred to endex.

In case the rectified address would still be negative, it is clamped to address zero.

Parameters

start (int) – Inclusive start address for rectification. If None, start is considered.
endex (int) – Exclusive end address for rectification. If None, endex is considered.

Returns

pair of int – Rectified address span.

append(item)¶

Appends a single item.

Parameters: item (int) – Value to append. Can be a single byte string or integer.

See also

append_backup() append_restore()

Examples

>>> from cbytesparse.c import Memory

>>> memory = Memory()
>>> memory.append(b'$')
>>> memory.to_blocks()
[[0, b'$']]

~~~

>>> memory = Memory()
>>> memory.append(3)
>>> memory.to_blocks()
[[0, b'\x03']]

append_backup()¶

Backups an append() operation.

Returns: None – Nothing.

See also

append() append_restore()

append_restore()¶: Restores an append() operation.

See also

append() append_backup()

block_span(address)¶

blocks(start, endex)¶

bound(start, endex)¶

clear(start, endex)¶

clear_backup(start, endex)¶

clear_restore(backup)¶

Restores a clear() operation.

Parameters: backup (ImmutableMemory) – Backup memory region to restore.

See also

clear() clear_backup()

content_endex¶

Exclusive content end address.

This property holds the exclusive end address of the memory content. By default, it is the current maximmum exclusive end address of the last stored block.

If the memory has no data and no trimming, start is returned.

Trimming is considered only for an empty memory.

Examples

>>> from cbytesparse.c import Memory

>>> Memory().content_endex
0
>>> Memory(endex=8).content_endex
0
>>> Memory(start=1, endex=8).content_endex
1

~~~

0	1	2	3	4	5	6	7	8
	[A	B	C]		[x	y	z]

>>> memory = Memory.from_blocks([[1, b'ABC'], [5, b'xyz']])
>>> memory.content_endex
8

~~~

0	1	2	3	4	5	6	7	8
	[A	B	C]					)))

>>> memory = Memory.from_blocks([[1, b'ABC']], endex=8)
>>> memory.content_endex
4

Type: int

content_endin¶

Inclusive content end address.

This property holds the inclusive end address of the memory content. By default, it is the current maximmum inclusive end address of the last stored block.

If the memory has no data and no trimming, start minus one is returned.

Trimming is considered only for an empty memory.

Examples

>>> from cbytesparse.c import Memory

>>> Memory().content_endin
-1
>>> Memory(endex=8).content_endin
-1
>>> Memory(start=1, endex=8).content_endin
0

~~~

0	1	2	3	4	5	6	7	8
	[A	B	C]		[x	y	z]

>>> memory = Memory.from_blocks([[1, b'ABC'], [5, b'xyz']])
>>> memory.content_endin
7

~~~

0	1	2	3	4	5	6	7	8
	[A	B	C]					)))

>>> memory = Memory.from_blocks([[1, b'ABC']], endex=8)
>>> memory.content_endin
3

Type: int

content_items(start, endex)¶

Iterates over content address and value pairs.

Parameters

start (int) – Inclusive start address. If None, start is considered.
endex (int) – Exclusive end address. If None, endex is considered.

Yields

int – Content address and value pairs.

See also

meth:content_keys meth:content_values

Examples

>>> from cbytesparse.c import Memory

0	1	2	3	4	5	6	7	8	9	10
	[A	B]			[x]		[1	2	3]

>>> memory = Memory.from_blocks([[1, b'AB'], [5, b'x'], [7, b'123']])
>>> dict(memory.content_items())
{1: 65, 2: 66, 5: 120, 7: 49, 8: 50, 9: 51}
>>> dict(memory.content_items(2, 9))
{2: 66, 5: 120, 7: 49, 8: 50}
>>> dict(memory.content_items(3, 5))
{}

content_keys(start, endex)¶

Iterates over content addresses.

Parameters

start (int) – Inclusive start address. If None, start is considered.
endex (int) – Exclusive end address. If None, endex is considered.

Yields

int – Content addresses.

See also

meth:content_items meth:content_values

Examples

>>> from cbytesparse.c import Memory

0	1	2	3	4	5	6	7	8	9	10
	[A	B]			[x]		[1	2	3]

>>> memory = Memory.from_blocks([[1, b'AB'], [5, b'x'], [7, b'123']])
>>> list(memory.content_keys())
[1, 2, 5, 7, 8, 9]
>>> list(memory.content_keys(2, 9))
[2, 5, 7, 8]
>>> list(memory.content_keys(3, 5))
[]

content_parts¶

Number of blocks.

Returns: int – The number of blocks.

Examples

>>> from cbytesparse.c import Memory

>>> Memory().content_parts
0

~~~

0	1	2	3	4	5	6	7	8
	[A	B	C]		[x	y	z]

>>> memory = Memory.from_blocks([[1, b'ABC'], [5, b'xyz']])
>>> memory.content_parts
2

~~~

0	1	2	3	4	5	6	7	8
	[A	B	C]					)))

>>> memory = Memory.from_blocks([[1, b'ABC']], endex=8)
>>> memory.content_parts
1

content_size¶

Actual content size.

Returns: int – The sum of all block lengths.

Examples

>>> from cbytesparse.c import Memory

>>> Memory().content_size
0
>>> Memory(start=1, endex=8).content_size
0

~~~

0	1	2	3	4	5	6	7	8
	[A	B	C]		[x	y	z]

>>> memory = Memory.from_blocks([[1, b'ABC'], [5, b'xyz']])
>>> memory.content_size
6

~~~

0	1	2	3	4	5	6	7	8
	[A	B	C]					)))

>>> memory = Memory.from_blocks([[1, b'ABC']], endex=8)
>>> memory.content_size
3

content_span¶

Memory content address span.

A tuple holding both content_start and content_endex.

Examples

>>> from cbytesparse.c import Memory

>>> Memory().content_span
(0, 0)
>>> Memory(start=1).content_span
(1, 1)
>>> Memory(endex=8).content_span
(0, 0)
>>> Memory(start=1, endex=8).content_span
(1, 1)

~~~

0	1	2	3	4	5	6	7	8
	[A	B	C]		[x	y	z]

>>> memory = Memory.from_blocks([[1, b'ABC'], [5, b'xyz']])
>>> memory.content_span
(1, 8)

Type: tuple of int

content_start¶

Inclusive content start address.

This property holds the inclusive start address of the memory content. By default, it is the current minimum inclusive start address of the first stored block.

If the memory has no data and no trimming, 0 is returned.

Trimming is considered only for an empty memory.

Examples

>>> from cbytesparse.c import Memory

>>> Memory().content_start
0
>>> Memory(start=1).content_start
1
>>> Memory(start=1, endex=8).content_start
1

~~~

0	1	2	3	4	5	6	7	8
	[A	B	C]		[x	y	z]

>>> memory = Memory.from_blocks([[1, b'ABC'], [5, b'xyz']])
>>> memory.content_start
1

~~~

0	1	2	3	4	5	6	7	8
	[[[				[x	y	z]

>>> memory = Memory.from_blocks([[5, b'xyz']], start=1)
>>> memory.content_start
5

Type: int

content_values(start, endex)¶

Iterates over content values.

Parameters

start (int) – Inclusive start address. If None, start is considered.
endex (int) – Exclusive end address. If None, endex is considered.

Yields

int – Content values.

See also

meth:content_items meth:content_keys

Examples

>>> from cbytesparse.c import Memory

0	1	2	3	4	5	6	7	8	9	10
	[A	B]			[x]		[1	2	3]

>>> memory = Memory.from_blocks([[1, b'AB'], [5, b'x'], [7, b'123']])
>>> list(memory.content_values())
[65, 66, 120, 49, 50, 51]
>>> list(memory.content_values(2, 9))
[66, 120, 49, 50]
>>> list(memory.content_values(3, 5))
[]

contiguous¶

Contains contiguous data.

The memory is considered to have contiguous data if there is no empty space between blocks.

If trimming is defined, there must be no empty space also towards it.

Type: bool

copy()¶

Creates a shallow copy.

Note

The Cython implementation actually creates a deep copy.

Returns: ImmutableMemory – Shallow copy.

count(item, start, endex)¶

crop(start, endex)¶

crop_backup(start, endex)¶

crop_restore(backup_start, backup_endex)¶

Restores a crop() operation.

Parameters

backup_start (ImmutableMemory) – Backup memory region to restore at the beginning.
backup_endex (ImmutableMemory) – Backup memory region to restore at the end.

See also

crop() crop_backup()

cut(start, endex, bound)¶

delete(start, endex)¶

delete_backup(start, endex)¶

delete_restore(backup)¶

Restores a delete() operation.

Parameters: backup (ImmutableMemory) – Backup memory region

See also

delete() delete_backup()

endex¶

Exclusive end address.

This property holds the exclusive end address of the virtual space. By default, it is the current maximmum exclusive end address of the last stored block.

If trim_endex not None, that is returned.

If the memory has no data and no trimming, start is returned.

Examples

>>> from cbytesparse.c import Memory

>>> Memory().endex
0

~~~

0	1	2	3	4	5	6	7	8
	[A	B	C]		[x	y	z]

>>> memory = Memory.from_blocks([[1, b'ABC'], [5, b'xyz']])
>>> memory.endex
8

~~~

0	1	2	3	4	5	6	7	8
	[A	B	C]					)))

>>> memory = Memory.from_blocks([[1, b'ABC']], endex=8)
>>> memory.endex
8

Type: int

endin¶

Inclusive end address.

This property holds the inclusive end address of the virtual space. By default, it is the current maximmum inclusive end address of the last stored block.

If trim_endex not None, that minus one is returned.

If the memory has no data and no trimming, start is returned.

Examples

>>> from cbytesparse.c import Memory

>>> Memory().endin
-1

~~~

0	1	2	3	4	5	6	7	8
	[A	B	C]		[x	y	z]

>>> memory = Memory.from_blocks([[1, b'ABC'], [5, b'xyz']])
>>> memory.endin
7

~~~

0	1	2	3	4	5	6	7	8
	[A	B	C]					)))

>>> memory = Memory.from_blocks([[1, b'ABC']], endex=8)
>>> memory.endin
7

Type: int

equal_span(address)¶

extend(items, offset)¶

Concatenates items.

Equivalent to self += items.

Parameters

items (items) – Items to append at the end of the current virtual space.
offset (int) – Optional offset w.r.t. content_endex.

See also

extend_backup() extend_restore()

extend_backup(offset)¶

Backups an extend() operation.

Parameters: offset (int) – Optional offset w.r.t. content_endex.
Returns: int – Content exclusive end address.

See also

extend() extend_restore()

extend_restore(content_endex)¶

Restores an extend() operation.

Parameters: content_endex (int) – Content exclusive end address to restore.

See also

extend() extend_backup()

extract(start, endex, pattern, step, bound)¶

fill(start, endex, pattern)¶

fill_backup(start, endex)¶

fill_restore(backup)¶

Restores a fill() operation.

Parameters: backup (ImmutableMemory) – Backup memory region to restore.

See also

fill() fill_backup()

find(item, start, endex)¶

flood(start, endex, pattern)¶

flood_backup(start, endex)¶

flood_restore(gaps)¶

Restores a flood() operation.

Parameters: gaps (list of open intervals) – Backup memory gaps to restore.

See also

flood() flood_backup()

classmethod from_blocks(blocks, offset, start, endex, copy, validate)¶

classmethod from_bytes(data, offset, start, endex, copy, validate)¶

classmethod from_items(items, offset, start, endex, validate)¶

Creates a virtual memory from a iterable address/byte mapping.

Parameters

items (iterable address/byte mapping) – An iterable mapping of address to byte values. Values of None are translated as gaps. When an address is stated multiple times, the last is kept.
offset (int) – An address offset applied to all the values.
start (int) – Optional memory start address. Anything before will be trimmed away.
endex (int) – Optional memory exclusive end address. Anything at or after it will be trimmed away.
validate (bool) – Validates the resulting ImmutableMemory object.

Returns

ImmutableMemory – The resulting memory object.

Raises

ValueError – Some requirements are not satisfied.

See also

to_bytes()

Examples

>>> from bytesparse.inplace import Memory

>>> memory = Memory.from_values({})
>>> memory.to_blocks()
[]

~~~

0	1	2	3	4	5	6	7	8
		[A	Z]		[x]

>>> items = [
...     (0, ord('A')),
...     (1, ord('B')),
...     (3, ord('x')),
...     (1, ord('Z')),
... ]
>>> memory = Memory.from_items(items, offset=2)
>>> memory.to_blocks()
[[2, b'AZ'], [5, b'x']]

classmethod from_memory(memory, offset, start, endex, copy, validate)¶

classmethod from_values(values, offset, start, endex, validate)¶

Creates a virtual memory from a byte-like sequence.

Parameters

values (iterable byte-like sequence) – An iterable sequence of byte values. Values of None are translated as gaps.
offset (int) – An address offset applied to all the values.
start (int) – Optional memory start address. Anything before will be trimmed away.
endex (int) – Optional memory exclusive end address. Anything at or after it will be trimmed away.
validate (bool) – Validates the resulting ImmutableMemory object.

Returns

ImmutableMemory – The resulting memory object.

Raises

ValueError – Some requirements are not satisfied.

See also

to_bytes()

Examples

>>> from bytesparse.inplace import Memory

>>> memory = Memory.from_values(range(0))
>>> memory.to_blocks()
[]

~~~

0	1	2	3	4	5	6	7	8
		[A	B	C	D	E]

>>> memory = Memory.from_values(range(ord('A'), ord('F')), offset=2)
>>> memory.to_blocks()
[[2, b'ABCDE']]

classmethod fromhex(string)¶

Creates a virtual memory from an hexadecimal string.

Parameters: string (str) – Hexadecimal string.
Returns: ImmutableMemory – The resulting memory object.

Examples

>>> from cbytesparse.c import Memory

>>> memory = Memory.fromhex('')
>>> bytes(memory)
b''

~~~

>>> memory = Memory.fromhex('48656C6C6F2C20576F726C6421')
>>> bytes(memory)
b'Hello, World!'

gaps(start, endex)¶

get(address, default)¶

hex(*args)¶

Converts into an hexadecimal string.

Parameters

sep (str) – Separator string between bytes. Defaults to an emoty string if not provided. Available since Python 3.8.
bytes_per_sep (int) – Number of bytes grouped between separators. Defaults to one byte per group. Available since Python 3.8.

Returns

str – Hexadecimal string representation.

Raises

ValueError – Data not contiguous (see contiguous).

Examples

>>> from cbytesparse.c import Memory

>>> Memory().hex() == ''
True

~~~

>>> memory = Memory.from_bytes(b'Hello, World!')
>>> memory.hex()
48656c6c6f2c20576f726c6421
>>> memory.hex('.')
48.65.6c.6c.6f.2c.20.57.6f.72.6c.64.21
>>> memory.hex('.', 4)
48.656c6c6f.2c20576f.726c6421

index(item, start, endex)¶

insert(address, data)¶

insert_backup(address, data)¶

insert_restore(address, backup)¶

Restores an insert() operation.

Parameters

address (int) – Address of the insertion point.
backup (Memory) – Backup memory region to restore.

See also

insert() insert_backup()

intervals(start, endex)¶

items(start, endex, pattern)¶

keys(start, endex)¶

ofind(item, start, endex)¶

peek(address)¶

poke(address, item)¶

poke_backup(address)¶

poke_restore(address, item)¶

Restores a poke() operation.

Parameters

address (int) – Address of the target item.
item (int or byte) – Item to restore.

See also

poke() poke_backup()

pop(address, default)¶

pop_backup(address)¶

pop_restore(address, item)¶

Restores a pop() operation.

Parameters

address (int) – Address of the target item.
item (int or byte) – Item to restore, None if empty.

See also

pop() pop_backup()

popitem()¶

Pops the last item.

Returns: (int, int) – Address and value of the last item.

See also

popitem_backup() popitem_restore()

Examples

>>> from cbytesparse.c import Memory

0	1	2	3	4	5	6	7	8	9	10	11
	[A]								[y	z]

>>> memory = Memory.from_blocks([[1, b'A'], [9, b'yz']])
>>> memory.popitem()  # -> ord('z') = 122
(10, 122)
>>> memory.popitem()  # -> ord('y') = 121
(9, 121)
>>> memory.popitem()  # -> ord('A') = 65
(1, 65)
>>> memory.popitem()
Traceback (most recent call last):
    ...
KeyError: empty

popitem_backup()¶

Backups a popitem() operation.

Returns: (int, int) – Address and value of the last item.

See also

popitem() popitem_restore()

popitem_restore(address, item)¶

Restores a popitem() operation.

Parameters

address (int) – Address of the target item.
item (int) – Item to restore.

See also

popitem() popitem_backup()

remove(item, start, endex)¶

remove_backup(item, start, endex)¶

remove_restore(backup)¶

Restores a remove() operation.

Parameters: backup (Memory) – Backup memory region.

See also

remove() remove_backup()

reserve(address, size)¶

reserve_backup(address, size)¶

reserve_restore(address, backup)¶

Restores a reserve() operation.

Parameters

address (int) – Address of the reservation point.
backup (ImmutableMemory) – Backup memory region to restore.

See also

reserve() reserve_backup()

reverse()¶

Reverses the memory in-place.

Data is reversed within the memory span.

Examples

>>> from cbytesparse.c import Memory

0	1	2	3	4	5	6	7	8	9	10	11
	[A	B	C	D]		[$]		[x	y	z]
	[z	y	x]		[$]		[D	C	B	A]

>>> memory = Memory.from_blocks([[1, b'ABCD'], [6, b'$'], [8, b'xyz']])
>>> memory.reverse()
>>> memory.to_blocks()
[[1, b'zyx'], [5, b'$'], [7, b'DCBA']]

~~~

0	1	2	3	4	5	6	7	8	9	10	11
		[[[		[A	B	C]				)))
		[[[			[C	B	A]			)))

>>> memory = Memory.from_bytes(b'ABCD', 3, start=2, endex=10)
>>> memory.reverse()
>>> memory.to_blocks()
[[5, b'CBA']]

rfind(item, start, endex)¶

rindex(item, start, endex)¶

rofind(item, start, endex)¶

rvalues(start, endex, pattern)¶

setdefault(address, default)¶

setdefault_backup(address)¶

setdefault_restore(address, item)¶

Restores a setdefault() operation.

Parameters

address (int) – Address of the target item.
item (int or byte) – Item to restore, None if empty.

See also

setdefault() setdefault_backup()

shift(offset)¶

shift_backup(offset)¶

shift_restore(offset, backup)¶

Restores an shift() operation.

Parameters

offset (int) – Signed amount of address shifting.
backup (ImmutableMemory) – Backup memory region to restore.

See also

shift() shift_backup()

span¶

Memory address span.

A tuple holding both start and endex.

Examples

>>> from cbytesparse.c import Memory

>>> Memory().span
(0, 0)
>>> Memory(start=1, endex=8).span
(1, 8)

~~~

0	1	2	3	4	5	6	7	8
	[A	B	C]		[x	y	z]

>>> memory = Memory.from_blocks([[1, b'ABC'], [5, b'xyz']])
>>> memory.span
(1, 8)

Type: tuple of int

start¶

Inclusive start address.

This property holds the inclusive start address of the virtual space. By default, it is the current minimum inclusive start address of the first stored block.

If trim_start not None, that is returned.

If the memory has no data and no trimming, 0 is returned.

Examples

>>> from cbytesparse.c import Memory

>>> Memory().start
0

~~~

0	1	2	3	4	5	6	7	8
	[A	B	C]		[x	y	z]

>>> memory = Memory.from_blocks([[1, b'ABC'], [5, b'xyz']])
>>> memory.start
1

~~~

0	1	2	3	4	5	6	7	8
	[[[				[x	y	z]

>>> memory = Memory.from_blocks([[5, b'xyz']], start=1)
>>> memory.start
1

Type: int

to_blocks(start, endex)¶

Exports into blocks.

Exports data blocks within an address range, converting them into standalone bytes objects.

Parameters

start (int) – Inclusive start address. If None, start is considered.
endex (int) – Exclusive end address. If None, endex is considered.

Returns

list of blocks – Exported data blocks.

See also

blocks() from_blocks()

Examples

>>> from cbytesparse.c import Memory

0	1	2	3	4	5	6	7	8	9	10
	[A	B]			[x]		[1	2	3]

>>> memory = Memory.from_blocks([[1, b'AB'], [5, b'x'], [7, b'123']])
>>> memory.to_blocks()
[[1, b'AB'], [5, b'x'], [7, b'123']]
>>> memory.to_blocks(2, 9)
[[2, b'B'], [5, b'x'], [7, b'12']]
>>> memory.to_blocks(3, 5)]
[]

to_bytes(start, endex)¶

Exports into bytes.

Exports data within an address range, converting into a standalone bytes object.

Parameters

start (int) – Inclusive start address. If None, start is considered.
endex (int) – Exclusive end address. If None, endex is considered.

Returns

bytes – Exported data bytes.

See also

from_bytes() view()

Examples

>>> from cbytesparse.c import Memory

>>> memory = Memory.from_bytes(b'')
>>> memory.to_bytes()
b''

~~~

0	1	2	3	4	5	6	7	8
		[A	B	C	x	y	z]

>>> memory = Memory.from_bytes(b'ABCxyz', 2)
>>> memory.to_bytes()
b'ABCxyz'
>>> memory.to_bytes(start=4)
b'Cxyz'
>>> memory.to_bytes(endex=6)
b'ABCx'
>>> memory.to_bytes(4, 6)
b'Cx'

trim_endex¶

trim_span¶

trim_start¶

update(data, clear, **kwargs)¶

Updates data.

Parameters

data (iterable) – Data to update with. Can be either another memory, an (address, value) mapping, or an iterable of (address, value) pairs.
clear (bool) – Clears the target range before writing data. Useful only if data is a Memory with empty spaces.

See also

update_backup() update_restore()

Examples

>>> from cbytesparse.c import Memory

1	2	3	5	6	7
			[A	B	C]
[x	y]		[A	B	C]
[x	y	@]	[A	?	C]

>>> memory = Memory()
>>> memory.update(Memory.from_bytes(b'ABC', 5))
>>> memory.to_blocks()
[[5, b'ABC']]
>>> memory.update({1: b'x', 2: ord('y')})
>>> memory.to_blocks()
[[1, b'xy'], [5, b'ABC']]
>>> memory.update([(6, b'?'), (3, ord('@'))])
>>> memory.to_blocks()
[[1, b'xy@'], [5, b'A?C']]

update_backup(data, clear, **kwargs)¶

Backups an update() operation.

Parameters

data (iterable) – Data to update with. Can be either another memory, an (address, value) mapping, or an iterable of (address, value) pairs.
clear (bool) – Clears the target range before writing data. Useful only if data is a Memory with empty spaces.

Returns

list of ImmutableMemory – Backup memory regions.

See also

update() update_restore()

update_restore(backups)¶

Restores an update() operation.

Parameters: backups (list of ImmutableMemory) – Backup memory regions to restore.

See also

update() update_backup()

validate()¶

Validates internal structure.

It makes sure that all the allocated blocks are sorted by block start address, and that all the blocks are non-overlapping.

Raises: ValueError – Invalid data detected (see exception message).

values(start, endex, pattern)¶

view(start, endex)¶

write(address, data, clear)¶

write_backup(address, data, clear)¶

write_restore(backups)¶

Restores a write() operation.

Parameters: backups (list of ImmutableMemory) – Backup memory regions to restore.

See also

write() write_backup()