struct – Интерпретация байтов как упакованных двоичных данных¶struct – Interpret bytes as packed binary data

Порядок байтов, размер и выравнивание¶Byte Order, Size, and Alignment

По умолчанию типы C представляются в собственном формате и порядке байтов машины и правильно выравниваются путём пропуска байтов заполнения при необходимости (в соответствии с правилами, используемыми компилятором C).

В качестве альтернативы, первый символ строки формата может использоваться для указания порядка байтов, размера и выравнивания упакованных данных, как показано в следующей таблице:

Если первый символ не один из этих, предполагается '@'.

Собственный порядок байтов может быть big-endian или little-endian в зависимости от хост-системы. Например, Intel x86 и AMD64 (x86-64) используют little-endian; Motorola 68000 и PowerPC G5 – big-endian; ARM и Intel Itanium поддерживают переключаемый порядок байтов (bi-endian). Используйте sys.byteorder для проверки порядка байтов вашей системы.

Собственный размер и выравнивание определяются с помощью выражения sizeof компилятора C. Это всегда используется вместе с собственным порядком байт.

Стандартный размер зависит только от символа формата; см. таблицу в разделе Символы формата.

Обратите внимание на различие между '@' и '=': оба используют собственный порядок байт, но размер и выравнивание второго стандартизированы.

Форма '!' доступна для тех несчастных, кто утверждает, что не может запомнить, является ли сетевой порядок байтов big-endian или little-endian.

Нет способа указать несобственный порядок байт (принудительную перестановку байт); используйте соответствующий выбор из '<' или '>'.

Примечания:

1. Заполнение автоматически добавляется только между последовательными членами структуры. Начало и конец закодированной структуры не дополняются.

2. Заполнение не добавляется при использовании несобственного размера и выравнивания, например, с ‘<’, ‘>’, ‘=’ и ‘!’.

3. Чтобы выровнять конец структуры по требованию выравнивания конкретного типа, завершите формат кодом этого типа с нулевым количеством повторений. См. Примеры.

Символы формата¶Format Characters

Символы формата имеют следующее значение; преобразование между значениями C и Python должно быть очевидным, исходя из их типов. Столбец «Стандартный размер» указывает размер упакованного значения в байтах при использовании стандартного размера; то есть когда строка формата начинается с одного из '<', '>', '!' или '='. При использовании собственного размера размер упакованного значения зависит от платформы.

Примечания:

1. Код преобразования '?' соответствует типу _Bool, определённому в стандарте C99. Если этот тип недоступен, он эмулируется с помощью char. В стандартном режиме он всегда представлен одним байтом.

2. При попытке упаковать нецелое число с использованием любого из кодов преобразования целых чисел, если нецелое число имеет метод __index__(), то этот метод вызывается для преобразования аргумента в целое число перед упаковкой.

   Изменено в версии 3.2: Использование метода __index__() для нецелых чисел появилось в версии 3.2.

3. Коды преобразования 'n' и 'N' доступны только для родного размера (выбранного по умолчанию или с символом порядка байтов '@'). Для стандартного размера можно использовать любой из других целочисленных форматов, который подходит для приложения.

4. Для кодов преобразования 'f', 'd' и 'e' упакованное представление использует форматы IEEE 754 binary32, binary64 или binary16 (для 'f', 'd' или 'e' соответственно), независимо от формата чисел с плавающей запятой, используемого платформой.

5. Символ формата 'P' доступен только для родного порядка байтов (выбранного по умолчанию или с символом порядка байтов '@'). Символ порядка байтов '=' выбирает порядок little- или big-endian в зависимости от хост-системы. Модуль struct не интерпретирует это как родной порядок, поэтому формат 'P' недоступен.

