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
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.
Source Distribution
fixedint-0.1.0.tar.gz
(11.0 kB
view hashes)
Built Distribution
Close
Hashes for fixedint-0.1.0.macosx-10.6-intel.exe
Algorithm | Hash digest | |
---|---|---|
SHA256 | b6de2c8a454510f53b76f510dbe7e46aadf36b9dfe640c37bcea3271f58c9a1f |
|
MD5 | 886be94ff37cdf9481c8babb65ea5793 |
|
BLAKE2b-256 | 2cfa24681ce6eca356ab45e1aace5ef7197f0c7b2d9816c0493f68ba7b6cac3f |