4.5 組み込みモジュール struct

  

このモジュールはパイソンの値とパイソンの文字列として表現されたCの構造体との間で変換を行います。これはファーマット文字列（後述）をCの構造体レイアウトおよびパイソンの値との意図した相互変換を簡潔に表現する記述として使います。

このモジュールは以下の例外と関数を定義しています。

error

例外は様々なケースで発生します。引き数は何が悪いかを表す文字列です。

pack (fmt, v1, v2, ...)

与えられたファーマットに従ってパックされた値v1, v2, ...を含む文字列を返します。引き数はフォーマットが要求する値に正確に一致していなければなりません。

unpack (fmt, string)

与えられたファーマットに従って文字列（おそらくpack(fmt, ...) でパックされた）をアンパックします。結果はアイテムが１つだけの場合でもタプル になります。文字列はフォーマットが要求するデータ量を正確に含んでいなければな りません。（つまりlen(string)はcalcsize(fmt) に等しくなければなりません。）

calcsize (fmt)

与えられたフォーマットに対応する構造体（従って文字列）のサイズを返します。

フォーマット文字は以下の意味を持ちます。与えるタイプによってCとパイソンの 値の間の変換を明確にすべきです。

フォーマット	C Type	Python
x	pad byte	no value
c	char	長さ１の文字列
b	signed char	整数
B	unsigned char	整数
h	short	整数
H	unsigned short	整数
i	int	整数
I	unsigned int	整数
l	long	整数
L	unsigned long	整数
f	float	浮動小数
d	double	浮動小数
s	char[]	文字列

フォーマット文字は整数の繰り返し回数を頭に付けることが出来ます。例えば、 フォーマット文字列'4h'は'hhhh'とまったく同じです。

フォーマット間のホワイトスペース文字は無視されます。繰り返し回数と フォーマットの間にホワイトスペースを含んでいてはいけません。

's'フォーマット文字に関しては、繰り返し回数は文字列のサイズとして 解釈され、他のフォーマット文字に対するように繰り返し回数とは解釈されません。 例えば、'10s'は１つの１０バイトの文字列を意味しますが、 '10c'は１０個の文字を意味します。パックする際には文字列は切り詰め られるか、そのサイズにフィットするようにヌルバイトで埋められます。 アンパックする際には結果の文字列は常に指定されたバイト数に等しくなります。 特別な場合として、'0s'は１つの空文字列を意味します。（一方 '0c'は０個の文字を意味します。）

'I'と'L'フォーマット文字については、戻り値はパイソンの ロング整数となります。

デフォルトではCの数値はそのマシンのネイティブ形式とバイトオーダ および必要であればパディングバイトで適切にアライメントされて（これはCコンパイラ で使われる規則に依ります）表現されています。

その代替として、フォーマット文字列の最初の文字を使ってバイトオーダ、 パックされたデータのサイズとアライメントを以下の表に従って 指定することができます。

文字	バイトオーダ	サイズとアライメント
@	ネイティブ	ネイティブ
=	ネイティブ	標準
<	リトルエンディアン	標準
>	ビッグエンディアン	標準
!	ネットワーク （＝ ビッグエンディアン）	標準

最初の文字がこれらの内の１つでなければ、'@'が仮定されます。

ネイティブバイトオーダはホストマシンによってビッグエンディアンまたは リトルエンディアンになります。（例えば、MotorolaとSunはビッグエンディアンで、 IntelとDECはリトルエンディアンです。）

ネイティブサイズとアライメントは使用しているCコンパイラのsizeof式によって 決まります。これは常にネイティブバイトオーダと結び付けられています。

標準のサイズとアライメントは次のとおりです。 いかなるタイプに対してもアライメントは要求されません。つまりshortは２バイト、 intとlongは４バイトです。floatとdoubleはそれぞれ３２ビットと６４ビットの IEEE浮動小数点数です。

'@'と'='の違いに注意して下さい。共にネイティブバイトオーダ を使いますが後者のサイズとアライメントは標準となります。

フォーム'!'はネットワークバイトオーダがビッグエンディアンか リトルエンディアンかを覚えられないと主張する心の貧しい人たち用に利用できる ようになっています。

非ネイティブバイトオーダ（バイトスワップを強制する等）を指示する 方法はありません。'<'または'>'を適切に選択して 使って下さい。

例：（すべてビッグエンディアンマシンでネイティブバイトオーダおよび サイズとアライメントを使用）

>>> from struct import *
>>> pack('hhl', 1, 2, 3)
'\000\001\000\002\000\000\000\003'
>>> unpack('hhl', '\000\001\000\002\000\000\000\003')
(1, 2, 3)
>>> calcsize('hhl')
8
>>>

ヒント：特定のタイプのアライメント要求に構造体の最後を整列させたい 場合には、繰り返し回数０を持つそのタイプをフォーマットの最後に置きます。 例えば、フォーマット'llh0l'はlongは４バイト境界に整列させられる ことを仮定して最後に２バイトの埋め草を指定します。 これはネイティブサイズとアライメントが有効なときのみ機能します。 標準のサイズとアライメントはいかなるアライメントも強制しません。

See Also:

モジュール array   (同種データのバイナリストレージをパックします。)