GV

GeezerVison

The World Wide Web, restored to 800 pixels of glory.

Home|About|Gaming cabinet|Archives|How it works|Starter sites

On this site

  • فهرست مطالب
  • خدمات داده‌های دودویی
  • codecs --- رجیستری کدک و کلاس‌های پایه
  • گزارش یک اشکال
  • بهبود این صفحه
  • نمایش منبع
  • نمایش منبع ترجمه
  • اندیس
  • ماژول‌ها
  • Python
  • 3.15.2 documentation
  • کتابخانه‌ی استاندارد پایتون

This view

  • Original page
  • New address

GeezerVison is showing python.github.io — struct --- تفسیر بایت‌ها به‌عنوان داده‌های دودویی بسته‌بندی‌شده

struct --- تفسیر بایت‌ها به‌عنوان داده‌های دودویی بسته‌بندی‌شده¶

کد منبع: Lib/struct.py

این ماژول بین مقادیر پایتون و ساختارهای C که به‌صورت اشیای bytes پایتون نمایش داده می‌شوند، تبدیل انجام می‌دهد. رشته‌های قالب فشرده، تبدیل‌های موردنظر به/از مقادیر پایتون را توصیف می‌کنند. توابع و اشیای این ماژول می‌توانند برای دو کاربرد تا حد زیادی متمایز استفاده شوند: تبادل داده با منابع خارجی (پرونده‌ها یا اتصال‌های شبکه)، یا انتقال داده بین برنامه‌ی پایتون و لایه‌ی C.

نکته

هنگامی که هیچ نویسه‌ی پیشوندی داده نشود، حالت بومی پیش‌فرض است. این حالت داده‌ها را بر اساس سکو و کامپایلری که مفسر پایتون بر پایه‌ی آن‌ها ساخته شده است، بسته‌بندی یا واگشایی می‌کند. نتیجه‌ی بسته‌بندی یک ساختار C مشخص، شامل بایت‌های پرکننده‌ای است که تراز مناسب را برای انواع C مربوط حفظ می‌کنند؛ به‌طور مشابه، هنگام واگشایی نیز تراز در نظر گرفته می‌شود. در مقابل، هنگام تبادل داده بین منابع خارجی، برنامه‌نویس مسئول تعیین ترتیب بایت‌ها و بایت‌های پرکننده بین المان‌ها است. برای جزئیات، ترتیب بایت، اندازه و هم‌ترازی را ببینید.

چندین تابع struct (و متدهای Struct) یک آرگومان بافر دریافت می‌کنند. این به اشیایی اشاره دارد که پروتکل بافر را پیاده‌سازی می‌کنند و یک بافر قابل خواندن یا قابل خواندن و نوشتن فراهم می‌کنند. رایج‌ترین انواعی که برای این منظور استفاده می‌شوند، bytes و bytearray هستند، اما بسیاری از انواع دیگر که می‌توان آن‌ها را به‌عنوان آرایه‌ای از بایت‌ها در نظر گرفت، پروتکل بافر را پیاده‌سازی می‌کنند، به‌طوری که بتوان آن‌ها را بدون کپی اضافی از یک شیء bytes خواند/پر کرد.

توابع و استثناها¶

این ماژول استثنا و توابع زیر را تعریف می‌کند:

exception struct.error¶

استثنایی که در موارد مختلف پرتاب می‌شود؛ آرگومان آن رشته‌ای است که توضیح می‌دهد چه چیزی اشتباه است.

struct.pack(format, v1, v2, ...)¶

یک شیء bytes حاوی مقادیر v1، v2، ... برمی‌گرداند که بر اساس رشته قالب format بسته‌بندی شده‌اند. آرگومان‌ها باید دقیقاً با مقادیر مورد نیاز قالب مطابقت داشته باشند.

struct.pack_into(format, buffer, offset, v1, v2, ...)¶

مقادیر v1، v2، ... را مطابق رشته‌ی قالب format بسته‌بندی کنید و بایت‌های بسته‌بندی‌شده را در بافر قابل‌نوشتن buffer از موقعیت offset بنویسید. توجه داشته باشید که offset یک آرگومان الزامی است. offset منفی از انتهای buffer شمارش می‌شود.

struct.unpack(format, buffer)¶

