位元組順序、大小和對齊¶

預設情況下，C 型別以機器的原生格式和位元組順序表示，並在必要時透過跳過填充位元組來正確對齊（根據 C 編譯器所使用的規則）。選擇此行為使得打包結構的位元組完全對應於相對應 C 結構的記憶體配置。是否使用原生位元組順序和填充或標準格式取決於應用程式。

或者，格式字串的第一個字元可以用來指示打包資料的位元組順序、大小和對齊，如下表所示：

如果第一個字元不是這些字元之一，則假設為 '@'。

>>> import struct
>>> struct.pack('>h', 1023)
b'\x03\xff'
>>> struct.pack('<h', 1023)
b'\xff\x03'

原生位元組順序是大端序或小端序，會取決於主機系統。例如，Intel x86、AMD64 (x86-64)和 Apple M1 是小端序；IBM z 和許多舊架構是大端序。可使用 sys.byteorder 來檢查你系統的位元組順序。

原生大小和對齊是使用 C 編譯器的 sizeof 運算式來決定的。這總是與原生位元組順序結合使用。

標準大小僅取決於格式字元；請參見格式字元區塊中的表格。

請注意 '@' 和 '=' 之間的差異：兩者都使用原生位元組順序，但後者的大小和對齊是標準化的。

'!' 形式表示網路位元組順序，根據 IETF RFC 1700 的定義，它總是大端序。

沒有方法來指示非原生位元組順序（強制位元組交換）；請使用適當的 '<' 或 '>' 選擇。

註解：

1. 填充只會在連續的結構成員之間自動加入。編碼結構的開頭或結尾不會加入填充。

2. 使用非原生大小和對齊時，例如使用 '<'、'>'、'=' 和 '!' 時，不會加入填充。

3. 要將結構的結尾對齊到特定型別的對齊需求，請以該型別的碼結束格式，重複次數為零。請參見範例。

格式字元¶

格式字元具有以下意義；在給定型別的情況下，C 和 Python 數值之間的轉換應該是顯而易見的。「標準大小」欄位指的是使用標準大小時（即當格式字串以 '<'、'>'、'!' 或 '=' 其中之一開始時）打包數值的位元組大小。使用原生大小時，打包數值的大小取決於平台。

註解：

1. '?' 轉換碼對應於自 C99 以來 C 標準定義的 _Bool 型別。在標準模式下，它由一個位元組表示。

2. 當嘗試使用任何整數轉換碼打包非整數時，如果非整數具有 __index__() 方法，則會呼叫該方法在打包之前將引數轉換為整數。

   在 3.2 版的變更: 新增對非整數使用 __index__() 方法的支援。

3. 'n' 和 'N' 轉換碼僅適用於原生大小（作為預設選擇或使用 '@' 位元組順序字元）。對於標準大小，你可以使用適合你應用程式的其他整數格式。

4. 對於 'f'、'd' 和 'e' 轉換碼，打包表示法使用 IEEE 754 binary32、binary64 或 binary16 格式（分別對應於 'f'、'd' 或 'e'），無論平台使用何種浮點數格式。

5. 'P' 格式字元僅適用於原生位元組順序（作為預設選擇或使用 '@' 位元組順序字元）。位元組順序字元 '=' 根據主機系統選擇使用小端序或大端序。struct 模組不將其解釋為原生順序，因此 'P' 格式不可用。

6. IEEE 754 binary16「半精度 (half precision)」型別是在 2008 年的 IEEE 754 標準修訂版中引入的。它有一個符號位元 (sign bit)、5 位元指數和 11 位元精度（明確儲存 10 位元），可以全精度表示大約 6.1e-05 到 6.5e+04 之間的數字。此型別未被 C 編譯器廣泛支援：在典型機器上，unsigned short 可以用於儲存但不能用於數學運算。請參見 Wikipedia 上的半精度浮點數格式頁面以取得更多資訊。

7. 打包時，'x' 插入一個 NUL 位元組。

8. 'p' 格式字元編碼一個「Pascal 字串」，意思是儲存在固定位元組數中的短、長度可變字串，由計數指定。儲存的第一個位元組是字串的長度，或與 255 間取較小者。字串的位元組在其後。如果傳遞給 pack() 的字串太長（長於計數減 1），則只儲存字串的前 count-1 個位元組。如果字串短於 count-1，則用空位元組填充，使得總共使用恰好 count 個位元組。請注意，對於 unpack()， 'p' 格式字元消耗 count 個位元組，但回傳的字串永遠不能包含超過 255 個位元組。

