array --- آرایه‌های کارآمد از مقادیر عددی¶

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

یادداشت‌ها:

1. بسته به پلتفرم، می‌تواند ۱۶ بیت یا ۳۲ بیت باشد.

   تغییر یافته در نسخه‌ی 3.9: array('u') اکنون از wchar_t به‌عنوان نوع C به‌جای Py_UNICODE منسوخ‌شده استفاده می‌کند. این تغییر بر رفتار آن تأثیری نمی‌گذارد، زیرا Py_UNICODE از پایتون 3.3 نام مستعاری از wchar_t است.

   منسوخ شده از نسخه‌ی 3.3, در نسخه‌ی 3.16 حذف خواهد شد: لطفاً به کد نوع (typecode) 'w' مهاجرت کنید.

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

3. نوع «نیم‌دقت» دودویی IEEE 754 با نام binary16 در بازبینی سال ۲۰۰۸ از :ieee 754 standard <استاندارد IEEE 754>_ معرفی شد. این نوع داده به‌طور گسترده توسط کامپایلرهای C پشتیبانی نمی‌شود. اگر کامپایلر از ضمیمه‌ی H استاندارد C23 پشتیبانی کند، این نوع داده به عنوان نوع _Float16 در دسترس است.

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

4. انواع مختلط (Zf و Zd) بدون قید و شرط و صرف‌نظر از پشتیبانی کامپایلر C از انواع مختلط (ضمیمه‌ی G استاندارد C11) در دسترس هستند. همان‌طور که در استاندارد C11 مشخص شده است، هر نوع داده‌ی مختلط توسط یک آرایه‌ی C دو عضوی نمایش داده می‌شود که به ترتیب شامل بخش‌های حقیقی و موهمی است.

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

نمایش واقعی مقادیر توسط معماری ماشین تعیین می‌شود (به‌طور دقیق‌تر، توسط پیاده‌سازی C). اندازه واقعی از طریق ویژگی array.itemsize قابل دسترسی است.

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

array.typecodes¶

یک تاپل با تمام کدهای نوع موجود.

تغییر یافته در نسخه‌ی 3.15: نوع داده از str به tuple تغییر یافت.

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

class array.array(typecode[, initializer])¶

آرایه‌ای جدید با آیتم‌های محدودشده با typecode که از مقدار اختیاری initializer مقداردهی اولیه می‌شود؛ این مقدار باید یک شیء bytes یا bytearray، یک رشته یونیکد، یا پیمایش‌پذیری روی عناصری از نوع مناسب باشد.

اگر یک شیء bytes یا bytearray داده شود، مقدارده اولیه به متد frombytes() آرایه‌ی جدید ارسال می‌شود؛ اگر یک رشته یونیکد داده شود، مقدارده اولیه به متد fromunicode() ارسال می‌شود؛ در غیر این صورت، پیمایش‌گر مقدارده اولیه به متد extend() ارسال می‌شود تا آیتم‌های اولیه به آرایه افزوده شوند.

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

آرایه‌ها نسبت به نوع محتوای خود عام هستند.

یک رویداد حسابرسی array.__new__ را با آرگومان‌های typecode و initializer پرتاب می‌کند.

typecode¶

نویسه‌ی کد نوع (typecode) که برای ایجاد آرایه به کار رفته است.

itemsize¶

طول یک آیتم آرایه در نمایش داخلی، بر حسب بایت.

append(value, /)¶

یک آیتم جدید با مقدار مشخص‌شده را به انتهای آرایه اضافه می‌کند.

buffer_info()¶

یک تاپل (address, length) برمی‌گرداند که نشانی حافظه فعلی و طول بر حسب عناصر بافری را که برای نگهداری محتوای آرایه استفاده می‌شود، مشخص می‌کند. اندازه‌ی بافر حافظه بر حسب بایت را می‌توان به‌صورت array.buffer_info()[1] * array.itemsize محاسبه کرد. این موضوع گاهی هنگام کار با رابط‌های سطح پایین I/O (و ذاتاً ناامن) که به نشانی‌های حافظه نیاز دارند، مفید است، مانند برخی از عملیات‌های ioctl(). اعداد برگردانده‌شده تا زمانی که آرایه وجود دارد و هیچ عملیات تغییر طولی بر آن اعمال نشود، معتبر هستند.

نکته

هنگام استفاده از اشیای آرایه از کدی که به زبان C یا C++ نوشته‌شده است (تنها راه برای استفاده مؤثر از این اطلاعات)، منطقی‌تر است از رابط بافر (buffer interface) که توسط اشیای آرایه پشتیبانی می‌شود استفاده کنید. این متد برای سازگاری با عقب‌گرد نگهداری می‌شود و باید در کد جدید از آن اجتناب شود. رابط بافر در پروتکل بافر مستند شده است.

byteswap()¶

تمام آیتم‌های آرایه را «Byteswap» کنید. این کار فقط برای مقادیری پشتیبانی می‌شود که اندازه‌ی آن‌ها ۱، ۲، ۴، ۸ یا ۱۶ بایت باشد؛ برای سایر انواع مقادیر، استثنای RuntimeError بالا می‌رود. این کار هنگام خواندن داده از پرونده‌ای که روی ماشینی با ترتیب بایت متفاوت نوشته شده است، مفید است. توجه داشته باشید که برای انواع مختلط، ترتیب اجزا (بخش حقیقی، و به دنبال آن بخش موهومی) حفظ می‌شود.

