تبدیل و قالب‌بندی رشته

توابعی برای تبدیل عدد و خروجی رشته‌ی قالب‌بندی‌شده.

int PyOS_snprintf(char *str, size_t size, const char *format, ...)

قسمتی از ABI پایدار.

حداکثر size بایت را مطابق رشته قالب format و آرگومان‌های اضافی به str خروجی بدهید. صفحه راهنمای یونیکس snprintf(3) را ببینید.

int PyOS_vsnprintf(char *str, size_t size, const char *format, va_list va)

قسمتی از ABI پایدار.

مطابق رشته قالب‌بندی format و فهرست آرگومان‌های متغیر va، حداکثر size بایت را به str خروجی می‌دهد. صفحه راهنمای man یونیکس vsnprintf(3).

PyOS_snprintf() و PyOS_vsnprintf() توابع snprintf() و vsnprintf() کتابخانه‌ی استاندارد C را پوشش می‌دهند. هدف آن‌ها تضمین رفتار سازگار در حالت‌های حاشیه‌ای (corner cases) است؛ چیزی که توابع استاندارد C انجام نمی‌دهند.

این توابع پوششی تضمین می‌کنند که str[size-1] پس از بازگشت همیشه '\0' باشد. آن‌ها هرگز بیش از size بایت (شامل '\0' انتهایی) در str نمی‌نویسند. هر دو تابع نیاز دارند که str != NULL، size > 0، format != NULL و size < INT_MAX باشد. توجه داشته باشید که این بدان معناست که معادلی برای n = snprintf(NULL, 0, ...) در C99 وجود ندارد که اندازه‌ی بافر لازم را تعیین کند.

مقدار بازگشتی (rv) برای این توابع باید به شرح زیر تفسیر شود:

• وقتی 0 <= rv < size باشد، تبدیل خروجی با موفقیت انجام شده و rv نویسه در str نوشته شده است (بدون احتساب بایت انتهایی '\0' در str[rv]).

• وقتی rv >= size باشد، تبدیل خروجی بریده شده است و برای موفقیت، بافری با rv + 1 بایت لازم بود. در این حالت، str[size-1] برابر با '\0' است.

• وقتی rv < 0 باشد، تبدیل خروجی شکست خورده و در این حالت نیز str[size-1] برابر '\0' است، اما بقیه‌ی str تعریف‌نشده است. علت دقیق خطا به پلتفرم زیرین بستگی دارد.

توابع زیر تبدیل رشته به عدد را به‌صورت مستقل از locale ارائه می‌دهند.

unsigned long PyOS_strtoul(const char *str, char **ptr, int base)

قسمتی از ABI پایدار.

بخش ابتدایی رشته در str را مطابق با base داده‌شده — که باید مقداری بین 2 و 36 (با احتساب هر دو) یا مقدار ویژه‌ی 0 باشد — به مقدار unsigned long تبدیل می‌کند.

فضای سفید ابتدایی و بزرگی و کوچکی نویسه‌ها نادیده گرفته می‌شوند. اگر base صفر باشد، به دنبال 0b، 0o یا 0x ابتدایی می‌گردد تا مشخص کند که مبنا کدام است. اگر این‌ها وجود نداشته باشند، مبنا به طور پیش‌فرض 10 خواهد بود. مبنا باید ۰ یا عددی بین ۲ و ۳۶ (با احتساب هر دو) باشد. اگر ptr غیر از NULL باشد، حاوی اشاره‌گری به انتهای پویش خواهد بود.

اگر مقدار تبدیل‌شده از محدوده‌ی نوع بازگشتی مربوطه خارج شود، خطای محدوده رخ می‌دهد (errno برابر ERANGE قرار می‌گیرد) و ULONG_MAX برگردانده می‌شود. اگر نتوان هیچ تبدیلی انجام داد، 0 برگردانده می‌شود.

همچنین صفحه‌ی راهنما (man page) یونیکس strtoul(3) را ببینید.

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

long PyOS_strtol(const char *str, char **ptr, int base)

