7.2.4 The intbv class

7.2.4 The `intbv` class

class intbv( [val=None][, min=None][, max=None]): This class represents int-like objects with some additional features that make it suitable for hardware design. The val argument can be an int, a long, an intbv or a bit string (a string with only '0's or '1's). For a bit string argument, the value is calculated as in int(bitstring, 2). The optional min and max arguments can be used to specify the minimum and maximum value of the intbv object. As in standard Python practice for ranges, the minimum value is inclusive and the maximum value is exclusive.

The minimum and maximum values of an intbv object are available as attributes:

min: Read-only attribute that is the minimum value (inclusive) of an intbv, or None for no minimum.

max: Read-only attribute that is the maximum value (exclusive) of an intbv, or None for no maximum.

Unlike int objects, intbv objects are mutable; this is also the reason for their existence. Mutability is needed to support assignment to indexes and slices, as is common in hardware design. For the same reason, intbv is not a subclass from int, even though int provides most of the desired functionality. (It is not possible to derive a mutable subtype from an immutable base type.)

An intbv object supports the same comparison, numeric, bitwise, logical, and conversion operations as int objects. See http://www.python.org/doc/current/lib/typesnumeric.html for more information on such operations. In all binary operations, intbv objects can work together with int objects. For mixed-type numeric operations, the result type is an int or a long. For mixed-type bitwise operations, the result type is an intbv.

In addition, intbv objects support indexing and slicing operations:

Operation Result Notes

bv[i] item i of bv (1)
bv[i] = x item i of bv is replaced by x (1)
bv[i:j] slice of bv from i downto j (2)(3)
bv[i:j] = t slice of bv from i downto j is replaced by t (2)(4)

Operation	Result	Notes
`bv[i]`	item `i` of `bv`	(1)
`bv[i] = x`	item `i` of `bv` is replaced by `x`	(1)
`bv[i:j]`	slice of `bv` from `i` downto `j`	(2)(3)
`bv[i:j] = t`	slice of `bv` from `i` downto `j` is replaced by `t`	(2)(4)

(1): Indexing follows the most common hardware design conventions: the lsb bit is the rightmost bit, and it has index 0. This has the following desirable property: if the intbv value is decomposed as a sum of powers of 2, the bit with index i corresponds to the term 2**i.
(2): In contrast to standard Python sequencing conventions, slicing range are downward. This is a consequence of the indexing convention, combined with the common convention that the most significant digits of a number are the leftmost ones. The Python convention of half-open ranges is followed: the bit with the highest index is not included. However, it is the leftmost bit in this case. As in standard Python, this takes care of one-off issues in many practical cases: in particular, bv[i:] returns i bits; bv[i:j] has i-j bits. When the low index j is omitted, it defaults to 0. When the high index i is omitted, it means ``all'' higher order bits.
(3): The object returned from a slicing access operation is always a positive intbv; higher order bits are implicitly assumed to be zero. The bit width is implicitly stored in the return object, so that it can be used in concatenations and as an iterator. In addition, for a bit width w, the min and max attributes are implicitly set to 0 and 2**w, respectively.
(4): When setting a slice to a value, it is checked whether the slice is wide enough.

In addition, an intbv object supports the iterator protocol. This makes it possible to iterate over all its bits, from the high index to index 0. This is only possible for intbv objects with a defined bit width.

About this document