count(value, /)¶

تعداد تکرارهای value را در آرایه برمی‌گرداند.

extend(iterable, /)¶

آیتم‌هایی از iterable را به انتهای آرایه اضافه می‌کند. اگر iterable آرایه دیگری باشد، باید کد نوع دقیقاً یکسانی داشته باشد؛ در غیر این صورت، TypeError پرتاب می‌شود. اگر iterable یک آرایه نباشد، باید پیمایش‌پذیر باشد و عناصر آن باید نوع مناسب برای اضافه شدن به آرایه را داشته باشند.

frombytes(buffer, /)¶

آیتم‌ها را از شیء شبه‌بایت می‌افزاید و محتوای آن را به‌عنوان آرایه‌ای از مقادیر ماشینی تفسیر می‌کند (انگار که با استفاده از متد fromfile() از پرونده‌ای خوانده شده باشد).

اضافه شده در نسخه‌ی 3.2: fromstring() برای وضوح بیشتر به frombytes() تغییر نام پیدا کرده است.

fromfile(f, n, /)¶

n آیتم را (به‌صورت مقادیر ماشینی) از file object f بخوانید و آن‌ها را به انتهای آرایه اضافه کنید. اگر کمتر از n آیتم در دسترس باشد، EOFError پرتاب می‌شود، اما آیتم‌هایی که در دسترس بودند همچنان در آرایه درج می‌شوند.

fromlist(list, /)¶

آیتم‌های فهرست را اضافه می‌کند. این معادل for x in list: a.append(x) است، با این تفاوت که اگر خطای نوع رخ دهد، آرایه بدون تغییر باقی می‌ماند.

fromunicode(ustr, /)¶

این آرایه را با داده‌های رشته یونیکد داده‌شده گسترش می‌دهد. آرایه باید کد نوع 'u' یا 'w' داشته باشد؛ در غیر این صورت یک ValueError پرتاب می‌شود. برای افزودن داده‌های یونیکد به آرایه‌ای از نوعی دیگر، از array.frombytes(unicodestring.encode(enc)) استفاده کنید.

index(value[, start[, stop]])¶

کوچک‌ترین i را برمی‌گرداند، به‌طوری که i اندیس نخستین رخداد value در آرایه باشد. می‌توان آرگومان‌های اختیاری start و stop را برای جست‌وجوی value در زیربخشی از آرایه مشخص کرد. اگر value یافت نشد، ValueError را پرتاب می‌کند.

تغییر یافته در نسخه‌ی 3.10: پارامترهای اختیاری start و stop افزوده شدند.

insert(index, value, /)¶

یک آیتم جدید با مقدار value را پیش از موقعیت index در آرایه درج کنید. مقادیر منفی نسبت به انتهای آرایه در نظر گرفته می‌شوند.

pop(index=-1, /)¶

آیتم با اندیس i را از آرایه حذف می‌کند و آن را برمی‌گرداند. آرگومان اختیاری به‌طور پیش‌فرض -1 است، بنابراین به‌طور پیش‌فرض آخرین آیتم حذف و برگردانده می‌شود.

remove(value, /)¶

اولین رخداد value را از آرایه حذف می‌کند.

clear()¶

حذف تمام عناصر از آرایه.

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

reverse()¶

ترتیب آیتم‌های آرایه را معکوس می‌کند.

tobytes()¶

آرایه را به آرایه‌ای از مقادیر ماشین تبدیل می‌کند و بازنمایی بایتی را برمی‌گرداند (همان دنباله‌ای از بایت‌ها که توسط متد tofile() در یک پرونده نوشته می‌شود.)

اضافه شده در نسخه‌ی 3.2: tostring() برای وضوح به tobytes() تغییر نام داده شده است.

tofile(f, /)¶

تمام آیتم‌ها (به‌صورت مقادیر ماشینی) را در شیء پرونده f می‌نویسد.

tolist()¶

آرایه را به یک فهرست معمولی با همان آیتم‌ها تبدیل می‌کند.

tounicode()¶

آرایه را به یک رشته‌ی یونیکد تبدیل کنید. آرایه باید نوع 'u' یا 'w' داشته باشد؛ در غیر این صورت ValueError پرتاب می‌شود. برای به دست آوردن یک رشته‌ی یونیکد از آرایه‌ای با نوع دیگر، از array.tobytes().decode(enc) استفاده کنید.

نمایش رشته‌ای اشیای آرایه به شکل array(typecode, initializer) است. اگر آرایه خالی باشد، initializer حذف می‌شود؛ در غیر این صورت، اگر typecode برابر 'u' یا 'w' باشد، یک رشته یونیکد است و در غیر این صورت فهرستی از اعداد است. تضمین می‌شود که نمایش رشته‌ای را بتوان با استفاده از eval() به آرایه‌ای با همان نوع و مقدار تبدیل کرد، مشروط بر اینکه کلاس array با استفاده از from array import array ایمپورت شده باشد. اگر شامل مقادیر ممیز شناور متناظر باشد، متغیرهای inf و nan نیز باید تعریف شده باشند. نمونه‌ها:

array('l')
array('w', 'hello \u2641')
array('l', [1, 2, 3, 4, 5])
array('d', [1.0, 2.0, 3.14, -inf, nan])