قسمتی از ABI پایدار.

بخش ابتدایی رشته در str را بر اساس base داده‌شده، که باید عددی بین 2 و 36 (با احتساب هر دو) یا مقدار ویژه 0 باشد، به مقدار long تبدیل می‌کند.

مانند PyOS_strtoul() است، اما به‌جای آن مقدار long و در صورت سرریز LONG_MAX برمی‌گرداند.

همچنین صفحه‌ی man یونیکس strtol(3) را ببینید.

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

double PyOS_string_to_double(const char *s, char **endptr, PyObject *overflow_exception)

قسمتی از ABI پایدار.

رشته‌ی s را به double تبدیل می‌کند و در صورت شکست، یک استثنای پایتون ایجاد می‌کند. مجموعه‌ی رشته‌های پذیرفته‌شده با مجموعه‌ی رشته‌هایی که سازنده‌ی float() پایتون می‌پذیرد مطابقت دارد، به جز اینکه s نباید فضای سفید ابتدایی یا انتهایی داشته باشد. این تبدیل مستقل از locale جاری است.

اگر endptr برابر NULL باشد، کل رشته تبدیل می‌شود. اگر رشته نمایش معتبری از یک عدد ممیز شناور نباشد، استثنای ValueError برافراخته می‌شود و -1.0 برگردانده می‌شود.

اگر endptr برابر NULL نباشد، تا حد امکان رشته را تبدیل می‌کند و *endptr را طوری تنظیم می‌کند که به نخستین نویسه‌ی تبدیل‌نشده اشاره کند. اگر هیچ بخش آغازینی از رشته، نمای معتبر یک عدد ممیز شناور نباشد، *endptr را طوری تنظیم می‌کند که به ابتدای رشته اشاره کند، استثنای ValueError ایجاد می‌کند و -1.0 را برمی‌گرداند.

اگر s مقداری را بازنمایی کند که برای ذخیره‌سازی در یک عدد اعشاری بیش از حد بزرگ است (برای مثال، "1e500" در بسیاری از پلتفرم‌ها چنین رشته‌ای است)، آنگاه اگر overflow_exception برابر NULL باشد، Py_INFINITY را (با علامت مناسب) بازگردانید و هیچ استثنایی تنظیم نکنید. در غیر این صورت، overflow_exception باید به یک شیء استثنای پایتون اشاره کند؛ آن استثنا را برانگیزید و -1.0 را بازگردانید. در هر دو حالت، *endptr را طوری تنظیم کنید که به نخستین نویسه‌ی پس از مقدار تبدیل‌شده اشاره کند.

اگر خطای دیگری در حین تبدیل رخ دهد (برای مثال، خطای کمبود حافظه)، استثنای مناسب پایتون را تنظیم کرده و -1.0 را برگردانید.

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

char *PyOS_double_to_string(double val, char format_code, int precision, int flags, int *ptype)

قسمتی از ABI پایدار.

تبدیل val از نوع double به یک رشته با استفاده از format_code، precision و flags داده‌شده.

format_code باید یکی از 'e'، 'E'، 'f'، 'F'، 'g'، 'G' یا 'r' باشد. برای 'r'، precision داده‌شده باید ۰ باشد و نادیده گرفته می‌شود. کد قالب 'r' قالب استاندارد repr() را مشخص می‌کند.

flags می‌تواند صفر یا بیشتر از مقادیر زیر باشد که با عملگر OR با هم ترکیب شده‌اند:

Py_DTSF_SIGN

همیشه پیش از رشته‌ی بازگردانده‌شده یک نویسه‌ی علامت قرار دهید، حتی اگر val نامنفی باشد.

Py_DTSF_ADD_DOT_0

مطمئن شوید که رشته‌ی بازگردانده‌شده شبیه یک عدد صحیح به نظر نرسد.

Py_DTSF_ALT

قواعد قالب‌بندی «جایگزین» را اعمال می‌کند. برای جزئیات، مستندات مشخص‌کننده‌ی '#' در PyOS_snprintf() را ببینید.

