Bitstruct
Bitstruct
Release 8.17.0
Erik Moqvist
1 About 1
2 Installation 3
3 Performance 5
4 MicroPython 7
5 Example usage 9
6 Contributing 13
7 Functions 15
8 Classes 19
Index 21
i
ii
CHAPTER 1
About
This module is intended to have a similar interface as the python struct module, but working on bits instead of primitive
data types (char, int, . . . ).
Project homepage: https://github.com/eerimoq/bitstruct
Documentation: https://bitstruct.readthedocs.io
1
bitstruct Documentation, Release 8.17.0
2 Chapter 1. About
CHAPTER 2
Installation
3
bitstruct Documentation, Release 8.17.0
4 Chapter 2. Installation
CHAPTER 3
Performance
Parts of this package has been re-implemented in C for faster pack and unpack operations. There are two independent
C implementations; bitstruct.c, which is part of this package, and the standalone package cbitstruct. These implemen-
tations are only available in CPython 3, and must be explicitly imported. By default the pure Python implementation
is used.
To use bitstruct.c, do import bitstruct.c as bitstruct.
To use cbitstruct, do import cbitstruct as bitstruct.
bitstruct.c has a few limitations compared to the pure Python implementation:
• Integers and booleans must be 64 bits or less.
• Text and raw must be a multiple of 8 bits.
• Bit endianness and byte order are not yet supported.
• byteswap() can only swap 1, 2, 4 and 8 bytes.
See cbitstruct for its limitations.
5
bitstruct Documentation, Release 8.17.0
6 Chapter 3. Performance
CHAPTER 4
MicroPython
The C implementation has been ported to MicroPython. See bitstruct-micropython for more details.
7
bitstruct Documentation, Release 8.17.0
8 Chapter 4. MicroPython
CHAPTER 5
Example usage
A basic example of packing and unpacking four integers using the format string 'u1u3u4s16':
An example compiling the format string once, and use it to pack and unpack data:
Use the pack into and unpack from functions to pack/unpack values at a bit offset into the data, in this example the bit
offset is 5:
The unpacked values can be named by assigning them to variables or by wrapping the result in a named tuple:
9
bitstruct Documentation, Release 8.17.0
An example of packing and unpacking an unsigned integer, a signed integer, a float, a boolean, a byte string and a
string:
>>> from bitstruct import *
>>> pack('u5s5f32b1r13t40', 1, -1, 3.75, True, b'\xff\xff', 'hello')
b'\x0f\xd0\x1c\x00\x00?\xffhello'
>>> unpack('u5s5f32b1r13t40', b'\x0f\xd0\x1c\x00\x00?\xffhello')
(1, -1, 3.75, True, b'\xff\xf8', 'hello')
>>> calcsize('u5s5f32b1r13t40')
96
The same format string and values as in the previous example, but using LSB (Least Significant Bit) first instead of
the default MSB (Most Significant Bit) first:
>>> from bitstruct import *
>>> pack('<u5s5f32b1r13t40', 1, -1, 3.75, True, b'\xff\xff', 'hello')
b'\x87\xc0\x00\x03\x80\xbf\xff\xf666\xa6\x16'
>>> unpack('<u5s5f32b1r13t40', b'\x87\xc0\x00\x03\x80\xbf\xff\xf666\xa6\x16')
(1, -1, 3.75, True, b'\xff\xf8', 'hello')
>>> calcsize('<u5s5f32b1r13t40')
96
Change endianness of the data with byteswap, and then unpack the values:
>>> from bitstruct import *
>>> packed = pack('u1u3u4s16', 1, 2, 3, 1)
>>> unpack('u1u3u4s16', byteswap('12', packed))
(1, 2, 3, 256)
A basic example of packing and unpacking four integers using the format string 'u1u3u4s16' using the C imple-
mentation:
11
bitstruct Documentation, Release 8.17.0
Contributing
make test
13
bitstruct Documentation, Release 8.17.0
14 Chapter 6. Contributing
CHAPTER 7
Functions
bitstruct.pack(fmt, *args)
Return a bytes object containing the values v1, v2, . . . packed according to given format string fmt. If the total
number of bits are not a multiple of 8, padding will be added at the end of the last byte.
fmt is a string of bit order-type-length groups, and optionally a byte order identifier after the groups. Bit Order
and byte order may be omitted.
Bit Order is either > or <, where > means MSB first and < means LSB first. If bit order is omitted, the previous
values’ bit order is used for the current value. For example, in the format string 'u1<u2u3', u1 is MSB first
and both u2 and u3 are LSB first.
Byte Order is either > or <, where > means most significant byte first and < means least significant byte first. If
byte order is omitted, most significant byte first is used.
There are eight types; u, s, f, b, t, r, p and P.
• u – unsigned integer
• s – signed integer
• f – floating point number of 16, 32, or 64 bits
• b – boolean
• t – text (ascii or utf-8)
• r – raw, bytes
• p – padding with zeros, ignore
• P – padding with ones, ignore
Length is the number of bits to pack the value into.
Example format string with default bit and byte ordering: 'u1u3p7s16'
Same format string, but with least significant byte first: 'u1u3p7s16<'
Same format string, but with LSB first (< prefix) and least significant byte first (< suffix): '<u1u3p7s16<'
It is allowed to separate groups with a single space for better readability.
15
bitstruct Documentation, Release 8.17.0
>>> calcsize('u1s3p4')
8
16 Chapter 7. Functions
bitstruct Documentation, Release 8.17.0
17
bitstruct Documentation, Release 8.17.0
18 Chapter 7. Functions
CHAPTER 8
Classes
19
bitstruct Documentation, Release 8.17.0
20 Chapter 8. Classes
Index
B
byteswap() (in module bitstruct), 16
C
calcsize() (in module bitstruct), 16
compile() (in module bitstruct), 16
CompiledFormat (class in bitstruct), 19
CompiledFormatDict (class in bitstruct), 19
P
pack() (bitstruct.CompiledFormat method), 19
pack() (bitstruct.CompiledFormatDict method), 19
pack() (in module bitstruct), 15
pack_dict() (in module bitstruct), 16
pack_into() (bitstruct.CompiledFormat method), 19
pack_into() (bitstruct.CompiledFormatDict method),
19
pack_into() (in module bitstruct), 16
pack_into_dict() (in module bitstruct), 16
U
unpack() (bitstruct.CompiledFormat method), 19
unpack() (bitstruct.CompiledFormatDict method), 19
unpack() (in module bitstruct), 16
unpack_dict() (in module bitstruct), 16
unpack_from() (bitstruct.CompiledFormat method),
19
unpack_from() (bitstruct.CompiledFormatDict
method), 19
unpack_from() (in module bitstruct), 16
unpack_from_dict() (in module bitstruct), 16
21