Basic types

This module contains three “basic types” used in binflakes in addition to the usual ones:

• binflakes.types.BinInt – an arbitrary-precision integer type, with a few extra methods for bit-level manipulation
• binflakes.types.BinWord – represents fixed-width binary words
• binflakes.types.BinArray – represents fixed-width arrays of binary words

class binflakes.types.BinWord(width, val, *, trunc=False)

Bases: object

A class representing a binary word value. Its width (in bits) can be an arbitrary positive integer and is specified on creation.

Values of this class are immutable once created.

Most operations on BinWords treat them as two’s complement numbers, complete with wrapping semantics (and require their widths to match).

Can be treated as a sequence of individual bits (which are represented as BinWords of width 1), with bit 0 being the LSB and width-1 being the MSB.

Creates a word with a given width corresponding to a given unsigned integer value.

If trunc is True, values out of range are masked to fit. Otherwise, it is an error to pass a value that doesn’t fit in the given width.

__add__(other)

Performs a wrapping addition of two equal-sized BinWords.

__and__(other)

Performs a bitwise AND of two equal-sized BinWords.

__bool__()

Converts a BinWord to a bool. All words not equal to all-zeros are considered to be true.

__eq__(other)

Compares for equality with another object. BinWords are only considered equal to other BinWords with the same width and value.

__ge__(other)

Compares two equal-sized BinWords, treating them as unsigned integers, and returning True if the first is bigger or equal. Use sge to compare as signed integers instead.

__getitem__(idx)

Extracts a given bit or a range of bits, with python indexing semantics. Use extract to extract by position and width.

__gt__(other)

Compares two equal-sized BinWords, treating them as unsigned integers, and returning True if the first is bigger. Use sgt to compare as signed integers instead.

__index__()

Converts the word to an int, treating it as an unsigned number.

__init__(width, val, *, trunc=False)

Creates a word with a given width corresponding to a given unsigned integer value.

If trunc is True, values out of range are masked to fit. Otherwise, it is an error to pass a value that doesn’t fit in the given width.

__int__()

Converts the word to an int, treating it as an unsigned number.

__invert__()

Returns a one’s complement of the BinWord (ie. inverts all bits).

__le__(other)

Compares two equal-sized BinWords, treating them as unsigned integers, and returning True if the first is smaller or equal. Use sle to compare as signed integers instead.

__len__()

Returns the width of this word in bits.

__lshift__(count)

Performs a left-shift of a BinWord by the given number of bits. Bits shifted out of the word are lost.

The shift count can be an arbitrary non-negative number, including counts larger than the word (0 is returned in this case).

__lt__(other)

Compares two equal-sized BinWords, treating them as unsigned integers, and returning True if the first is smaller. Use slt to compare as signed integers instead.

__mul__(other)

Performs a wrapping multiplication of two equal-sized BinWords.

__neg__()

Returns a two’s complement of the BinWord.

__or__(other)

Performs a bitwise OR of two equal-sized BinWords.

__rshift__(count)

Performs a logical right-shift of a BinWord by the given number of bits. Bits shifted out of the word are lost. The word is filled on the left with 0 bits.

The shift count can be an arbitrary non-negative number, including counts larger than the word (0 is returned in this case).

__str__()

Returns a textual representation in the following format: <width as a decimal number>'0x<value as a hexadecimal number>. This format is directly accepted by the S-expression parser.

__sub__(other)

Performs a wrapping subtraction of two equal-sized BinWords.

__xor__(other)

Performs a bitwise XOR of two equal-sized BinWords.

classmethod concat(*args)

Returns a BinWord made from concatenating several BinWords, in LSB-first order.

deposit(pos, val)

Returns a copy of this BinWord, with a given word deposited at a given position (ie. with bits pos:pos+len(val) replaced bit bits from val).

extract(pos, width)

Extracts a subword with a given width, starting from a given bit position. It is an error to extract out-of-range bits.

mask

Returns a BinInt with low self.width bits set, corresponding to a bitmask of valid bits for words of this size.

sar(count)

Performs an arithmetic right-shift of a BinWord by the given number of bits. Bits shifted out of the word are lost. The word is filled on the left with copies of the top bit.

The shift count can be an arbitrary non-negative number, including counts larger than the word (a word filled with copies of the sign bit is returned in this case).

sext(width)

Sign-extends a word to a larger width. It is an error to specify a smaller width (use extract instead to crop off the extra bits).

sge(other)

Compares two equal-sized BinWords, treating them as signed integers, and returning True if the first is bigger or equal.

sgt(other)

Compares two equal-sized BinWords, treating them as signed integers, and returning True if the first is bigger.

sle(other)

Compares two equal-sized BinWords, treating them as signed integers, and returning True if the first is smaller or equal.

slt(other)

Compares two equal-sized BinWords, treating them as signed integers, and returning True if the first is smaller.

to_sint()

Converts the word to a BinInt, treating it as a signed number.

to_uint()

Converts the word to a BinInt, treating it as an unsigned number.

width

Returns the width of this word in bits.

zext(width)

Zero-extends a word to a larger width. It is an error to specify a smaller width (use extract instead to crop off the extra bits).

class binflakes.types.BinInt

Bases: int

A class representing an arbitrary-precision binary integer number.

This is just a python int with some extra methods.

Can be treated as an infinite sequence of individual bits (which are represented as BinWords of width 1), with bit 0 being the LSB. For non-negative numbers, all bits from a certain point are equal to 0. For negative numbers, all bits from a certain point are equal to 1 (following two’s complement convention).

__getitem__(idx)

Extracts a given bit or a range of bits, with python indexing semantics. Use extract to extract by position and width.

