struct — אריזה ופריקה של סוגי נתונים פרימיטיביים

מודול זה מבצע המרות בין ערכי Python ל-structs בסגנון C המיוצגים כאובייקטי bytes של Python, תוך שימוש במחרוזות פורמט לתיאור פריסת הנתונים.

סדרי הבתים הבאים נתמכים:

תו	סדר בתים	גודל	יישור
@	native	native	native
<	little-endian	סטנדרטי	ללא
>	big-endian	סטנדרטי	ללא
!	network (= big-endian)	סטנדרטי	ללא

סוגי הנתונים הבאים נתמכים:

פורמט	סוג C	סוג Python	גודל סטנדרטי
b	signed char	integer	1
B	unsigned char	integer	1
h	short	integer	2
H	unsigned short	integer	2
i	int	integer (1)	4
I	unsigned int	integer (1)	4
l	long	integer (1)	4
L	unsigned long	integer (1)	4
q	long long	integer (1)	8
Q	unsigned long long	integer (1)	8
e	n/a (half-float)	float (2)	2
f	float	float (2)	4
d	double	float (2)	8
s	char[]	bytes
P	void *	integer

1. דורש תמיכת long כאשר משתמשים בערכים גדולים מ-30 ביט.

2. דורש תמיכה בנקודה צפה.

הבדל מ-CPython

רווחים לבנים אינם נתמכים במחרוזות פורמט.

דוגמאות

אריזה ופריקה של ערכי little-endian. הקידומת < בוחרת סדר בתים little-endian עם גדלים סטנדרטיים וללא יישור:

import struct

# Pack an unsigned short (H, 2 bytes) then an unsigned int (I, 4 bytes).
data = struct.pack("<HI", 7, 1000)
# data == b'\x07\x00\xe8\x03\x00\x00'

# Unpack returns a tuple of the values, in order.
struct.unpack("<HI", data)
# (7, 1000)

# calcsize() reports how many bytes the format needs.
struct.calcsize("<HI")
# 6

אריזה לתוך וקריאה מתוך חוצץ (buffer) קיים בהיסט בתים:

buf = bytearray(8)

# Write a little-endian signed int (i) at offset 2.
struct.pack_into("<i", buf, 2, -12345)
# buf == bytearray(b'\x00\x00\xc7\xcf\xff\xff\x00\x00')

# Read it back from the same offset.
struct.unpack_from("<i", buf, 2)
# (-12345,)

פונקציות

struct.calcsize(fmt: str) → int

מחזיר את מספר הבתים הדרושים לאחסון ה-fmt הנתון.

struct.pack(fmt: str, *values: Any) → bytes

אורז את ה-values בהתאם למחרוזת הפורמט fmt. ערך ההחזרה הוא אובייקט bytes המקודד את הערכים.

struct.pack_into(fmt: str, buffer: Any, offset: int, *values: Any) → None

אורז את ה-values בהתאם למחרוזת הפורמט fmt לתוך buffer החל מ-offset. offset יכול להיות שלילי כדי לספור מסוף ה-buffer.

struct.unpack(fmt: str, data: bytes) → Tuple

פורק מתוך ה-data בהתאם למחרוזת הפורמט fmt. ערך ההחזרה הוא tuple של הערכים שפורקו.

struct.unpack_from(fmt: str, data: bytes, offset: int = 0, /) → Tuple

פורק מתוך ה-data החל מ-offset בהתאם למחרוזת הפורמט fmt. offset יכול להיות שלילי כדי לספור מסוף ה-data. ערך ההחזרה הוא tuple של הערכים שפורקו.