از بافر buffer (که احتمالاً با pack(format, ...) بسته‌بندی شده است) بر اساس رشته‌ی قالب format واگشایی می‌کند. نتیجه یک تاپل است، حتی اگر دقیقاً شامل یک آیتم باشد. اندازه‌ی بافر بر حسب بایت باید با اندازه‌ی مورد نیاز قالب مطابقت داشته باشد، همان‌طور که calcsize() نشان می‌دهد.

struct.unpack_from(format, /, buffer, offset=0)¶

از buffer با شروع از موقعیت offset، بر اساس رشته‌ی قالب format واگشایی کنید. نتیجه حتی اگر دقیقاً شامل یک آیتم باشد، یک تاپل است. اندازه‌ی بافر بر حسب بایت، با شروع از موقعیت offset، باید حداقل برابر با اندازه‌ی موردنیاز قالب باشد، همان‌طور که calcsize() نشان می‌دهد. یک offset منفی از انتهای buffer شمارش می‌شود.

struct.iter_unpack(format, buffer)¶

به‌صورت تکراری از بافر buffer بر اساس رشته‌ی قالب format واگشایی می‌شود. این تابع یک پیمایش‌گر برمی‌گرداند که تکه‌هایی با اندازه‌ی یکسان از بافر می‌خواند تا زمانی که تمام محتوای آن مصرف شود. اندازه‌ی بافر بر حسب بایت باید مضربی از اندازه‌ی مورد نیاز قالب باشد، همان‌طور که calcsize() نشان می‌دهد.

هر تکرار، یک تاپل را مطابق آنچه رشته‌ی قالب مشخص می‌کند برمی‌گرداند.

اضافه شده در نسخه‌ی 3.4.

struct.calcsize(format)¶

اندازه‌ی ساختار (و بنابراین اندازه‌ی شیء bytes تولیدشده توسط pack(format, ...)) متناظر با رشته‌ی قالب format را برمی‌گرداند.

رشته‌های قالب¶

رشته‌های قالب، چیدمان داده‌ها را هنگام بسته‌بندی و واگشایی داده توصیف می‌کنند. آن‌ها از نویسه‌های قالب تشکیل شده‌اند که نوع داده‌هایی را که بسته‌بندی/واگشایی می‌شوند مشخص می‌کنند. افزون بر این، نویسه‌های ویژه ترتیب بایت، اندازه و ترازبندی را کنترل می‌کنند. هر رشته‌ی قالب شامل یک نویسه‌ی پیشوندی اختیاری است که ویژگی‌های کلی داده‌ها را توصیف می‌کند و یک یا چند نویسه‌ی قالب که مقادیر واقعی داده و فضای پرکننده را توصیف می‌کنند.

ترتیب بایت، اندازه و هم‌ترازی¶

به‌طور پیش‌فرض، انواع C در قالب و ترتیب بایت بومی ماشین نمایش داده می‌شوند و در صورت لزوم با پرش از بایت‌های پرکننده (طبق قواعد استفاده‌شده توسط کامپایلر C) به‌درستی هم‌تراز می‌شوند. این رفتار انتخاب شده است تا بایت‌های یک ساختار فشرده دقیقاً با چیدمان حافظه‌ی ساختار C متناظر مطابقت داشته باشند. این‌که از ترتیب بایت و پرکنندگی بومی استفاده شود یا از قالب‌های استاندارد، به کاربرد بستگی دارد.

به‌عنوان جایگزین، می‌توان از اولین نویسه‌ی رشته‌ی قالب برای نشان دادن ترتیب بایت‌ها، اندازه و هم‌ترازی داده‌های بسته‌بندی‌شده، مطابق جدول زیر استفاده کرد:

نویسه

ترتیب بایت

اندازه

تراز

@

بومی

بومی

بومی

=

بومی

استاندارد

هیچ

<

کوچک‌اندیان (little-endian)

استاندارد

هیچ

>

بزرگ‌اندیان

استاندارد

هیچ

!

شبکه (= بزرگ‌اندیان)

استاندارد

هیچ

اگر اولین نویسه یکی از این‌ها نباشد، '@' فرض می‌شود.

نکته

عدد ۱۰۲۳ (0x3ff در مبنای شانزده) بازنمایی‌های بایتی زیر را دارد:

  • 03 ff در بزرگ‌اندیان (>)

  • ff 03 به‌صورت کوچک‌اندیان (little-endian) (<)

