bitarray-hardbyte 2.3.8

主要功能

• 可以为每个bitarray对象指定位序，如下所示。

• 序列方法：切片（包括切片赋值和删除）、操作+、*、+=、*=、in运算符、len()

• 快速编码和解码可变位长前缀码的方法。

• 位运算：~、&、|、^、<<、>>（以及它们的就地版本&=、|=、^=、<<=、>>=）。

• 打包和解包到其他二进制数据格式，例如numpy.ndarray。

• 位数组对象支持缓冲区协议（既支持导入也支持导出缓冲区）。

• 可哈希的frozenbitarray对象

• 位数组对象的序列化和反序列化。

• 顺序搜索

• 超过400个单元测试的全面测试套件。

• 实用模块bitarray.util

  • 转换为十六进制字符串

  • 序列化

  • 美化打印

  • 转换为整数

  • 创建霍夫曼码

  • 各种计数函数

  • 其他有帮助的函数

安装

如果您有一个可用的C编译器，您可以直接

$ pip install bitarray

如果您希望使用预编译的二进制文件，您可以选择

• 使用conda安装bitarray（默认的Anaconda仓库以及conda-forge都支持bitarray）

• 从Chris Gohlke下载Windows wheels

一旦安装了包，您可能想测试它

$ python -c 'import bitarray; bitarray.test()'
bitarray is installed in: /Users/ilan/bitarray/bitarray
bitarray version: 2.3.7
sys.version: 2.7.15 (default, Mar  5 2020, 14:58:04) [GCC Clang 9.0.1]
sys.prefix: /Users/ilan/Mini3/envs/py27
pointer size: 64 bit
sizeof(size_t): 8
sizeof(bitarrayobject): 80
PY_UINT64_T defined: 1
USE_WORD_SHIFT: 1
DEBUG: 0
.........................................................................
.........................................................................
................................................................
----------------------------------------------------------------------
Ran 409 tests in 0.484s

OK

您始终可以导入函数test，当测试成功时，test().wasSuccessful()将返回True。

使用模块

如上所述，位数组对象的行为非常类似于列表，因此没有太多需要学习的地方。与列表对象最大的不同（除了位数组显然是同质的之外）是能够访问对象机器表示。在这样做的时候，位字节序非常重要；这个问题在下面的部分中详细解释。在这里，我们展示了位数组对象的基本用法

>>> from bitarray import bitarray
>>> a = bitarray()         # create empty bitarray
>>> a.append(1)
>>> a.extend([1, 0])
>>> a
bitarray('110')
>>> x = bitarray(2 ** 20)  # bitarray of length 1048576 (uninitialized)
>>> len(x)
1048576
>>> bitarray('1001 011')   # initialize from string (whitespace is ignored)
bitarray('1001011')
>>> lst = [1, 0, False, True, True]
>>> a = bitarray(lst)      # initialize from iterable
>>> a
bitarray('10011')
>>> a.count(1)
3
>>> a.remove(0)            # removes first occurrence of 0
>>> a
bitarray('1011')

与列表一样，位数组对象支持切片赋值和删除

>>> a = bitarray(50)
>>> a.setall(0)            # set all elements in a to 0
>>> a[11:37:3] = 9 * bitarray('1')
>>> a
bitarray('00000000000100100100100100100100100100000000000000')
>>> del a[12::3]
>>> a
bitarray('0000000000010101010101010101000000000')
>>> a[-6:] = bitarray('10011')
>>> a
bitarray('000000000001010101010101010100010011')
>>> a += bitarray('000111')
>>> a[9:]
bitarray('001010101010101010100010011000111')

此外，切片可以赋值给布尔值，这比将值赋给所有值都相同的位数组要简单（且更快）

>>> a = 20 * bitarray('0')
>>> a[1:15:3] = True
>>> a
bitarray('01001001001001000000')

这比

>>> a = 20 * bitarray('0')
>>> a[1:15:3] = 5 * bitarray('1')
>>> a
bitarray('01001001001001000000')

注意在后者中，我们必须创建一个长度必须已知或计算的临时位数组。将切片赋给布尔值的另一个例子是设置范围

>>> a = bitarray(30)
>>> a[:] = 0         # set all elements to 0 - equivalent to a.setall(0)
>>> a[10:25] = 1     # set elements in range(10, 25) to 1
>>> a
bitarray('000000000011111111111111100000')

位运算符

位数组对象支持位运算符 ~、&、|、^、<<、>>（以及它们的就地版本 &=、|=、^=、<<=、>>=）。行为与预期非常相似