6. Тип IEEE 754 binary16 «половинной точности» был введён в редакции стандарта IEEE 754 2008 года. Он имеет знаковый бит, 5-битную экспоненту и 11-битную точность (10 бит хранятся явно) и может представлять числа от примерно 6.1e-05 до 6.5e+04 с полной точностью. Этот тип не получил широкой поддержки в компиляторах C: на типичной машине unsigned short можно использовать для хранения, но не для математических операций. См. страницу Википедии о формате чисел с плавающей запятой половинной точности для получения дополнительной информации.

Символу формата может предшествовать целочисленный счётчик повторений. Например, строка формата '4h' означает то же самое, что и 'hhhh'.

Пробельные символы между форматами игнорируются; однако счётчик и его формат не должны содержать пробелов.

Для символа формата 's' счётчик интерпретируется как длина строки в байтах, а не как количество повторений, как для других символов формата; например, '10s' означает одну 10-байтовую строку, а '10c' – 10 символов. Если счётчик не указан, по умолчанию он равен 1. При упаковке строка усекается или дополняется нулевыми байтами по мере необходимости, чтобы соответствовать размеру. При распаковке результирующий объект bytes всегда имеет ровно указанное количество байт. В особом случае '0s' означает одну пустую строку (а '0c' – 0 символов).

При упаковке значения x с использованием одного из целочисленных форматов ('b', 'B', 'h', 'H', 'i', 'I', 'l', 'L', 'q', 'Q'), если x выходит за допустимый диапазон для этого формата, то вызывается struct.error.

Символ форматирования 'p' кодирует «строку Паскаля» – короткую строку переменной длины, хранящуюся в фиксированном количестве байт, задаваемом счётчиком. Первым байтом хранится длина строки или 255 (выбирается меньшее). Затем следуют байты строки. Если строка, переданная в pack(), слишком длинна (длиннее, чем счётчик минус 1), сохраняются только первые count-1 байт строки. Если строка короче count-1, она дополняется нулевыми байтами так, чтобы всего было использовано ровно счётчик байт. Обратите внимание, что для unpack() символ форматирования 'p' потребляет count байт, но возвращаемая строка никогда не может содержать более 255 байт.

Для символа формата '?' возвращаемое значение – True или False. При упаковке используется истинностное значение объекта-аргумента. Будет упакован либо 0, либо 1 в родном или стандартном представлении bool, и любое ненулевое значение будет True при распаковке.

Примеры¶Examples

Простой пример упаковки/распаковки трёх целых чисел:

>>> from struct import *
>>> pack('hhl', 1, 2, 3)
b'\x00\x01\x00\x02\x00\x00\x00\x03'
>>> unpack('hhl', b'\x00\x01\x00\x02\x00\x00\x00\x03')
(1, 2, 3)
>>> calcsize('hhl')
8

Распакованные поля можно именовать, присваивая их переменным или оборачивая результат в именованный кортеж:

>>> record = b'raymond   \x32\x12\x08\x01\x08'
>>> name, serialnum, school, gradelevel = unpack('<10sHHb', record)

>>> from collections import namedtuple
>>> Student = namedtuple('Student', 'name serialnum school gradelevel')
>>> Student._make(unpack('<10sHHb', record))
Student(name=b'raymond   ', serialnum=4658, school=264, gradelevel=8)

Порядок символов формата может влиять на размер, поскольку заполнение, необходимое для удовлетворения требований выравнивания, отличается:

>>> pack('ci', b'*', 0x12131415)
b'*\x00\x00\x00\x12\x13\x14\x15'
>>> pack('ic', 0x12131415, b'*')
b'\x12\x13\x14\x15*'
>>> calcsize('ci')
8
>>> calcsize('ic')
5

Следующий формат 'llh0l' указывает два байта заполнения в конце, предполагая, что значения типа long выровнены по границе в 4 байта:

>>> pack('llh0l', 1, 2, 3)
b'\x00\x00\x00\x01\x00\x00\x00\x02\x00\x03\x00\x00'

Это работает только при использовании собственного размера и выравнивания; стандартный размер и выравнивание не обеспечивают никакого выравнивания.