[plum.int] Tutorial: Using Integer Types

The plum.int subpackage provides plum type classes for packing and unpacking integer numbers. This tutorial teaches how to use the standard integer plum types offered as well as how to create custom integer types.

Common Integer Types

The plum.int subpackage includes three modules, one for each endian byte order: plum.int.big, plum.int.little, and plum.int.native (native byte order follows host architecture). Each module provides plum type classes for both signed and unsigned integers for each of the sizes:

Plum Type Sign Bits Bytes
SInt8 signed 8 1
SInt16 signed 16 2
SInt32 signed 32 4
SInt64 signed 64 8
UInt8 unsigned 8 1
UInt16 unsigned 16 2
UInt32 unsigned 32 4
UInt64 unsigned 64 8

Unpacking Bytes

The plum integer types convert bytes into Python int instances when used with the various plum unpacking mechanisms. For example:

>>> from plum import unpack, Buffer
>>> from plum.int.big import UInt8, UInt16
>>>
>>> # utility function
>>> unpack((UInt16, UInt8), b'\x00\x01\x02')
(1, 2)
>>>
>>> # class method
>>> UInt16.unpack(b'\x00\x01')
1
>>> # bytes buffer
>>> with Buffer(b'\x00\x01\x02') as buffer:
...     a = buffer.unpack(UInt16)
...     b = buffer.unpack(UInt8)
...
>>> a, b
(1, 2)

Packing Bytes

The plum integer types convert integers (or anything int-like) into bytes when used with the various plum packing mechanisms. For example:

>>> from plum import pack
>>> from plum.int.big import UInt8, UInt16
>>>
>>> # utility function
>>> fmt = (UInt16, UInt8)
>>> pack(fmt, 1, 2)
bytearray(b'\x00\x01\x02')
>>>
>>> # class method
>>> UInt16.pack(1) + UInt8.pack(2)
bytearray(b'\x00\x01\x02')
>>>
>>> # instance method
>>> UInt16(1).pack() + UInt8(2).pack()
bytearray(b'\x00\x01\x02')

Instantiation and Instance Properties

plum integer type constructors accept integers (or anything int() accepts) so long as it is within the range the type supports. The representation of the instance includes the class name to differentiate it from standard Python int instances:

>>> from plum.int.big import UInt8
>>>
>>> repr(UInt8(0))
'UInt8(0)'
>>>
>>> UInt8(256)
Traceback (most recent call last):
    ...
ValueError: UInt8 requires 0 <= number <= 255

Instances support the pack() method:

>>> x = UInt8(0)
>>> x.pack()
bytearray(b'\x00')

Since plum integer types are a subclass of the standard Python int, they support the same behaviors and methods. For example:

>>> x = UInt8(1)
>>>
>>> # compare
>>> x == 1
True
>>> # arithmetic
>>> x + 1
2
>>> # logical
>>> x << 4
16

Custom Integer Types

The plum.int subpackage offers the Int class for creating integer plum types for applications requiring packing and unpacking unusually sized integers. The following example uses the nbytes argument to create a 24 bit integer:

>>> from plum.int import Int
>>> class UInt24(Int, nbytes=3, signed=False, byteorder='big'):
...     """Unsigned 24 bit big endian integer."""
...
>>> UInt24.unpack(b'\x00\x01\x02')
258
>>> UInt24.pack(258)
bytearray(b'\x00\x01\x02')