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

## Download Files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

File Name & Hash SHA256 Hash Help | Version | File Type | Upload Date |
---|---|---|---|

fixedint-0.1.3.tar.gz
(11.1 kB) Copy SHA256 Hash SHA256 |
– | Source | Jun 23, 2014 |