مثال پایتون:

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

ترتیب بایت بومی، بسته به سیستم میزبان، بزرگ‌اندیان (big-endian) یا کوچک‌اندیان (little-endian) است. برای مثال، Intel x86، AMD64 (x86-64) و Apple M1 کوچک‌اندیان هستند؛ IBM z و بسیاری از معماری‌های قدیمی بزرگ‌اندیان هستند. برای بررسی ترتیب بایت (endianness) سیستم خود از sys.byteorder استفاده کنید.

اندازه و هم‌ترازی بومی با استفاده از عبارت sizeof کامپایلر C تعیین می‌شود. این همیشه با ترتیب بایت بومی ترکیب می‌شود.

اندازه‌ی استاندارد فقط به نویسه‌ی قالب بستگی دارد؛ جدول موجود در بخش Type Codes را ببینید.

به تفاوت بین '@' و '=' توجه کنید: هر دو از ترتیب بایت‌های بومی استفاده می‌کنند، اما اندازه و هم‌ترازی مورد دوم استاندارد شده است.

قالب '!' نمایانگر ترتیب بایت‌های شبکه است که مطابق تعریف IETF RFC 1700، همیشه به‌صورت بزرگ‌اندیان (big-endian) است.

راهی برای مشخص کردن ترتیب بایت غیربومی (اجبار به جابجایی بایت‌ها) وجود ندارد؛ از انتخاب مناسب '<' یا '>' استفاده کنید.

یادداشت‌ها:

  1. فضای پرکننده (padding) فقط به‌صورت خودکار بین اعضای متوالی ساختار اضافه می‌شود. هیچ فضای پرکننده‌ای در ابتدا یا انتهای ساختار کدگذاری‌شده اضافه نمی‌شود.

  2. هنگام استفاده از اندازه و ترازبندی غیربومی، هیچ پرکننده‌ای (padding) اضافه نمی‌شود، برای مثال با '<'، '>'، '=' و '!'.

  3. برای هم‌تراز کردن انتهای یک ساختار با الزام هم‌ترازی یک نوع خاص، قالب را با کد آن نوع و تعداد تکرار صفر به پایان ببرید. مثال‌ها را ببینید.

Type Codes¶

نویسه‌های قالب معنای زیر را دارند؛ با توجه به نوع آن‌ها، تبدیل بین مقادیر C و پایتون باید بدیهی باشد. ستون «اندازه استاندارد» به اندازه‌ی مقدار بسته‌بندی‌شده بر حسب بایت هنگام استفاده از اندازه استاندارد اشاره دارد؛ یعنی زمانی که رشته‌ی قالب با یکی از '<'، '>'، '!' یا '=' شروع شود. هنگام استفاده از اندازه بومی، اندازه‌ی مقدار بسته‌بندی‌شده وابسته به سکو است.

قالب

نوع C

نوع پایتون

اندازه استاندارد

یادداشت‌ها

x

بایت پرکننده

بدون مقدار

(7)

c

char

بایت‌هایی با طول ۱

1

b

signed char

int

1

(2)

B

unsigned char

int

1

(2)

?

_Bool

bool

1

(1)

h

short

int

2

(2)

H

unsigned short

int

2

(2)

i

int

int

4

(2)

I

unsigned int

int

4

(2)

l

long

int

4

(2)

L

unsigned long

int

4

(2)

q

long long

int

۸

(2)

Q

unsigned long long

int

۸

(2)

n

ssize_t

int

(2), (3)

N

size_t

int

(2), (3)

e

_Float16

float

2

(4), (6)

f

float

float

4

(4)

d

double

float

۸

(4)

Zf

float complex

complex

۸

(10)

Zd

double complex

complex

16

(10)

s

char[]

bytes

(9)

p

char[]

bytes

(8)

P

void*

int

(2), (5)

تغییر یافته در نسخه‌ی 3.3: پشتیبانی از قالب‌های 'n' و 'N' اضافه شد.

تغییر یافته در نسخه‌ی 3.6: پشتیبانی از قالب 'e' اضافه شد.

تغییر یافته در نسخه‌ی 3.14: پشتیبانی از قالب‌های 'F' و 'D' اضافه شد.

تغییر یافته در نسخه‌ی 3.15: پشتیبانی از قالب‌های 'Zf' و 'Zd' اضافه شد. قالب‌های 'F' و 'D' منسوخ نرم هستند.

