simple fixed-width integers

## Project description

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.

## Project details

### Source Distribution

fixedint-0.2.0.tar.gz (14.9 kB view hashes)

Uploaded source

### Built Distributions

fixedint-0.2.0-py3-none-any.whl (14.7 kB view hashes)

Uploaded py3

fixedint-0.2.0-py2-none-any.whl (14.6 kB view hashes)

Uploaded py2