文字列の変換と書式化¶
数値変換と、書式化文字列出力のための関数群。
-
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'です。rv < 0の場合、出力の変換に失敗しています。 この場合もstr[size-1]は'\0'ですが、strのほかの部分は未定義です。 エラーの正確な原因は、基盤となるプラットフォームによって異なります。
以下の関数は 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を返します。sが float に格納できないほど大きな値を表す場合 (多くのプラットフォームでは例えば"1e500")、overflow_exceptionがNULLなら適切な符号のINFINITYを返し、例外は設定しません。 それ以外の場合、overflow_exceptionは Python の例外オブジェクトを指す必要があります。 その例外を送出して-1.0を返します。 どちらの場合も、*endptrは変換した値の直後の文字を指すように設定されます。それ以外のエラーが変換中に発生した場合(例えば 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には、以下の値のうち 0 個以上をビット OR で組み合わせて指定できます。-
Py_DTSF_SIGN¶
valが負でなくても、戻り値の文字列の先頭に常に符号を付けます。
-
Py_DTSF_ADD_DOT_0¶
戻り値の文字列が整数のように見えないようにします。
-
Py_DTSF_ALT¶
「代替形式」の書式規則を適用します。 詳細は
PyOS_snprintf()の'#'指定子の説明を参照してください。
-
Py_DTSF_NO_NEG_0¶
負のゼロを正のゼロに変換します。
Added in version 3.11.
ptypeがNULLでなければ、valの種類に応じて参照先を以下の定数のいずれかに設定します。*ptypevalの種類-
Py_DTST_FINITE¶
有限の数値
-
Py_DTST_INFINITE¶
無限大
-
Py_DTST_NAN¶
非数
戻り値は変換後の文字列が格納された buffer へのポインタか、変換が失敗した場合は
NULLです。 呼び出し側は、返された文字列をPyMem_Free()を使って解放する責任があります。Added in version 3.1.
-
Py_DTSF_SIGN¶
-
int PyOS_mystricmp(const char *str1, const char *str2)¶
-
int PyOS_mystrnicmp(const char *str1, const char *str2, Py_ssize_t size)¶
- 次に属します: Stable ABI.
大文字と小文字を区別せずに文字列を比較します。 それぞれ
strcmp()とstrncmp()とほぼ同じですが、ASCII 文字の大文字と小文字の違いを無視します。文字列が等しければ
0、辞書順でstr1がstr2より前なら負の値、後なら正の値を返します。引数
str1とstr2では、NUL バイトが文字列の終わりを示します。PyOS_mystrnicmp()では、size引数が文字列の最大サイズを指定し、そのインデックスに NUL があるかのように扱います。これらの関数はロケールを使いません。
-
int PyOS_stricmp(const char *str1, const char *str2)¶
-
int PyOS_strnicmp(const char *str1, const char *str2, Py_ssize_t size)¶
大文字と小文字を区別しない文字列の比較。
Windows では、それぞれ
stricmp()とstrnicmp()の別名です。ほかのプラットフォームでは、それぞれ
PyOS_mystricmp()とPyOS_mystrnicmp()の別名です。
文字の分類と変換¶
以下のマクロは、C 標準ライブラリの ctype.h と異なり、ロケールに依存しない文字の分類と変換を行います。
引数は符号付きまたは符号なしの char でなければなりません。
-
Py_ISALNUM(c)¶
文字
cが英数字の場合に真を返します。
-
Py_ISALPHA(c)¶
文字
cが英字 (a-zまたはA-Z) の場合に真を返します。
-
Py_ISDIGIT(c)¶
文字
cが 10 進数字 (0-9) の場合に真を返します。
-
Py_ISLOWER(c)¶
文字
cが ASCII の英小文字 (a-z) の場合に真を返します。
-
Py_ISUPPER(c)¶
文字
cが ASCII の英大文字 (A-Z) の場合に真を返します。
-
Py_ISSPACE(c)¶
文字
cが空白文字 (スペース、タブ、復帰、改行、垂直タブ、フォームフィード) の場合に真を返します。
-
Py_ISXDIGIT(c)¶
文字
cが 16 進数字 (0-9、a-f、A-F) の場合に真を返します。
-
Py_TOLOWER(c)¶
文字
cに対応する小文字を返します。
-
Py_TOUPPER(c)¶
文字
cに対応する大文字を返します。
ビットマスク¶
以下の定数は、上記の文字分類マクロで使うビットマスクです。