Skip to main content

simple fixed-width integers

Project description

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



Build Status
============

.. image:: https://travis-ci.org/nneonneo/fixedint.svg?branch=master
:target: https://travis-ci.org/nneonneo/fixedint

Project details


Download files

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

Files for fixedint, version 0.1.0
Filename, size File type Python version Upload date Hashes
Filename, size fixedint-0.1.0.macosx-10.6-intel.exe (76.8 kB) File type Windows Installer Python version any Upload date Hashes View
Filename, size fixedint-0.1.0.tar.gz (11.0 kB) File type Source Python version None Upload date Hashes View

Supported by

Pingdom Pingdom Monitoring Google Google Object Storage and Download Analytics Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN DigiCert DigiCert EV certificate StatusPage StatusPage Status page