文字列の変換と書式化

数値変換と、書式化文字列出力のための関数群。

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

次に属します: Stable ABI.

書式文字列 format と追加の引数から、 size バイトを超えない文字列を str に出力します。 Unix man page の snprintf(3) を参照してください。

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

次に属します: Stable ABI.

書式文字列 format と可変長引数リスト va から、 size バイトを超えない文字列を str に出力します。 Unix man page の vsnprintf(3) を参照してください。

PyOS_snprintf() と PyOS_vsnprintf() は標準Cライブラリの snprintf() と vsnprintf() 関数をラップします。これらの関数の目的は、C標準ライブラリが保証していないコーナーケースでの動作を保証することです。

これらのラッパーは、戻る時点で str[size-1] が必ず '\0' になることを保証します。 末尾の '\0' を含めて、size バイトを超えて str に書き込むことはありません。 どちらの関数も str != NULL、size > 0、format != NULL、size < INT_MAX を必要とします。 このため、必要なバッファサイズを調べる C99 の n = snprintf(NULL, 0, ...) に相当する操作はできません。

これらの関数の戻り値 (以下では rv とします) は以下の意味を持ちます:

• 0 <= rv < size のとき、変換出力は成功して、(最後の str[rv] にある '\0' を除いて) rv 文字が str に出力された。

• rv >= size のとき、変換出力は切り詰められており、成功するためには rv + 1 バイトが必要だったことを示します。str[size-1] は '\0' です。

• When rv < 0, the output conversion failed and str[size-1] is '\0' in this case too, but the rest of str is undefined. The exact cause of the error depends on the underlying platform.

以下の関数は locale 非依存な文字列から数値への変換を行ないます。

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

次に属します: Stable ABI.

文字列 str の先頭部分を、指定された基数 base に従って unsigned long の値に変換します。 base は 2 以上 36 以下、または特別な値 0 でなければなりません。

先頭の空白と文字の大文字・小文字の違いは無視します。 base がゼロの場合、先頭の 0b、0o、0x から基数を判定します。 これらがなければ 10 を使います。 基数は 0、または 2 以上 36 以下でなければなりません。 ptr が NULL でなければ、走査が終了した位置へのポインタを格納します。

変換した値が戻り値の型の範囲外になった場合、範囲エラーとして errno を ERANGE に設定し、ULONG_MAX を返します。 変換できなかった場合は 0 を返します。

Unix マニュアルページ strtoul(3) も参照してください。

Added in version 3.2.

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

次に属します: Stable ABI.

文字列 str の先頭部分を、指定された基数 base に従って long の値に変換します。 base は 2 以上 36 以下、または特別な値 0 でなければなりません。

PyOS_strtoul() と同じですが、戻り値は long で、オーバーフロー時には LONG_MAX を返します。

Unix マニュアルページ strtol(3) も参照してください。

Added in version 3.2.

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

次に属します: Stable ABI.

文字列 s を double に変換します。失敗したときは Python の例外を発生させます。受け入れられる文字列は、 Python の float() コンストラクタが受け付ける文字列に準拠しますが、 s の先頭と末尾に空白文字があってはならないという部分が異なります。この変換は現在のロケールに依存しません。

endptr が NULL の場合、変換は文字列全体に対して行われます。文字列が正しい浮動小数点数の表現になっていない場合は -1.0 を返して ValueError を発生させます。

endptr が NULL で無い場合、文字列を可能な範囲で変換して、*endptr に最初の変換されなかった文字へのポインタを格納します。文字列の先頭に正しい浮動小数点数の表現が無かった場合、*endptr を文字列の先頭に設定して、ValueError を発生させ、-1.0 を返します。

If s represents a value that is too large to store in a float (for example, "1e500" is such a string on many platforms) then if overflow_exception is NULL return Py_HUGE_VAL (with an appropriate sign) and don't set any exception. Otherwise, overflow_exception must point to a Python exception object; raise that exception and return -1.0. In both cases, set *endptr to point to the first character after the converted value.

それ以外のエラーが変換中に発生した場合(例えば out-of-memory エラー)、適切な Python の例外を設定して -1.0 を返します。

Added in version 3.1.

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

次に属します: Stable ABI.

double val を指定された format_code, precision, flags に基づいて文字列に変換します。

format_code は 'e', 'E', 'f', 'F', 'g', 'G', 'r' のどれかでなければなりません。 'r' の場合、 precision は 0 でなければならず、無視されます。 'r' フォーマットコードは標準の repr() フォーマットを指定しています。

flags can be zero or more of the following values or-ed together:

Py_DTSF_SIGN

Always precede the returned string with a sign character, even if val is non-negative.

Py_DTSF_ADD_DOT_0

Ensure that the returned string will not look like an integer.

Py_DTSF_ALT

Apply "alternate" formatting rules. See the documentation for the PyOS_snprintf() '#' specifier for details.

Py_DTSF_NO_NEG_0

Negative zero is converted to positive zero.

Added in version 3.11.

If ptype is non-NULL, then the value it points to will be set to one of the following constants depending on the type of val:

*ptype	type of val
Py_DTST_FINITE	finite number
Py_DTST_INFINITE	infinite number
Py_DTST_NAN	not a number

戻り値は変換後の文字列が格納された buffer へのポインタか、変換が失敗した場合は NULL です。 呼び出し側は、返された文字列を PyMem_Free() を使って解放する責任があります。

Added in version 3.1.

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

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

次に属します: Stable ABI.

Case insensitive comparison of strings. These functions work almost identically to strcmp() and strncmp() (respectively), except that they ignore the case of ASCII characters.

Return 0 if the strings are equal, a negative value if str1 sorts lexicographically before str2, or a positive value if it sorts after.

In the str1 or str2 arguments, a NUL byte marks the end of the string. For PyOS_mystrnicmp(), the size argument gives the maximum size of the string, as if NUL was present at the index given by size.

These functions do not use the locale.

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

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

Case insensitive comparison of strings.

On Windows, these are aliases of stricmp() and strnicmp(), respectively.

On other platforms, they are aliases of PyOS_mystricmp() and PyOS_mystrnicmp(), respectively.

Character classification and conversion

The following macros provide locale-independent (unlike the C standard library ctype.h) character classification and conversion. The argument must be a signed or unsigned char.

Py_ISALNUM(c)

Return true if the character c is an alphanumeric character.

Py_ISALPHA(c)

Return true if the character c is an alphabetic character (a-z and A-Z).

Py_ISDIGIT(c)

Return true if the character c is a decimal digit (0-9).

Py_ISLOWER(c)

Return true if the character c is a lowercase ASCII letter (a-z).

Py_ISUPPER(c)

Return true if the character c is an uppercase ASCII letter (A-Z).

Py_ISSPACE(c)

Return true if the character c is a whitespace character (space, tab, carriage return, newline, vertical tab, or form feed).

Py_ISXDIGIT(c)

Return true if the character c is a hexadecimal digit (0-9, a-f, and A-F).

Py_TOLOWER(c)

Return the lowercase equivalent of the character c.

Py_TOUPPER(c)

Return the uppercase equivalent of the character c.