همچنین ببینید

ماژول‌های array و ctypes، و همچنین ماژول‌های شخص ثالث مانند numpy، از کدهای نوع مشابه، اما کمی متفاوت، استفاده می‌کنند.

یادداشت‌ها:

  1. کد تبدیل '?' متناظر با نوع _Bool است که از C99 در استانداردهای C تعریف شده است. در حالت استاندارد، این نوع با یک بایت بازنمایی می‌شود.

  2. هنگام تلاش برای بسته‌بندی مقداری که عدد صحیح نیست با استفاده از هر یک از کدهای تبدیل مربوط به عدد صحیح، اگر آن مقدار دارای متد __index__() باشد، آن متد برای تبدیل آرگومان به عدد صحیح پیش از بسته‌بندی فراخوانی می‌شود.

    تغییر یافته در نسخه‌ی 3.2: استفاده از متد __index__() برای غیرصحیح‌ها افزوده شد.

  3. کدهای تبدیل 'n' و 'N' فقط برای اندازه بومی (انتخاب‌شده به‌عنوان پیش‌فرض یا با نویسه ترتیب بایت '@') در دسترس هستند. برای اندازه استاندارد، می‌توانید از هر یک از قالب‌های دیگر عدد صحیح که مناسب برنامه شماست استفاده کنید.

  4. برای کدهای تبدیل 'f'، 'd' و 'e'، بازنمایی فشرده از قالب binary32، binary64 یا binary16 IEEE 754 (به‌ترتیب برای 'f'، 'd' یا 'e') استفاده می‌کند، صرف‌نظر از قالب ممیز شناور استفاده‌شده توسط سکو.

  5. نویسه‌ی قالب 'P' فقط برای ترتیب بایت بومی در دسترس است (که به‌عنوان پیش‌فرض یا با نویسه‌ی ترتیب بایت '@' انتخاب می‌شود). نویسه‌ی ترتیب بایت '=' استفاده از ترتیب کوچک‌اندیان (little-endian) یا بزرگ‌اندیان (big-endian) را بر اساس سیستم میزبان انتخاب می‌کند. ماژول struct این را به‌عنوان ترتیب بومی تفسیر نمی‌کند، بنابراین قالب 'P' در دسترس نیست.

  6. نوع binary16 «دقت نصفه» (half precision) در IEEE 754، در بازنگری سال ۲۰۰۸ استاندارد IEEE 754 معرفی شد. این نوع دارای یک بیت علامت، توان ۵ بیتی و دقت ۱۱ بیتی است (با ۱۰ بیت که به‌صورت صریح ذخیره می‌شوند) و می‌تواند اعدادی بین تقریباً 6.1e-05 و 6.5e+04 را با دقت کامل نمایش دهد. این نوع به‌طور گسترده توسط کامپایلرهای C پشتیبانی نمی‌شود: اگر کامپایلر از پیوست H استاندارد C23 پشتیبانی کند، به‌عنوان نوع _Float16 در دسترس است. در یک ماشین معمول، می‌توان از unsigned short برای ذخیره‌سازی استفاده کرد، اما نه برای عملیات ریاضی. برای اطلاعات بیشتر، صفحه‌ی ویکی‌پدیا درباره‌ی قالب ممیز شناور با دقت نصفه را ببینید.

  7. هنگام بسته‌بندی، 'x' یک بایت NUL درج می‌کند.

  8. نویسه قالب 'p' یک «رشته پاسکالی» را کدگذاری می‌کند، یعنی رشته‌ای کوتاه با طول متغیر که در تعداد ثابتی از بایت‌ها ذخیره می‌شود و با تعداد (count) مشخص می‌گردد. نخستین بایت ذخیره‌شده، طول رشته یا ۲۵۵ است، هرکدام که کوچک‌تر باشد. بایت‌های رشته در ادامه می‌آیند. اگر رشته بایت داده‌شده به pack() بیش از حد طولانی باشد (طولانی‌تر از count منهای ۱)، تنها count-1 بایت ابتدایی رشته ذخیره می‌شود. اگر رشته بایت کوتاه‌تر از count-1 باشد، با بایت‌های null پر می‌شود تا دقیقاً در مجموع count بایت استفاده شود. توجه داشته باشید که برای unpack()، نویسه قالب 'p' count بایت مصرف می‌کند، اما شیء bytes برگشتی هرگز نمی‌تواند بیش از ۲۵۵ بایت داشته باشد. هنگام pack کردن، آرگومان‌هایی از انواع bytes و bytearray پذیرفته می‌شوند.

  9. برای نویسه‌ی قالب 's'، تعداد به‌عنوان طول رشته‌ی بایتی تفسیر می‌شود، نه به‌عنوان تعداد تکرار مانند دیگر نویسه‌های قالب؛ برای مثال، '10s' به‌معنای یک رشته‌ی ۱۰ بایتی واحد است که به یک رشته‌ی بایتی پایتون یا از آن نگاشت می‌شود، در حالی که '10c' به‌معنای ۱۰ المان نویسه‌ای یک‌بایتی جداگانه (مانند cccccccccc) است که به ۱۰ شیء بایتی متفاوت پایتون یا از آن‌ها نگاشت می‌شوند. (برای نمایش ملموس این تفاوت، مثال‌ها را ببینید.) اگر تعدادی داده نشود، مقدار پیش‌فرض ۱ است. در بسته‌بندی، رشته‌ی بایتی در صورت لزوم بریده می‌شود یا با بایت‌های تهی پر می‌شود تا در قالب جای گیرد. در واگشایی، شیء bytes حاصل همیشه دقیقاً دارای تعداد بایت مشخص‌شده است. به‌عنوان یک حالت خاص، '0s' به‌معنای یک رشته‌ی بایتی خالی واحد است (در حالی که '0c' به‌معنای ۰ نویسه است). هنگام بسته‌بندی، آرگومان‌هایی از انواع bytes و bytearray پذیرفته می‌شوند.

  10. برای کدهای نوع 'Zf' و 'Zd'، بازنمایی بسته‌بندی‌شده از قالب‌های باینری ۳۲ و باینری ۶۴ استاندارد IEEE 754 برای اجزای عدد مختلط استفاده می‌کند، صرف‌نظر از قالب ممیز شناوری که پلتفرم به کار می‌برد. توجه داشته باشید که انواع مختلط به‌طور پیش‌فرض و بدون قید و شرط در دسترس هستند، با وجود اینکه انواع مختلط در زبان C یک ویژگی اختیاری محسوب می‌شوند. همان‌طور که در استاندارد C11 مشخص شده است، هر نوع مختلط با یک آرایه‌ی دو عنصری C نمایش داده می‌شود که به‌ترتیب حاوی قسمت‌های حقیقی و موهمی است. نویسه‌های قالب 'F' و 'D' (به‌ترتیب برای 'Zf' و 'Zd') برای سازگاری پشتیبانی می‌شوند.

