=====================================
fixedint: simple fixed-width integers

This module provides fixed-size integer classes which retain their fixed nature across
arithmetic operations. It is geared towards users who need to emulate machine integers.

It provides flexible classes for defining integers with a fixed number of bits, as well
as predefined classes for common machine integer sizes. These classes can be used as
drop-in replacements for int/long, and can be sliced to extract bitfields.

Mutable versions of these integers are provided, enabling usages such as emulation of
machine registers.

Basic Usage

A collection of predefined fixed-width integers for widths 8, 16, 32 and 64 are available
in signed and unsigned varieties. Mutable and immutable versions of each type are provided.

These are named as [Mutable][U]Int<N>, e.g. UInt64 or MutableInt8. Use these
classes as you would int; arithmetic operations involving these classes will preserve
fixed width. For example::

x = UInt32(0)
print(hex(~x)) # prints 0xffffffff

Mutable instances can be modified in-place, preserving their type::

x = MutableUInt32(0)
y = x
x += 100
print(y) # prints 100

To set a mutable integer without losing its type, use slicing::

x = MutableUInt32(0)
x[:] = -1
print(hex(x)) # prints 0xffffffff

Arithmetic Operations

FixedInt instances support all arithmetic operators. For binary operators, both
operands are converted to plain Python int and then operated on. With a few
exceptions, the result will be cast back to a FixedInt large enough to hold either
operand, provided one of the operands was a FixedInt. Note that the resulting
FixedInt may not be large enough to hold the complete result, in which case the
result will be truncated.

The exceptions are as follows:

divmod returns a tuple of plain int s
true division returns a float
**, << and >> will return a FixedInt if the left operand was a
FixedInt, and plain int otherwise.

Mutable instances additionally support in-place operations, which will modify the
value without altering its type.

Arithmetic operations between two integers of different sizes follow C integer promotion
rules when determining the type of the final result. These rules boil down to the
following:

If the operands are both signed, or both unsigned, the wider of the two operand types is chosen.
Otherwise, if the unsigned operand is wider, the unsigned operand is chosen.
Otherwise, the signed operand is chosen.

Slicing

FixedInt instances support slicing. Slicing with a single integer produces a single
Boolean value representing the bit at that position. Slicing with a range produces a
FixedInt containing the range of bits. Mutable instances additionally support slice
assignment. This makes e.g. manipulating a flag register straightforward, without needing
to use bitwise operations.

All indexing operations treat the least-significant bit (LSB) as bit 0. Currently, only
contiguous bit sections can be obtained; for more flexibility consider using a module
such as bitarray.

Getting a slice results in a FixedInt instance with exactly as many bits as the range.
This can be used to perform wraparound arithmetic on a bit field.

Slices support two main syntaxes::

value[<start>:<end>]
value[<start>:<length>j]

The latter syntax is more convenient when dealing with fixed-width fields. Either of the
slice arguments may be omitted, in which case they will default to the LSB and MSB of
the FixedInt respectively.

Byte Conversion

FixedInt instances can be converted to and from raw byte representations by using the
.to_bytes instance method and the .from_bytes classmethod. The usage of these
methods matches that of Python 3.4's int.to_bytes and int.from_bytes methods, but
the length is automatically inferred from the integer width.

Package profile

fixedint

Releases

Release table

PyPI Downloads

Dependencies

Details

Project URLs

Dependencies

Package description