>>> a = bitarray('101110001')
>>> ~a  # invert
bitarray('010001110')
>>> b = bitarray('111001011')
>>> a ^ b
bitarray('010111010')
>>> a &= b
>>> a
bitarray('101000001')
>>> a <<= 2   # in-place left shift by 2
>>> a
bitarray('100000100')
>>> b >> 1
bitarray('011100101')

C语言没有指定负移位和大于或等于提升左操作数宽度的左移位的行为。确切的行为是编译器/机器特定的。此Python位数组库指定如下行为

• 位数组的长度永远不会因任何移位操作而改变

• 空白由0填充

• 负移位将引发ValueError

• 大于或等于位数组长度的移位将导致所有值都为0的位数组

位字节序

除非显式转换为机器表示，使用.tobytes()、.frombytes()、.tofile()和.fromfile()方法，以及使用memoryview，位字节序将不会对任何计算产生影响，因此可以跳过此部分。

由于位数组允许对单个位进行寻址，而机器以一个字节表示8位，因此此映射有两个明显的选择：小端字节序和大小端字节序。

在处理位数组对象的机器表示时，建议始终显式指定字节序。

默认情况下，位数组使用大端表示

>>> a = bitarray()
>>> a.endian()
'big'
>>> a.frombytes(b'A')
>>> a
bitarray('01000001')
>>> a[6] = 1
>>> a.tobytes()
b'C'

大端序意味着最高有效位首先出现。在这里，a[0]是最低地址（索引）和最高有效位，而a[7]是最高地址和最低有效位。

当创建一个新的位数组对象时，可以始终明确指定端序。

>>> a = bitarray(endian='little')
>>> a.frombytes(b'A')
>>> a
bitarray('10000010')
>>> a.endian()
'little'

在这里，低位首先出现，因为小端序意味着数值的递增与地址的递增相对应。因此，a[0]是最低地址和最低有效位，而a[7]是最高地址和最高有效位。

位端序是位数组对象的属性。一旦创建了位数组对象，端序就不能更改。在比较位数组对象时，端序（以及因此的机器表示）是不相关的；重要的是索引到位的映射。

>>> bitarray('11001', endian='big') == bitarray('11001', endian='little')
True

位运算（|、^、&=、|=、^=、~）是通过在C中使用相应的字节运算来高效实现的，即运算符作用于位数组对象的机器表示。因此，无法对具有不同端序的位数组执行位运算。

在转换到和从机器表示时，使用.tobytes()、.frombytes()、.tofile()和.fromfile()方法时，端序很重要。

>>> a = bitarray(endian='little')
>>> a.frombytes(b'\x01')
>>> a
bitarray('10000000')
>>> b = bitarray(endian='big')
>>> b.frombytes(b'\x80')
>>> b
bitarray('10000000')
>>> a == b
True
>>> a.tobytes() == b.tobytes()
False

如上所述，一旦创建了对象，端序就不能更改。但是，您可以创建具有不同端序的新位数组。

>>> a = bitarray('111000', endian='little')
>>> b = bitarray(a, endian='big')
>>> b
bitarray('111000')
>>> a == b
True

缓冲区协议

位数组对象支持缓冲区协议。它们可以导出自己的缓冲区，也可以导入另一个对象的缓冲区。有关此主题的更多信息，请阅读缓冲区协议。还有一个示例，展示了如何将文件内存映射到位数组：mmapped-file.py

可变位长度前缀码

.encode()方法接受一个映射符号到位数组的字典和一个可迭代对象，并在迭代过程中扩展位数组对象，以包含找到的编码符号。例如

>>> d = {'H':bitarray('111'), 'e':bitarray('0'),
...      'l':bitarray('110'), 'o':bitarray('10')}
...
>>> a = bitarray()
>>> a.encode(d, 'Hello')
>>> a
bitarray('111011011010')

请注意，字符串'Hello'是一个可迭代对象，但符号不仅限于字符，实际上任何不可变的Python对象都可以是符号。使用相同的字典，我们可以应用.decode()方法，它将返回符号列表

>>> a.decode(d)
['H', 'e', 'l', 'l', 'o']
>>> ''.join(a.decode(d))
'Hello'

由于符号不仅限于字符，因此有必要将它们作为列表的元素返回，而不仅仅是简单地返回连接的字符串。上述字典d可以使用函数bitarray.util.huffman_code()高效构建。我还编写了使用位数组在Python中进行Huffman编码以获取更多信息。

当码很大，并且你有许多解码调用时，大部分时间将花费在创建（相同的）内部解码树对象上。在这种情况下，创建一个decodetree对象会更快，该对象可以传递给位数组的.decode()和.iterdecode()方法，而不是将前缀码字典本身传递给这些方法。

