Skip to main content

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


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.2.0.tar.gz (14.9 kB view details)

Uploaded Source

Built Distributions

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

Uploaded Python 3

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

Uploaded Python 2

File details

Details for the file fixedint-0.2.0.tar.gz.

File metadata

  • Download URL: fixedint-0.2.0.tar.gz
  • Upload date:
  • Size: 14.9 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/4.0.1 CPython/3.10.5

File hashes

Hashes for fixedint-0.2.0.tar.gz
Algorithm Hash digest
SHA256 aeea0c7a3a54e5371ed632f9a97719316699f64f863ffce4414ef0f925255d17
MD5 a1062f01ce021d3bee52920e550ff63c
BLAKE2b-256 099163a0b3a26731c278e09f9e9931a3ea06c91d987803ef689d02a8d377b1f7

See more details on using hashes here.

File details

Details for the file fixedint-0.2.0-py3-none-any.whl.

File metadata

  • Download URL: fixedint-0.2.0-py3-none-any.whl
  • Upload date:
  • Size: 14.7 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/4.0.1 CPython/3.10.5

File hashes

Hashes for fixedint-0.2.0-py3-none-any.whl
Algorithm Hash digest
SHA256 0fadb639d735a45216ffc3a281a5208ec990c3179daabb8ca4128cf8db84db39
MD5 553025265ac269c5a5ef0d224061c90e
BLAKE2b-256 b6a5d29376ba14b70859f6dbba1573afb9ea20dcdbf792caedf8771553c50eb9

See more details on using hashes here.

File details

Details for the file fixedint-0.2.0-py2-none-any.whl.

File metadata

  • Download URL: fixedint-0.2.0-py2-none-any.whl
  • Upload date:
  • Size: 14.6 kB
  • Tags: Python 2
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/4.0.1 CPython/3.10.5

File hashes

Hashes for fixedint-0.2.0-py2-none-any.whl
Algorithm Hash digest
SHA256 576da1ec15c3787add10c68a5d87a33d8f723d7fd9ad9bfec1a69c1951414655
MD5 33ee72176937f7f2957a8e4d946fa90e
BLAKE2b-256 63db1bf2fd918b02754b497be873b55a018103d2843743eaa63fa1776498756c

See more details on using hashes here.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page