9. 對於 's' 格式字元，計數被直譯為位元組的長度，而不是像其他格式字元那樣的重複次數；例如，'10s' 表示一個 10 位元組字串，對應於單一 Python 位元組字串，而 '10c' 表示 10 個獨立的單位元組字元元素（例如 cccccccccc），對應於十個不同的 Python 位元組物件。（請參見 範例 以了解具體差異的示範。）如果未給定計數，則預設為 1。打包時，會適當地截斷或用空位元組填充字串以使其適合。解包時，結果位元組物件總是恰好具有指定的位元組數。作為特殊情況，'0s' 表示單一空字串（而 '0c' 表示 0 個字元）。

格式字元前面可以加上整數重複次數。例如，格式字串 '4h' 與 'hhhh' 意思完全相同。

格式之間的空白字元會被忽略；但是計數和其格式不能包含空白字元。

當使用整數格式之一（'b'、'B'、'h'、'H'、'i'、'I'、'l'、'L'、'q'、'Q'）打包數值 x 時，如果 x 超出該格式的有效範圍，則會觸發 struct.error。

對於 '?' 格式字元，回傳值是 True 或 False。打包時，使用引數物件的真值。原生或標準布林值表示法中的 0 或 1 將被打包，解包時任何非零值都將為 True。

範例¶

使用大端序打包和解包三種不同大小的整數：

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

嘗試打包對於定義欄位來說太大的整數：

>>> pack(">h", 99999)
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
struct.error: 'h' format requires -32768 <= number <= 32767

示範 's' 和 'c' 格式字元之間的差異：

>>> pack("@ccc", b'1', b'2', b'3')
b'123'
>>> pack("@3s", b'123')
b'123'

解包的欄位可以透過將其指派給變數或將結果包裝在具名元組中來命名：

>>> 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 呼叫中，在打包的 '#' 之後加入了三個 NUL 位元組，以將後續整數對齊到四位元組邊界。在此範例中，輸出是在小端序機器上產生的：

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

假設平台的 long 對齊到 4 位元組邊界，以下格式 'llh0l' 會在結尾加入兩個填充位元組：

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

原生格式¶

當構造模擬原生配置的格式字串時，編譯器和機器架構會決定位元組順序和填充。在這種情況下，應該使用 @ 格式字元來指定原生位元組順序和資料大小。內部填充位元組通常會自動插入。可能需要在格式字串的結尾使用零重複格式碼來向上舍入到正確的位元組邊界，以便正確對齊連續的資料區塊 (chunks)。

考慮這兩個簡單範例（在 64 位元小端序機器上）：

>>> calcsize('@lhl')
24
>>> calcsize('@llh')
18

在第二個格式字串的結尾，如果不使用額外填充，資料不會填充到 8 位元組邊界。零重複格式碼解決了這個問題：

>>> calcsize('@llh0l')
24

'x' 格式碼可以用來指定重複，但對於原生格式來說最好使用像 '0l' 這樣的零重複格式。

預設使用原生位元組順序和對齊，但最好明確使用 '@' 前綴字元。

標準格式¶

當與你的行程之外的網路或儲存區等交換資料時，要夠精確。指定確切的位元組順序、大小和對齊。不要假設它們與特定機器的原生順序匹配。例如，網路位元組順序是大端序，而許多流行的 CPU 是小端序。透過明確定義這一點，使用者無需關心其程式碼運行的平台細節。第一個字元通常應該是 < 或 >（或 !）。填充是程式設計師的責任。零重複格式字元不會起作用。取而代之的是使用者必須在需要的地方明確加入 'x' 填充位元組。重新檢視上一節的範例，我們有：

>>> calcsize('<qh6xq')
24
>>> pack('<qh6xq', 1, 2, 3) == pack('@lhl', 1, 2, 3)
True
>>> calcsize('@llh')
18
>>> pack('@llh', 1, 2, 3) == pack('<qqh', 1, 2, 3)
True
>>> calcsize('<qqh6x')
24
>>> calcsize('@llh0l')
24
>>> pack('@llh0l', 1, 2, 3) == pack('<qqh6x', 1, 2, 3)
True

上述結果（在 64 位元機器上執行）和在不同機器上執行時不保證會匹配。例如，下面的範例是在 32 位元機器上執行的：

>>> calcsize('<qqh6x')
24
>>> calcsize('@llh0l')
12
>>> pack('@llh0l', 1, 2, 3) == pack('<qqh6x', 1, 2, 3)
False