>>> from bitarray import bitarray, decodetree
>>> t = decodetree({'a': bitarray('0'), 'b': bitarray('1')})
>>> a = bitarray('0110')
>>> a.decode(t)
['a', 'b', 'b', 'a']
>>> ''.join(a.iterdecode(t))
'abba'

decodetree对象是不可变的且不可哈希的，它的唯一目的是传递给位数组的.decode()和.iterdecode()方法。

冻结位数组

frozenbitarray对象与位数组对象非常相似。不同之处在于，这个frozenbitarray是不可变的、可哈希的，因此可以用作字典键。

>>> from bitarray import frozenbitarray
>>> key = frozenbitarray('1100011')
>>> {key: 'some value'}
{frozenbitarray('1100011'): 'some value'}
>>> key[3] = 1
Traceback (most recent call last):
    ...
TypeError: frozenbitarray is immutable

位数组对象

bitarray(initializer=0, /, endian='big', buffer=None) -> bitarray

返回一个新的位数组对象，其元素从可选的初始化对象和字节序初始化。初始化器可以是以下类型

int：创建给定长度的位数组。初始值未初始化。

str：从由 0 和 1 组成的字符串创建位数组。

iterable：从可迭代对象、序列或整数 0 或 1 创建位数组。

可选关键字参数

endian：指定创建的位数组对象的位字节序。允许的值是 big 和 little（默认为 big）。位字节序影响位数组的缓冲区表示。

buffer：任何暴露缓冲区的对象。如果提供，则 initializer 不能存在（或必须是 None）。导入的缓冲区可以是只读或可写，具体取决于对象类型。

新功能：版本 2.3 中的可选 buffer 参数。

位数组对象支持以下方法

all() -> bool

当数组中所有位都是 True 时返回 True。注意，a.all() 比 all(a) 快。

any() -> bool

当数组中任何位是 True 时返回 True。注意，a.any() 比 any(a) 快。

append(item, /)

将 item 追加到位数组的末尾。

buffer_info() -> tuple

返回一个包含以下内容的元组

0. 缓冲区的内存地址

1. 缓冲区大小（以字节为单位）

2. 位字节序作为字符串

3. 未使用的填充位数量

4. 缓冲区分配的内存（以字节为单位）

5. 内存是只读的

6. 缓冲区已导入

7. 缓冲区导出次数

bytereverse(start=0, stop=<end of buffer>, /)

原地反转缓冲区中范围（start，stop）内的字节位序。start 和 stop 索引以字节为单位（不是位）。默认情况下，缓冲区中的所有字节都反转。注意：此方法仅更改缓冲区；它不更改位数组对象的字节序。

新功能：版本 2.2.5 中的可选 start 和 stop 参数。

clear()

从位数组中删除所有项目。

新功能：版本 1.4。

copy() -> bitarray

返回位数组的副本。

count(value=1, start=0, stop=<end of array>, step=1, /) -> int

在位数组中计算 value 出现的次数。

新功能：版本 1.1.0 中的可选 start 和 stop 参数。

新功能：版本 2.3.7 中的可选 step 参数。

decode(code, /) -> list

给定前缀码（映射符号到位数组的字典或 decodetree 对象），解码位数组的内 容，并作为符号列表返回。

encode(code, iterable, /)

给定前缀码（映射符号到位数组的字典），迭代带有符号的可迭代对象，并将每个符号对应的位数组扩展到位数组。

endian() -> str

以字符串形式返回位数组的位字节序（little 或 big）。

extend(iterable, /)

将迭代器中的所有项目添加到bitarray的末尾。如果迭代器是字符串，则将每个0和1作为位添加（忽略空格和下划线）。

fill() -> int

向bitarray末尾添加零，使得bitarray的长度为8的倍数，并返回添加的位数（0..7）。

find(sub_bitarray, start=0, stop=<数组末尾>, /) -> int

返回sub_bitarray首次出现的位置的最低索引，使得sub_bitarray包含在[start:stop]中。如果sub_bitarray未找到，则返回-1。

自版本2.1起引入。

frombytes(bytes, /)

用原始字节扩展bitarray。即，每个追加字节将向bitarray添加8位。

fromfile(f, n=-1, /)

从文件对象f读取最多n字节以扩展bitarray。当n省略或为负时，读取直到EOF的所有数据。当n提供且为正但超出可用数据时，引发EOFError（但仍然读取和追加可用数据）。

index(sub_bitarray, start=0, stop=<数组末尾>, /) -> int

