A Python module to help you manage your bits

A Python module to help you manage your bits

by Scott Griffiths

version 3.1.7 July 20, 2021

python-logo.png scott-griffiths/bitstring

Contents

I User Manual

1

1 Walkthrough

3

1.1 A Brief Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3

1.1.1 Prerequisites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3

1.1.2 Getting started . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3

1.1.3 Modifying bitstrings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

1.1.4 Finding and Replacing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

1.1.5 Constructing a bitstring . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6

1.1.6 Parsing bitstreams . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

1.2 Worked examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

1.2.1 Hamming distance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8

1.2.2 Sieve of Eratosthenes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8

2 Introduction

9

2.1 Getting Started . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10

3 Creation

11

3.1 The bitstring classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

3.2 Using the constructor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12

3.2.1 From a hexadecimal string . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12

3.2.2 From a binary string . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12

3.2.3 From an octal string . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

3.2.4 From an integer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

3.2.5 Big and little-endian integers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

3.2.6 From a floating point number . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14

3.2.7 Exponential-Golomb codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14

3.2.8 From raw byte data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14

3.2.9 From a file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

3.3 The auto initialiser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

4 Packing

17

4.1 Compact format strings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19

5 Interpreting Bitstrings

21

5.1 bin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21

5.2 hex . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21

5.3 oct . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22

5.4 uint / uintbe / uintle / uintne . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22

5.5 int / intbe / intle / intne . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22

5.6 float / floatbe / floatle / floatne . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23

5.7 bytes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23

i

5.8 ue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23 5.9 se . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23 5.10 uie / sie . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24

6 Slicing, Dicing and Splicing

25

6.1 Slicing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25

6.1.1 Stepping in slices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26

6.2 Joining . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26

6.3 Truncating, inserting, deleting and overwriting . . . . . . . . . . . . . . . . . . . . . . . . . . . 27

6.3.1 Deleting and truncating . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27

6.3.2 insert . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27

6.3.3 overwrite . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27

6.4 The bitstring as a list . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27

6.5 Splitting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28

6.5.1 split . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28

6.5.2 cut . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28

7 Reading, Parsing and Unpacking

29

7.1 Reading and parsing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29

7.1.1 read / readlist . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29

7.1.2 Reading using format strings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30

7.1.3 Peeking . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31

7.2 Unpacking . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31

7.3 Seeking . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31

7.4 Finding and replacing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32

7.4.1 find / rfind . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32

7.4.2 findall . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32

7.4.3 replace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32

7.5 Working with byte aligned data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33

8 Miscellany

35

8.1 Other Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35

8.1.1 bytealign . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35

8.1.2 reverse . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35

8.1.3 tobytes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35

8.1.4 tofile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36

8.1.5 startswith / endswith . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36

8.1.6 ror / rol . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36

8.2 Special Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36

8.2.1 __len__ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36

8.2.2 __str__ / __repr__ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37

8.2.3 __eq__ / __ne__ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37

8.2.4 __invert__ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37

8.2.5 __lshift__ / __rshift__ / __ilshift__ / __irshift__ . . . . . . . 37

8.2.6 __mul__ / __imul__ / __rmul__ . . . . . . . . . . . . . . . . . . . . . . . . 38

8.2.7 __copy__ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38

8.2.8 __and__ / __or__ / __xor__ / __iand__ / __ior__ / __ixor__ . 38

II Reference

39

9 Quick Reference

41

9.1 Bits . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41

9.1.1 Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41

9.1.2 Special methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42

9.1.3 Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42

9.2 BitArray . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42

9.2.1 Additional methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42

9.2.2 Additional special methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43

ii

9.2.3 Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43 9.3 ConstBitStream . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43

9.3.1 Additional methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43 9.3.2 Additional attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43 9.4 BitStream . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43

10 The bitstring module

45

10.1 The auto initialiser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45

10.2 Compact format strings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46

10.3 Class properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46

11 The Bits class

47

12 The BitArray class

57

13 The ConstBitStream class

63

14 The BitStream class

67

15 Functions

69

16 Exceptions

71

III Appendices

73

17 Examples

77

17.1 Creation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77

17.2 Manipulation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77

17.3 Parsing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78

18 Exponential-Golomb Codes

79

18.1 Interleaved exponential-Golomb codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80

19 Optimisation Techniques

81

19.1 Use combined read and interpretation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81

19.2 Choose the simplest class you can . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81

19.3 Use dedicated functions for bit setting and checking . . . . . . . . . . . . . . . . . . . . . . . . 82

20 Release Notes

83

20.1 Full Version History . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83

20.1.1 May 5th 2020: version 3.1.7 released . . . . . . . . . . . . . . . . . . . . . . . . . . . 83

20.1.2 Experimental LSB0 mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83

20.1.3 July 9th 2019: version 3.1.6 released . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84

20.1.4 May 17th 2016: version 3.1.5 released . . . . . . . . . . . . . . . . . . . . . . . . . . . 84

20.1.5 March 19th 2016: version 3.1.4 released . . . . . . . . . . . . . . . . . . . . . . . . . . 84

20.1.6 March 4th 2014: version 3.1.3 released . . . . . . . . . . . . . . . . . . . . . . . . . . 84

20.1.7 April 18th 2013: version 3.1.2 released . . . . . . . . . . . . . . . . . . . . . . . . . . 84

20.1.8 March 21st 2013: version 3.1.1 released . . . . . . . . . . . . . . . . . . . . . . . . . . 84

20.1.9 February 26th 2013: version 3.1.0 released . . . . . . . . . . . . . . . . . . . . . . . . 84

20.1.10 November 21st 2011: version 3.0.0 released . . . . . . . . . . . . . . . . . . . . . . . . 85

20.1.11 Backwardly incompatible changes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85

20.1.12 New features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86

20.1.13 June 18th 2011: version 2.2.0 released . . . . . . . . . . . . . . . . . . . . . . . . . . . 86

20.1.14 February 23rd 2011: version 2.1.1 released . . . . . . . . . . . . . . . . . . . . . . . . 87

20.1.15 January 23rd 2011: version 2.1.0 released . . . . . . . . . . . . . . . . . . . . . . . . . 87

20.1.16 New class hierarchy introduced with simpler classes . . . . . . . . . . . . . . . . . . . 87

20.1.17 July 26th 2010: version 2.0.3 released . . . . . . . . . . . . . . . . . . . . . . . . . . . 88

20.1.18 July 25th 2010: version 2.0.2 released . . . . . . . . . . . . . . . . . . . . . . . . . . . 88

20.1.19 The backwardly incompatible changes are: . . . . . . . . . . . . . . . . . . . . . . . . 88

iii

 ................
................

In order to avoid copyright disputes, this page is only a partial summary.

Google Online Preview   Download