می‌توان پیش از یک نویسه قالب، یک تعداد تکرار صحیح قرار داد. برای مثال، رشته قالب '4h' دقیقاً همان معنای 'hhhh' را دارد.

نویسه‌های فضای سفید بین قالب‌ها نادیده گرفته می‌شوند؛ هرچند یک تعداد و قالب آن نباید شامل فضای سفید باشند.

هنگام بسته‌بندی (packing) یک مقدار x با استفاده از یکی از قالب‌های عدد صحیح ('b'، 'B'، 'h'، 'H'، 'i'، 'I'، 'l'، 'L'، 'q'، 'Q')، اگر x خارج از محدوده معتبر برای آن قالب باشد، struct.error پرتاب می‌شود.

تغییر یافته در نسخه‌ی 3.1: پیش‌تر، برخی از قالب‌های عدد صحیح مقادیر خارج از محدوده را دور می‌زدند و به‌جای struct.error، DeprecationWarning ایجاد می‌کردند.

برای نویسه‌ی قالب '?'، مقدار بازگشتی یا True است یا False. هنگام بسته‌بندی، از مقدار درستی شیء آرگومان استفاده می‌شود. یکی از مقادیر ۰ یا ۱ در نمایش بولی بومی یا استاندارد بسته‌بندی می‌شود، و هر مقدار غیرصفر هنگام واگشایی True خواهد بود.

مثال‌ها¶

نکته

مثال‌های ترتیب بایت‌های بومی (native byte order) (که با پیشوند قالب '@' یا فقدان هر نویسه‌ی پیشوند مشخص می‌شوند) ممکن است با آنچه دستگاه خواننده تولید می‌کند مطابقت نداشته باشند، زیرا این امر به سکو و کامپایلر بستگی دارد.