返回sub_bitarray首次出现的位置的最低索引，使得sub_bitarray包含在[start:stop]中。如果sub_bitarray不存在，则引发ValueError。

insert(index, value, /)

在index之前将value插入到bitarray中。

invert(index=<所有位>, /)

就地反转数组中的所有位。当给出可选的index时，仅反转索引处的单个位。

自版本1.5.3起引入：可选的index参数。

iterdecode(code, /) -> iterator

给定一个前缀码（一个将符号映射到bitarray的字典，或decodetree对象），解码bitarray的内容，并返回符号的迭代器。

itersearch(sub_bitarray, /) -> iterator

在self中搜索给定的sub_bitarray，并返回bitarray匹配self的起始位置的迭代器。

pack(bytes, /)

从字节扩展bitarray，其中每个字节对应单个位。字节b'\x00'映射到位0，所有其他字符映射到位1。此方法以及解包方法旨在在bitarray对象和其他具有不同内存视图的Python对象（例如NumPy的ndarray对象）之间高效传输数据。

pop(index=-1, /) -> item

返回第i个（默认为最后一个）元素并将其从bitarray中删除。如果bitarray为空或索引超出范围，则引发IndexError。

remove(value, /)

从bitarray中移除第一次出现的value。如果项目不存在，则引发ValueError。

reverse()

就地反转数组中的所有位。

search(sub_bitarray, limit=<none>, /) -> list

在self中搜索给定的sub_bitarray，并返回起始位置的列表。可选参数限制搜索结果的数量为指定的整数。默认情况下，返回所有搜索结果。

setall(value, /)

将位数组中的所有元素设置为 value。注意，a.setall(value) 与 a[:] = value 等价。

sort(reverse=False)

原地排序数组中的位。

to01() -> str

返回一个包含 '0' 和 '1' 的字符串，表示位数组中的位。

tobytes() -> bytes

返回位数组的字节表示。

tofile(f, /)

将位数组的字节表示写入文件对象 f。

tolist() -> list

返回一个包含位数组中项（0 或 1）的列表。注意，正在创建的列表对象将比位数组对象多 32 或 64 倍内存（取决于机器架构），如果位数组非常大，可能会引发内存错误。

unpack(zero=b'\x00', one=b'\x01') -> bytes

返回包含位数组中每个位的一个字符的字节，使用指定的映射。

其他对象

frozenbitarray(initializer=0, /, endian='big', buffer=None) -> frozenbitarray

返回一个 frozenbitarray 对象，其初始化方式与位数组对象相同。frozenbitarray 是不可变的且可散列的。其内容在创建后不能更改；然而，它可以作为字典键使用。

New in version 1.1.

decodetree(code, /) -> decodetree

给定一个前缀码（将符号映射到位数组的字典），创建一个二叉树对象以传递给 .decode() 或 .iterdecode()。

New in version 1.6.

在 bitarray 模块中定义的函数

bits2bytes(n, /) -> int

返回存储 n 位所需的字节数。

get_default_endian() -> string

返回创建新位数组对象时的默认字节序。除非调用 _set_default_endian()，否则返回值是 big。

New in version 1.3.

test(verbosity=1, repeat=1) -> TextTestResult

运行自检，并返回 unittest.runner.TextTestResult 对象。

在 bitarray.util 模块中定义的函数

This sub-module was add in version 1.2.

zeros(length, /, endian=None) -> bitarray

创建一个长度为 length 的位数组，所有值都为 0，可选的字节序，可以是 'big'、'little'。

urandom(length, /, endian=None) -> bitarray

返回一个长度为 length 的随机位位数组（使用 os.urandom）。

New in version 1.7.

pprint(bitarray, /, stream=None, group=8, indent=4, width=80)

在 stream 上打印对象的格式化表示（默认为 sys.stdout）。默认情况下，元素按字节（8 个元素）分组，每行 8 个字节（64 个元素）。非位数组对象通过标准库函数 pprint.pprint() 打印。

New in version 1.8.

make_endian(bitarray, /, endian) -> bitarray

当给定位数组的字节序与 endian 不同时，返回一个新的位数组，其字节序为 endian 且与原始位数组具有相同的元素。否则（字节序已为 endian），返回原始位数组不变。

New in version 1.3.

rindex(bitarray, value=1, start=0, stop=<end of array>, /) -> int

返回位数组中 value 的最右侧（最高）索引。如果值不存在，则引发 ValueError。

版本 2.3.0 中的新功能：可选的起始和停止参数。

strip(bitarray, /, mode='right') -> bitarray

返回一个新的 bitarray，从左边、右边或两边去除零。mode 参数允许的值是字符串：left、right、both