Since BinInt is, conceptually, an infinite sequence of bits, it is an error to use negative indices. However, it is fine to omit the stop index, returning an infinite subsequence of bits – a BigInt is returned in this case. For finite sequences, a BinWord is returned.

ceildiv(other)

Returns ceil(a / b).

deposit(pos, val)

Returns a copy of this BinInt, with a given word deposited at a given position (ie. with bits pos:pos+len(val) replaced with bits from val).

extract(pos, width)

Extracts a subword with a given width, starting from a given bit position.

classmethod mask(width)

Creates a new BinInt with low width bits set.

class binflakes.types.BinArray(data=None, *, width=None, length=None)

Bases: object

Represents an array of equal-width BinWords. Conceptually behaves like bytearray, except that element width can be different than 8, and item accesses return BinWord instances.

Creates a new BinArray. The following forms are valid:

• BinArray(bytes or bytearray): creates a BinArray of width 8 with items from the given bytearray.
• BinArray(BinArray instance): creates a copy of a BinArray.
• BinArray(width=w): creates empty BinArray of given width.
• BinArray(width=w, length=n): creates a zero-filled BinArray of given width and length.
• BinArray(iterable, width=n): creates a BinArray from the given iterable of items. Items should be ints, BinInts, or BinWords of the correct width.
• BinArray(iterable): creates a BinArray from a non-empty array of BinWords.

__add__(other)

Concatenates two equal-width BinArray instances together, returning a new BinArray.

__and__(other)

Creates a new BinArray from two equal-width, equal-length BinArrays by applying the bitwise AND operation to every pair of corresponding words.

__eq__(other)

Compares for equality with another object. BinArrays are only considered equal to other BinArrays with the same width, length, and contents.

__getitem__(idx)

Returns a word at the given index (as a BinWord instance), or a slice of the array (as a new BinArray instance).

__init__(data=None, *, width=None, length=None)

Creates a new BinArray. The following forms are valid:

• BinArray(bytes or bytearray): creates a BinArray of width 8 with items from the given bytearray.
• BinArray(BinArray instance): creates a copy of a BinArray.
• BinArray(width=w): creates empty BinArray of given width.
• BinArray(width=w, length=n): creates a zero-filled BinArray of given width and length.
• BinArray(iterable, width=n): creates a BinArray from the given iterable of items. Items should be ints, BinInts, or BinWords of the correct width.
• BinArray(iterable): creates a BinArray from a non-empty array of BinWords.

__invert__()

Creates a new BinArray with all bits inverted.

__len__()

Returns length of the array in words.

__mul__(count)

Repeats a BinArray count times, returning a new BinArray.

__or__(other)

Creates a new BinArray from two equal-width, equal-length BinArrays by applying the bitwise OR operation to every pair of corresponding words.

__rmul__(count)

Repeats a BinArray count times, returning a new BinArray.

__setitem__(idx, val)

Assigns to the word at a given index, or to a subslice of the array. When assigning words, the assigned value must be a BinWord instance of the same width as the array, or an int or BinInt instance that will be automatically converted to BinWord. It is an error if an int or BinInt is assigned that does not fit in width bits.

__str__()

Returns a textual representation in the following format: <width as a decimal number>'0x(<space-separated words as hexadecimal numbers>). This format is directly accepted by the S-expression parser.

__xor__(other)

Creates a new BinArray from two equal-width, equal-length BinArrays by applying the bitwise XOR operation to every pair of corresponding words.

repack(to_width, *, msb_first, start=0, start_bit=0, length=None)

Extracts a part of a BinArray’s data and converts it to a BinArray of a different width.

For the purposes of this conversion, words in this BinArray are joined side-by-side, starting from a given start index (defaulting to 0), skipping start_bit first bits of the first word, then the resulting stream is split into to_width-sized words and length first such words are returned as a new BinArray.

If msb_first is False, everything proceeds with little endian ordering: the first word provides the least significant bits of the combined stream, start_bit skips bits starting from the LSB, and the first output word is made from the lowest bits of the combined stream. Otherwise (msb_first is True), everything proceeds with big endian ordering: the first word provides the most significant bits of the combined stream, start_bit skips bits starting from the MSB, and the first output word is made from the highest bits of the combined stream.

start_bits must be smaller than the width of the input word. It is an error to request a larger length than can be provided from the input array. If length is not provided, this function returns as many words as can be extracted.

For example, consider a 10-to-3 repack with start_bit=2, length=4 msb_first=True:

	MSB … LSB
	…
start	X	X	a	b	c	d	e	f	g	h
start+1	i	j	k	l	X	X	X	X	X	X
	…

is repacked to:

0	a	b	c
1	d	e	f
2	g	h	i
3	j	k	l

The same repack for msb_first=False is performed as follows:

	MSB … LSB
	…
start	h	g	f	e	d	c	b	a	X	X
start+1	X	X	X	X	X	X	l	k	j	i
	…

into:

0	c	b	a
1	f	e	d
2	i	h	g
3	l	k	j

repack_data_available(src_width, to_width, *, src_length=None, start=None, start_bit=0)

Calculates the maximum number of words that can be requested from a repack invocation with the given settings.

This function can be called either on a BinArray instance (assuming its width as the source width), or on the BinArray class (passing the source width as an extra first argument). If called in the second form, src_length must be provided. Otherwise, it will default to the number of words in the source array from the given start index (defaulting to 0) until the end.

repack_source_required(src_width, to_width, length, *, start_bit=0)

Calculates how many source words would be read for an invocation of repack with a given length, including possible partial words at the beginning and the end of the repack source. This can be called either on a concrete BinArray instance (assuming its width as the source width), or on the BinArray class (providing the source width as an extra first argument). This function doesn’t take start or msb_first parameters, since they wouldn’t affect the computation.

width

Returns word width of the BinArray.