بسته‌بندی و واگشایی اعداد صحیح در سه اندازه‌ی مختلف، با استفاده از ترتیب بایت‌بزرگ (big endian):

>>> 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'

می‌توان فیلدهای واگشایی‌شده را با انتساب آن‌ها به متغیرها یا با قرار دادن نتیجه در یک تاپل نام‌دار (named tuple) نام‌گذاری کرد:

>>> 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)

ترتیب نویسه‌های قالب ممکن است در حالت بومی بر اندازه تأثیر بگذارد، زیرا پرکننده (padding) ضمنی است. در حالت استاندارد، کاربر مسئول درج هرگونه پرکننده دلخواه است. توجه داشته باشید که در اولین فراخوانی pack در زیر، ۳ بایت NUL پس از '#' بسته‌بندی‌شده اضافه شدند تا عدد صحیح بعدی روی مرز ۴ بایتی تراز شود. در این مثال، خروجی روی یک ماشین با ترتیب بایت کم‌ارزش در ابتدا (little endian) تولید شده است:

>>> 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

قالب زیر 'llh0l' منجر به افزوده شدن دو بایت پرکننده (pad bytes) در انتها می‌شود، با فرض تراز بودن نوع long پلتفرم روی مرزهای ۴ بایتی:

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

همچنین ببینید

ماژول array

ذخیره‌سازی دودویی فشرده از داده‌های همگن.

ماژول json

کدگذار و کدگشای JSON.

ماژول pickle

سریال‌سازی شیء پایتون.

برنامه‌های کاربردی¶

دو کاربرد اصلی برای ماژول struct وجود دارند: تبادل داده بین کد پایتون و C در یک برنامه یا برنامه‌ای دیگر که با همان کامپایلر کامپایل شده است (قالب‌های بومی)، و تبادل داده بین برنامه‌هایی که از چیدمان داده‌ی مورد توافق استفاده می‌کنند (قالب‌های استاندارد). به‌طور کلی، رشته‌های قالب ساخته‌شده برای این دو حوزه با یکدیگر تفاوت دارند.

قالب‌های بومی¶

هنگام ساخت رشته‌های قالب که چیدمان‌های بومی را تقلید می‌کنند، کامپایلر و معماری ماشین ترتیب بایت‌ها و پرکننده‌گذاری را تعیین می‌کنند. در چنین مواردی، باید از نویسه‌ی قالب @ برای مشخص کردن ترتیب بایت بومی و اندازه‌های داده استفاده شود. بایت‌های پرکننده داخلی معمولاً به‌طور خودکار درج می‌شوند. ممکن است در انتهای یک رشته قالب به یک کد پیش‌ساخته با تکرار صفر نیاز باشد تا به مرز بایت صحیح گرد شود و تراز مناسب تکه‌های متوالی داده فراهم گردد.

این دو مثال ساده را در نظر بگیرید (روی یک ماشین ۶۴بیتی، کوچک‌اندیان):

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

بدون استفاده از پد (padding) اضافی، داده‌ها در انتهای دومین رشته‌ی قالب تا یک مرز ۸ بایتی پد نمی‌شوند. یک کد قالب با تکرار صفر این مشکل را حل می‌کند:

>>> calcsize('@llh0l')
24

می‌توانید از کد قالب 'x' برای مشخص کردن تعداد تکرار استفاده کنید، اما برای قالب‌های بومی بهتر است از یک قالب با تکرار صفر مانند '0l' استفاده کنید.

به‌طور پیش‌فرض، از ترتیب بایت‌ها و ترازبندی بومی استفاده می‌شود، اما بهتر است صریح باشید و از نویسه‌ی پیشوند '@' استفاده کنید.

قالب‌های استاندارد¶

هنگام تبادل داده فراتر از فرایند خود، مانند شبکه یا ذخیره‌سازی، دقیق باشید. ترتیب بایت، اندازه و ترازبندی را دقیقاً مشخص کنید. فرض نکنید که آن‌ها با ترتیب بومی یک ماشین خاص مطابقت دارند. برای مثال، ترتیب بایت شبکه بزرگ‌اندیان (big-endian) است، در حالی که بسیاری از پردازنده‌های رایج کوچک‌اندیان (little-endian) هستند. با تعریف صریح این موارد، نیازی نیست کاربر به جزئیات سکویی که کدش روی آن اجرا می‌شود توجه کند. اولین نویسه معمولاً باید < یا > (یا !) باشد. مسئولیت پر کردن (padding) بر عهده‌ی برنامه‌نویس است. نویسه‌ی قالب با تکرار صفر کار نمی‌کند. در عوض، کاربر باید به‌صراحت بایت‌های پرکننده‌ی '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

