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

boolself 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.

_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.

_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.

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.

append_restore()

Restores an append() operation.

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.

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.

cut(start, endex, bound)
delete(start, endex)
delete_backup(start, endex)
delete_restore(backup)

Restores a delete() operation.

Parameters

backup (ImmutableMemory) – Backup memory region

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.

extend_backup(offset)

Backups an extend() operation.

Parameters

offset (int) – Optional offset w.r.t. content_endex.

Returns

int – Content exclusive end address.

extend_restore(content_endex)

Restores an extend() operation.

Parameters

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

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.

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.

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.

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.

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.

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.

popitem_restore(address, item)

Restores a popitem() operation.

Parameters
  • address (int) – Address of the target item.

  • item (int) – Item to restore.

remove(item, start, endex)
remove_backup(item, start, endex)
remove_restore(backup)

Restores a remove() operation.

Parameters

backup (Memory) – Backup memory region.

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.

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.

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.

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.

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.

Examples

>>> from cbytesparse.c import Memory

0

1

2

3

4

5

6

7

8

9

10

11

[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.

update_restore(backups)

Restores an update() operation.

Parameters

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

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.