count_n(a, n, value=1, /) -> int

返回最低索引 i，对于该索引 a[:i].count(value) 等于 n。当 n 超出总计数（a.count(value)）时，引发 ValueError。

版本 2.3.6 中的新功能：可选的 value 参数。

parity(a, /) -> int

返回 bitarray a 的奇偶性。这等价于 a.count() % 2（但更高效）。

版本 1.9 中的新功能。

count_and(a, b, /) -> int

以内存高效的方式返回 a & b 的计数，不创建中间的 bitarray 对象。

count_or(a, b, /) -> int

以内存高效的方式返回 a | b 的计数，不创建中间的 bitarray 对象。

count_xor(a, b, /) -> int

以内存高效的方式返回 a ^ b 的计数，不创建中间的 bitarray 对象。

subset(a, b, /) -> bool

如果 bitarray a 是 bitarray b 的子集，则返回 True。与 subset(a, b) 相等，但更高效，因为我们可以在找到第一个不匹配时停止，并且不创建中间的 bitarray 对象。

ba2hex(bitarray, /) -> hexstr

返回一个包含 bitarray 的十六进制表示的字符串（长度必须是 4 的倍数）。

hex2ba(hexstr, /, endian=None) -> bitarray

十六进制表示的 bitarray。hexstr 可以包含任何数量的十六进制数字（包括奇数个数字），大小写均可。

ba2base(n, bitarray, /) -> str

返回一个包含 bitarray 的 base n ASCII 表示的字符串。允许的 n 值是 2、4、8、16、32 和 64。对于 n=16（十六进制），ba2hex() 将更快，因为 ba2base() 不会利用字节级操作。对于 n=32，使用 RFC 4648 Base32 字母表，对于 n=64，使用标准的 base 64 字母表。

另请参阅：[Bitarray 表示](https://github.com/ilanschnell/bitarray/blob/master/doc/represent.rst)

版本 1.9 中的新功能。

base2ba(n, asciistr, /, endian=None) -> bitarray

base n ASCII 表示的 bitarray。允许的 n 值是 2、4、8、16、32 和 64。对于 n=16（十六进制），hex2ba() 将更快，因为 base2ba() 不会利用字节级操作。对于 n=32，使用 RFC 4648 Base32 字母表，对于 n=64，使用标准的 base 64 字母表。

另请参阅：[Bitarray 表示](https://github.com/ilanschnell/bitarray/blob/master/doc/represent.rst)

版本 1.9 中的新功能。

ba2int(bitarray, /, signed=False) -> int

将给定的 bitarray 转换为整数。尊重 bitarray 的位顺序。signed 表示是否使用二进制补码表示整数。

int2ba(int, /, length=None, endian=None, signed=False) -> bitarray

将给定的整数转换为位数组（带有指定的字节序，且无前导（大端）或尾随（小端）零），除非提供了位数组的长度。如果整数不能用给定的位数表示，将引发< span class="docutils literal">OverflowError。 signed确定是否使用二进制补码表示整数，并要求提供< span class="docutils literal">length。

serialize(bitarray, /) -> bytes

返回位数组的序列化表示，该表示可以传递给< span class="docutils literal">deserialize()。它有效地表示位数组对象（包括其字节序）并保证在未来的版本中不会更改。

另请参阅：[Bitarray 表示](https://github.com/ilanschnell/bitarray/blob/master/doc/represent.rst)

New in version 1.8.

deserialize(bytes, /) -> bitarray

根据由< span class="docutils literal">serialize()返回的字节表示返回位数组。

另请参阅：[Bitarray 表示](https://github.com/ilanschnell/bitarray/blob/master/doc/represent.rst)

New in version 1.8.

vl_encode(bitarray, /) -> bytes

返回位数组的可变长度二进制表示。这种表示对于在二进制流中有效地存储小位数组很有用。使用< span class="docutils literal">vl_decode()进行解码。

另请参阅：可变长度位数组格式

新功能2.2。

vl_decode(stream, /, endian=None) -> bitarray

解码二进制流（整数迭代器或字节对象），并返回解码后的位数组。此函数仅消耗一个位数组，并保留剩余的流不变。StopIteration在未找到终止字节时引发。使用< span class="docutils literal">vl_encode()进行编码。

另请参阅：可变长度位数组格式

新功能2.2。

huffman_code(dict, /, endian=None) -> dict

给定一个频率图，一个将符号映射到其频率的字典，计算霍夫曼代码，即一个将符号映射到位数组（具有给定字节序）的字典。请注意，符号不限于字符串。符号可以是任何可哈希的对象（如< span class="docutils literal">None）。