تضمین نمی‌شود که نتایج بالا (اجراشده روی یک ماشین ۶۴ بیتی) هنگام اجرا روی ماشین‌های مختلف مطابقت داشته باشند. برای مثال، مثال‌های زیر روی یک ماشین ۳۲ بیتی اجرا شده‌اند:

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

کلاس‌ها¶

ماژول struct همچنین نوع زیر را تعریف می‌کند:

class struct.Struct(format)¶

یک شیء Struct جدید برمی‌گرداند که داده‌های دودویی را بر اساس رشته قالب format می‌نویسد و می‌خواند. ایجاد یک شیء Struct به‌صورت یک‌بار و فراخوانی متدهای آن کارآمدتر از فراخوانی توابع سطح ماژول با همان قالب است، زیرا رشته قالب تنها یک‌بار کامپایل می‌شود.

نکته

نسخه‌های کامپایل‌شده‌ی آخرین رشته‌های قالب ارسال‌شده به توابع سطح ماژول در نهانگاه ذخیره می‌شوند، بنابراین برنامه‌هایی که تنها از چند رشته‌ی قالب استفاده می‌کنند، نیازی نیست نگران استفاده‌ی مجدد از یک نمونه از Struct باشند.

اشیای Struct کامپایل‌شده از متدها و ویژگی‌های زیر پشتیبانی می‌کنند:

pack(v1, v2, ...)¶

یکسان با تابع pack()، با استفاده از قالب کامپایل‌شده. (len(result) برابر با size خواهد بود.)

pack_into(buffer, offset, v1, v2, ...)¶

کاملاً مشابه تابع pack_into()، با استفاده از قالب کامپایل‌شده.

unpack(buffer)¶

دقیقاً مانند تابع unpack()، با استفاده از قالب کامپایل‌شده. اندازه‌ی بافر بر حسب بایت باید برابر با size باشد.

unpack_from(buffer, offset=0)¶

کاملاً مشابه تابع unpack_from() است و از قالب کامپایل‌شده استفاده می‌کند. اندازه بافر بر حسب بایت، از موقعیت offset به بعد، باید حداقل size باشد.

iter_unpack(buffer)¶

یکسان با تابع iter_unpack()، با استفاده از قالب کامپایل‌شده. اندازه‌ی بافر بر حسب بایت باید مضربی از size باشد.

اضافه شده در نسخه‌ی 3.4.

format¶

رشته قالب استفاده‌شده برای ساخت این شیء Struct.

تغییر یافته در نسخه‌ی 3.7: نوع رشته‌ی قالب‌بندی اکنون str است، نه bytes.

size¶

اندازه‌ی محاسبه‌شده‌ی ساختار (و بنابراین اندازه‌ی شیء bytes تولیدشده به‌وسیله‌ی متد pack()) متناظر با format.

تغییر یافته در نسخه‌ی 3.13: نمایش repr() ساختارها تغییر کرده است. اکنون به این صورت است:

>>> Struct('i')
Struct('i')
© حق نشر 2001 Python Software Foundation.
این صفحه تحت مجوز بنیاد نرم‌افزار پایتون نسخه ۲ منتشر شده است.
مثال‌ها، دستورالعمل‌ها، و سایر کدهای موجود در مستندات همچنین تحت مجوز بدون بند BSD منتشر شده‌اند.
برای اطلاعات بیشتر به تاریخچه و مجوز مراجعه کنید.

بنیاد نرم‌افزار پایتون یک شرکت غیرانتفاعی است. لطفاً کمک مالی کنید.

آخرین به‌روزرسانی در نوامبر 12, 2026 (06:19 UTC). آیا اشکالی یافتید؟
ساخته شده با Sphinx 9.1.0.
You are visitor 01402503 — GeezerVison does not store the pages you look up.
Best viewed with Netscape Navigator 4.7 or Internet Explorer 6 at 800×600. No cookies required.