Py_DTSF_NO_NEG_0

صفر منفی به صفر مثبت تبدیل می‌شود.

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

اگر ptype غیر از NULL باشد، مقداری که به آن اشاره می‌کند بسته به نوع val به یکی از ثابت‌های زیر تنظیم خواهد شد:

*ptype	نوع val
Py_DTST_FINITE	عدد متناهی
Py_DTST_INFINITE	عدد بی‌نهایت
Py_DTST_NAN	عدد نیست

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

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

int PyOS_mystricmp(const char *str1, const char *str2)

int PyOS_mystrnicmp(const char *str1, const char *str2, Py_ssize_t size)

قسمتی از ABI پایدار.

مقایسه‌ی رشته‌ها بدون حساسیت به بزرگی و کوچکی حروف. این توابع تقریباً به‌طور یکسان با strcmp() و strncmp() (به ترتیب) کار می‌کنند، با این تفاوت که بزرگی و کوچکی نویسه‌های اسکی را نادیده می‌گیرند.

اگر رشته‌ها برابر باشند 0، اگر str1 از نظر ترتیب لغت‌نگارتی قبل از str2 مرتب شود مقداری منفی، یا اگر بعد از آن مرتب شود مقداری مثبت برمی‌گرداند.

در آرگومان‌های str1 یا str2، بایت تهی پایان رشته را مشخص می‌کند. برای PyOS_mystrnicmp()، آرگومان size حداکثر اندازه‌ی رشته را تعیین می‌کند؛ گویی که بایت تهی در اندیسی که size می‌دهد وجود داشته باشد.

این توابع از locale استفاده نمی‌کنند.

int PyOS_stricmp(const char *str1, const char *str2)

int PyOS_strnicmp(const char *str1, const char *str2, Py_ssize_t size)

مقایسه رشته‌ها بدون توجه به بزرگی و کوچکی حروف.

در ویندوز، این‌ها به ترتیب نام‌های مستعارِ stricmp() و strnicmp() هستند.

در پلتفرم‌های دیگر، آن‌ها به ترتیب نام‌های مستعاری از PyOS_mystricmp() و PyOS_mystrnicmp() هستند.

طبقه‌بندی و تبدیل نویسه‌ها

ماکروهای زیر طبقه‌بندی و تبدیل نویسه‌ها را به‌صورت مستقل از locale (برخلاف کتابخانه استاندارد C ctype.h) فراهم می‌کنند. آرگومان باید یک char علامت‌دار یا بدون علامت باشد.

Py_ISALNUM(c)

اگر نویسه c یک نویسه الفبایی‌عددی باشد، مقدار درست را برمی‌گرداند.

Py_ISALPHA(c)

اگر نویسه‌ی c یک نویسه‌ی الفبایی باشد (a-z و A-Z)، مقدار true را برمی‌گرداند.

Py_ISDIGIT(c)

اگر نویسه c یک رقم ده‌دهی (0-9) باشد، مقدار true را برمی‌گرداند.

Py_ISLOWER(c)

اگر نویسه c یک حرف کوچک اسکی (a-z) باشد، مقدار true را برمی‌گرداند.

Py_ISUPPER(c)

اگر نویسه‌ی c یک حرف بزرگ اسکی (A-Z) باشد، مقدار true را برمی‌گرداند.

Py_ISSPACE(c)

در صورتی که نویسه c یک نویسه فاصله‌ساز باشد (فاصله، تب، بازگشت به ابتدای سطر، سطر جدید، تب عمودی یا تغذیه‌ی صفحه)، true برمی‌گرداند.

Py_ISXDIGIT(c)

اگر نویسه c یک رقم در مبنای شانزده باشد (0-9، a-f و A-F)، مقدار درست را برمی‌گرداند.

Py_TOLOWER(c)

بازگرداندن معادل کوچک نویسه‌ی c.

Py_TOUPPER(c)

معادل بزرگ‌نویسی نویسه‌ی c را برمی‌گرداند.