Unicodeオブジェクトとコーデック—Pythonドキュメント

提供:Dev Guides
< PythonPython/docs/3.9/c-api/unicode
移動先:案内検索

Unicodeオブジェクトとコーデック

Unicodeオブジェクト

Python3.3での PEP 393 の実装以降、Unicodeオブジェクトは、メモリ効率を維持しながらUnicode文字の全範囲を処理できるようにするために、内部でさまざまな表現を使用します。 すべてのコードポイントが128、256、または65536未満である文字列には特別な場合があります。 それ以外の場合、コードポイントは1114112(Unicodeの全範囲)未満である必要があります。

Py_UNICODE * およびUTF-8表現はオンデマンドで作成され、Unicodeオブジェクトにキャッシュされます。 Py_UNICODE * 表現は非推奨であり、非効率的です。

古いAPIと新しいAPIの間の移行により、Unicodeオブジェクトは、作成方法に応じて、内部的に2つの状態になる可能性があります。

  • 「正規の」Unicodeオブジェクトは、非推奨ではないUnicodeAPIによって作成されたすべてのオブジェクトです。 それらは、実装によって許可された最も効率的な表現を使用します。
  • 「レガシー」Unicodeオブジェクトは、非推奨のAPIの1つ(通常は PyUnicode_FromUnicode())を介して作成されており、 Py_UNICODE * 表現のみを備えています。 他のAPIを呼び出す前に、それらに対して PyUnicode_READY()を呼び出す必要があります。

ノート

「レガシー」Unicodeオブジェクトは、非推奨のAPIを使用してPython3.12で削除されます。 それ以降、すべてのUnicodeオブジェクトは「正規」になります。 詳細については、 PEP 623 を参照してください。


Unicodeタイプ

これらは、PythonでのUnicode実装に使用される基本的なUnicodeオブジェクトタイプです。

type Py_UCS4

type Py_UCS2

type Py_UCS1

これらの型は、それぞれ32ビット、16ビット、および8ビットの文字を含むのに十分な幅の符号なし整数型のtypedefです。 単一のUnicode文字を扱う場合は、 Py_UCS4 を使用してください。

バージョン3.3の新機能。

type Py_UNICODE

これはwchar_tのtypedefであり、プラットフォームに応じて16ビットタイプまたは32ビットタイプです。

バージョン3.3で変更:以前のバージョンでは、ビルド時にPythonの「ナロー」または「ワイド」Unicodeバージョンを選択したかどうかに応じて、これは16ビットタイプまたは32ビットタイプでした。

type PyASCIIObject

type PyCompactUnicodeObject

type PyUnicodeObject

PyObject のこれらのサブタイプは、PythonUnicodeオブジェクトを表します。 ほとんどすべての場合、Unicodeオブジェクトを処理するすべてのAPI関数は PyObject ポインターを受け取り、返すため、直接使用しないでください。

バージョン3.3の新機能。

PyTypeObject PyUnicode_Type
PyTypeObject のこのインスタンスは、PythonUnicode型を表します。 strとしてPythonコードに公開されます。

次のAPIは実際にはCマクロであり、高速チェックを実行したり、Unicodeオブジェクトの内部読み取り専用データにアクセスしたりするために使用できます。

int PyUnicode_Check(PyObject *o)
オブジェクト o がUnicodeオブジェクトまたはUnicodeサブタイプのインスタンスである場合、trueを返します。 この関数は常に成功します。
int PyUnicode_CheckExact(PyObject *o)
オブジェクト o がUnicodeオブジェクトであるが、サブタイプのインスタンスではない場合はtrueを返します。 この関数は常に成功します。
int PyUnicode_READY(PyObject *o)

文字列オブジェクト o が「正規」表現であることを確認してください。 これは、以下で説明するアクセスマクロを使用する前に必要です。

成功した場合は0を返し、失敗した場合は例外セットを除いて-1を返します。これは、特にメモリ割り当てが失敗した場合に発生します。

バージョン3.3の新機能。

Py_ssize_t PyUnicode_GET_LENGTH(PyObject *o)

Unicode文字列の長さをコードポイントで返します。 o は、「正規」表現のUnicodeオブジェクトである必要があります(チェックされていません)。

バージョン3.3の新機能。

Py_UCS1 *PyUnicode_1BYTE_DATA(PyObject *o)

Py_UCS2 *PyUnicode_2BYTE_DATA(PyObject *o)

Py_UCS4 *PyUnicode_4BYTE_DATA(PyObject *o)

文字に直接アクセスするために、UCS1、UCS2、またはUCS4整数型にキャストされた正規表現へのポインタを返します。 正規表現の文字サイズが正しい場合、チェックは実行されません。 PyUnicode_KIND()を使用して、適切なマクロを選択します。 これにアクセスする前に、 PyUnicode_READY()が呼び出されていることを確認してください。

バージョン3.3の新機能。

PyUnicode_WCHAR_KIND

PyUnicode_1BYTE_KIND

PyUnicode_2BYTE_KIND

PyUnicode_4BYTE_KIND

PyUnicode_KIND()マクロの戻り値。

バージョン3.3の新機能。

unsigned int PyUnicode_KIND(PyObject *o)

このUnicodeオブジェクトがデータを格納するために使用する文字あたりのバイト数を示すPyUnicode種類の定数(上記を参照)の1つを返します。 o は、「正規」表現のUnicodeオブジェクトである必要があります(チェックされていません)。

バージョン3.3の新機能。

void *PyUnicode_DATA(PyObject *o)

生のUnicodeバッファへのvoidポインタを返します。 o は、「正規」表現のUnicodeオブジェクトである必要があります(チェックされていません)。

バージョン3.3の新機能。

void PyUnicode_WRITE(int kind, void *data, Py_ssize_t index, Py_UCS4 value)

正規表現 data に書き込みます( PyUnicode_DATA()で取得)。 このマクロは健全性チェックを行わず、ループでの使用を目的としています。 呼び出し元は、他のマクロ呼び出しから取得した kind 値と data ポインターをキャッシュする必要があります。 index は文字列内のインデックス(0から始まります)であり、 value はその場所に書き込む必要のある新しいコードポイント値です。

バージョン3.3の新機能。

Py_UCS4 PyUnicode_READ(int kind, void *data, Py_ssize_t index)

正規表現 dataPyUnicode_DATA()で取得)からコードポイントを読み取ります。 チェックやレディコールは実行されません。

バージョン3.3の新機能。

Py_UCS4 PyUnicode_READ_CHAR(PyObject *o, Py_ssize_t index)

Unicodeオブジェクト o から文字を読み取ります。これは「正規」表現である必要があります。 これは、複数の連続した読み取りを行う場合、 PyUnicode_READ()よりも効率的ではありません。

バージョン3.3の新機能。

PyUnicode_MAX_CHAR_VALUE(o)

o に基づいて別の文字列を作成するのに適した最大コードポイントを返します。これは、「正規」表現である必要があります。 これは常に概算ですが、文字列を反復処理するよりも効率的です。

バージョン3.3の新機能。

Py_ssize_t PyUnicode_GET_SIZE(PyObject *o)
非推奨の Py_UNICODE 表現のサイズをコード単位で返します(これには、2単位の代理ペアが含まれます)。 o はUnicodeオブジェクトである必要があります(チェックされていません)。
Py_ssize_t PyUnicode_GET_DATA_SIZE(PyObject *o)
非推奨の Py_UNICODE 表現のサイズをバイト単位で返します。 o はUnicodeオブジェクトである必要があります(チェックされていません)。
Py_UNICODE *PyUnicode_AS_UNICODE(PyObject *o)

const char *PyUnicode_AS_DATA(PyObject *o)

オブジェクトの Py_UNICODE 表現へのポインタを返します。 返されるバッファは、常に余分なnullコードポイントで終了します。 また、埋め込まれたnullコードポイントが含まれている場合があります。これにより、ほとんどのC関数で使用されるときに文字列が切り捨てられます。 AS_DATAフォームは、ポインターを const char * にキャストします。 o 引数はUnicodeオブジェクトである必要があります(チェックされていません)。

バージョン3.3で変更:このマクロは非効率になりました–多くの場合 Py_UNICODE 表現が存在せず、作成する必要があるため–失敗する可能性があります(NULLを返す)例外セットを除く)。 新しいPyUnicode_nBYTE_DATA()マクロを使用するようにコードを移植するか、 PyUnicode_WRITE()または PyUnicode_READ()を使用してみてください。

int PyUnicode_IsIdentifier(PyObject *o)

文字列が言語定義のセクション識別子とキーワードに従って有効な識別子である場合は、1を返します。 それ以外の場合は0を返します。

バージョン3.9で変更:文字列の準備ができていない場合、関数は Py_FatalError()を呼び出さなくなりました。


Unicode文字プロパティ

Unicodeは、さまざまな文字プロパティを提供します。 最も頻繁に必要とされるものは、Python構成に応じてC関数にマップされるこれらのマクロを介して利用できます。

int Py_UNICODE_ISSPACE(Py_UNICODE ch)
ch が空白文字であるかどうかに応じて、1または0を返します。
int Py_UNICODE_ISLOWER(Py_UNICODE ch)
ch が小文字であるかどうかに応じて、1または0を返します。
int Py_UNICODE_ISUPPER(Py_UNICODE ch)
ch が大文字であるかどうかに応じて、1または0を返します。
int Py_UNICODE_ISTITLE(Py_UNICODE ch)
ch がタイトルケース文字であるかどうかに応じて、1または0を返します。
int Py_UNICODE_ISLINEBREAK(Py_UNICODE ch)
ch が改行文字であるかどうかに応じて、1または0を返します。
int Py_UNICODE_ISDECIMAL(Py_UNICODE ch)
ch が10進文字であるかどうかに応じて、1または0を返します。
int Py_UNICODE_ISDIGIT(Py_UNICODE ch)
ch が数字であるかどうかに応じて、1または0を返します。
int Py_UNICODE_ISNUMERIC(Py_UNICODE ch)
ch が数字であるかどうかに応じて、1または0を返します。
int Py_UNICODE_ISALPHA(Py_UNICODE ch)
ch が英字であるかどうかに応じて、1または0を返します。
int Py_UNICODE_ISALNUM(Py_UNICODE ch)
ch が英数字であるかどうかに応じて、1または0を返します。
int Py_UNICODE_ISPRINTABLE(Py_UNICODE ch)
ch が印刷可能な文字であるかどうかに応じて、1または0を返します。 印刷不可能な文字とは、Unicode文字データベースで「その他」または「区切り文字」として定義されている文字です。ただし、印刷可能と見なされるASCIIスペース(0x20)は除きます。 (このコンテキストでの印刷可能な文字は、 repr()が文字列で呼び出されたときにエスケープしてはならない文字であることに注意してください。 sys.stdout または sys.stderr に書き込まれた文字列の処理には関係ありません。)

これらのAPIは、高速の直接文字変換に使用できます。

Py_UNICODE Py_UNICODE_TOLOWER(Py_UNICODE ch)

小文字に変換された文字 ch を返します。

バージョン3.3以降非推奨:この関数は単純なケースマッピングを使用します。

Py_UNICODE Py_UNICODE_TOUPPER(Py_UNICODE ch)

大文字に変換された文字 ch を返します。

バージョン3.3以降非推奨:この関数は単純なケースマッピングを使用します。

Py_UNICODE Py_UNICODE_TOTITLE(Py_UNICODE ch)

タイトルケースに変換された文字 ch を返します。

バージョン3.3以降非推奨:この関数は単純なケースマッピングを使用します。

int Py_UNICODE_TODECIMAL(Py_UNICODE ch)
10進正の整数に変換された文字 ch を返します。 これが不可能な場合は、-1を返します。 このマクロは例外を発生させません。
int Py_UNICODE_TODIGIT(Py_UNICODE ch)
1桁の整数に変換された文字 ch を返します。 これが不可能な場合は、-1を返します。 このマクロは例外を発生させません。
double Py_UNICODE_TONUMERIC(Py_UNICODE ch)
ダブルに変換された文字 ch を返します。 これが不可能な場合は、-1.0を返します。 このマクロは例外を発生させません。

これらのAPIは、サロゲートを操作するために使用できます。

Py_UNICODE_IS_SURROGATE(ch)
ch がサロゲート(0xD800 <= ch <= 0xDFFF)であるかどうかを確認します。
Py_UNICODE_IS_HIGH_SURROGATE(ch)
ch が上位サロゲート(0xD800 <= ch <= 0xDBFF)であるかどうかを確認します。
Py_UNICODE_IS_LOW_SURROGATE(ch)
ch がローサロゲート(0xDC00 <= ch <= 0xDFFF)であるかどうかを確認します。
Py_UNICODE_JOIN_SURROGATES(high, low)
2つの代理文字を結合し、単一のPy_UCS4値を返します。 highlow は、それぞれサロゲートペアの先頭と末尾のサロゲートです。


Unicode文字列の作成とアクセス

Unicodeオブジェクトを作成し、それらの基本的なシーケンスプロパティにアクセスするには、次のAPIを使用します。

PyObject *PyUnicode_New(Py_ssize_t size, Py_UCS4 maxchar)

新しいUnicodeオブジェクトを作成します。 maxchar は、文字列に配置される真の最大コードポイントである必要があります。 概算として、127、255、65535、1114111のシーケンスで最も近い値に切り上げることができます。

これは、新しいUnicodeオブジェクトを割り当てるための推奨される方法です。 この関数を使用して作成されたオブジェクトはサイズ変更できません。

バージョン3.3の新機能。

PyObject *PyUnicode_FromKindAndData(int kind, const void *buffer, Py_ssize_t size)

指定された kind を使用して新しいUnicodeオブジェクトを作成します( PyUnicode_KIND()によって返される PyUnicode_1BYTE_KIND などの可能な値)。 buffer は、種類で指定されているように、1文字あたり1、2、または4バイトの size 単位の配列を指している必要があります。

バージョン3.3の新機能。

PyObject *PyUnicode_FromStringAndSize(const char *u, Py_ssize_t size)

charバッファ u からUnicodeオブジェクトを作成します。 バイトはUTF-8でエンコードされていると解釈されます。 バッファが新しいオブジェクトにコピーされます。 バッファがNULLでない場合、戻り値は共有オブジェクトである可能性があります。 データの変更は許可されていません。

uNULLの場合、この関数は PyUnicode_FromUnicode()のように動作し、バッファーはNULLに設定されます。 この使用法は PyUnicode_New()を優先して非推奨になり、Python3.12で削除される予定です。

PyObject *PyUnicode_FromString(const char *u)
UTF-8でエンコードされたnullで終了するcharバッファ u からUnicodeオブジェクトを作成します。
PyObject *PyUnicode_FromFormat(const char *format, ...)

C printf()スタイルの format 文字列と可変数の引数を取り、結果のPython Unicode文字列のサイズを計算し、値がフォーマットされた文字列を返します。 可変引数はCタイプである必要があり、 format ASCIIエンコード文字列のフォーマット文字に正確に対応している必要があります。 次のフォーマット文字を使用できます。

文字のフォーマット

タイプ

コメント

%%

該当なし

The literal % character.

%c

int

Cintとして表される単一の文字。

%d

int

printf("%d")と同等です。 1

%u

unsigned int

printf("%u")と同等です。 1

%ld

長いです

printf("%ld")と同等です。 1

%li

長いです

printf("%li")と同等です。 1

%lu

unsigned long

printf("%lu")と同等です。 1

%lld

長い長い

printf("%lld")と同等です。 1

%lli

長い長い

printf("%lli")と同等です。 1

%llu

unsigned long long

printf("%llu")と同等です。 1

%zd

Py_ssize_t

printf("%zd")と同等です。 1

%zi

Py_ssize_t

printf("%zi")と同等です。 1

%zu

size_t

printf("%zu")と同等です。 1

%i

int

printf("%i")と同等です。 1

%x

int

printf("%x")と同等です。 1

%s

const char *

ヌル終了C文字配列。

%p

const void *

Cポインターの16進表現。 プラットフォームのprintfが何を生成するかに関係なく、リテラル0xで開始することが保証されていることを除いて、printf("%p")とほぼ同等です。

%A

PyObject *

ascii()を呼び出した結果。

%U

PyObject *

Unicodeオブジェクト。

%V

PyObject *、const char *

Unicodeオブジェクト(NULLの場合があります)および2番目のパラメーターとしてのヌル終了C文字配列(最初のパラメーターがNULLの場合に使用されます)。

%S

PyObject *

PyObject_Str()を呼び出した結果。

%R

PyObject *

PyObject_Repr()を呼び出した結果。

認識されないフォーマット文字により、フォーマット文字列の残りのすべてがそのまま結果文字列にコピーされ、余分な引数は破棄されます。

ノート

幅フォーマッタの単位は、バイトではなく文字数です。 精度フォーマッタの単位は、"%s"および"%V"のバイト数(PyObject*引数がNULLの場合)、および"%A""%U""%S""%R"、および"%V"PyObject*引数がNULLでない場合) 。

1123456 、[ X67X] 7 、 8910111213

整数指定子(d、u、ld、li、lu、lld、lli、llu、zd、zi、zu、i、x)の場合:0変換フラグは、精度が指定されている場合でも有効です。

バージョン3.2で変更: "%lld"および"%llu"のサポートが追加されました。

バージョン3.3で変更: "%li""%lli"、および"%zi"のサポートが追加されました。

バージョン3.4で変更: "%s""%A""%U""%V""%S"の幅と精度のフォーマッターをサポート]、"%R"を追加しました。

PyObject *PyUnicode_FromFormatV(const char *format, va_list vargs)
PyUnicode_FromFormat()と同じですが、2つの引数を取る点が異なります。
PyObject *PyUnicode_FromEncodedObject(PyObject *obj, const char *encoding, const char *errors)

エンコードされたオブジェクト obj をUnicodeオブジェクトにデコードします。

bytesbytearray およびその他の bytes-likeオブジェクトは、指定された encoding に従って、で定義されたエラー処理を使用してデコードされます。エラー。 どちらもNULLにして、インターフェイスにデフォルト値を使用させることができます(詳細については、組み込みコーデックを参照してください)。

Unicodeオブジェクトを含む他のすべてのオブジェクトにより、 TypeError が設定されます。

エラーが発生した場合、APIはNULLを返します。 呼び出し元は、返されたオブジェクトをdecrefする責任があります。

Py_ssize_t PyUnicode_GetLength(PyObject *unicode)

Unicodeオブジェクトの長さをコードポイントで返します。

バージョン3.3の新機能。

Py_ssize_t PyUnicode_CopyCharacters(PyObject *to, Py_ssize_t to_start, PyObject *from, Py_ssize_t from_start, Py_ssize_t how_many)

あるUnicodeオブジェクトから別のUnicodeオブジェクトに文字をコピーします。 この関数は、必要に応じて文字変換を実行し、可能であればmemcpy()にフォールバックします。 -1を返し、エラー時に例外を設定します。それ以外の場合は、コピーされた文字数を返します。

バージョン3.3の新機能。

Py_ssize_t PyUnicode_Fill(PyObject *unicode, Py_ssize_t start, Py_ssize_t length, Py_UCS4 fill_char)

文字列に文字を入力します。 fill_charunicode[start:start+length]に書き込みます。

fill_char が文字列の最大文字よりも大きい場合、または文字列に複数の参照がある場合は失敗します。

書き込まれた文字数を返すか、-1を返し、エラー時に例外を発生させます。

バージョン3.3の新機能。

int PyUnicode_WriteChar(PyObject *unicode, Py_ssize_t index, Py_UCS4 character)

文字列に文字を書き込みます。 文字列は、 PyUnicode_New()を介して作成されている必要があります。 Unicode文字列は不変であると想定されているため、文字列を共有したり、ハッシュ化したりしてはなりません。

この関数は、 unicode がUnicodeオブジェクトであること、インデックスが範囲外ではないこと、およびオブジェクトを安全に変更できること(つまり、 参照カウントが1であること)。

バージョン3.3の新機能。

Py_UCS4 PyUnicode_ReadChar(PyObject *unicode, Py_ssize_t index)

文字列から文字を読み取ります。 この関数は、マクロバージョン PyUnicode_READ_CHAR()とは対照的に、 unicode がUnicodeオブジェクトであり、インデックスが範囲外ではないことを確認します。

バージョン3.3の新機能。

PyObject *PyUnicode_Substring(PyObject *str, Py_ssize_t start, Py_ssize_t end)

文字インデックス start (含まれる)から文字インデックス end (除外される)までの str のサブストリングを返します。 負のインデックスはサポートされていません。

バージョン3.3の新機能。

Py_UCS4 *PyUnicode_AsUCS4(PyObject *u, Py_UCS4 *buffer, Py_ssize_t buflen, int copy_null)

copy_null が設定されている場合は、文字列 u をヌル文字を含むUCS4バッファーにコピーします。 NULLを返し、エラー時に例外を設定します(特に、 buflenu の長さよりも小さい場合は SystemError )。 buffer は、成功すると返されます。

バージョン3.3の新機能。

Py_UCS4 *PyUnicode_AsUCS4Copy(PyObject *u)

文字列 u を、 PyMem_Malloc()を使用して割り当てられた新しいUCS4バッファーにコピーします。 これが失敗した場合、[X14X] MemoryError が設定されたNULLが返されます。 返されるバッファには、常に追加のnullコードポイントが追加されます。

バージョン3.3の新機能。


非推奨のPy_UNICODEAPI

これらのAPI関数は、 PEP 393 の実装で非推奨になりました。 拡張モジュールはPython3.xで削除されないため、引き続き使用できますが、拡張モジュールを使用するとパフォーマンスとメモリが低下する可能性があることに注意する必要があります。

PyObject *PyUnicode_FromUnicode(const Py_UNICODE *u, Py_ssize_t size)

指定されたサイズのPy_UNICODEバッファ u からUnicodeオブジェクトを作成します。 uNULLである可能性があり、これにより内容が未定義になります。 必要なデータを入力するのはユーザーの責任です。 バッファが新しいオブジェクトにコピーされます。

バッファがNULLでない場合、戻り値は共有オブジェクトである可能性があります。 したがって、結果のUnicodeオブジェクトの変更は、 uNULLの場合にのみ許可されます。

バッファがNULLの場合、 PyUnicode_KIND()などのアクセスマクロを使用する前に、文字列の内容が入力されたら PyUnicode_READY()を呼び出す必要があります。

Py_UNICODE *PyUnicode_AsUnicode(PyObject *unicode)
Unicodeオブジェクトの内部 Py_UNICODE バッファーへの読み取り専用ポインターを返すか、エラーの場合はNULLを返します。 これにより、オブジェクトがまだ使用できない場合、オブジェクトの Py_UNICODE * 表現が作成されます。 バッファは常に余分なヌルコードポイントで終了します。 結果の Py_UNICODE 文字列には、埋め込まれたnullコードポイントも含まれる可能性があることに注意してください。これにより、ほとんどのC関数で使用されるときに文字列が切り捨てられます。
PyObject *PyUnicode_TransformDecimalToASCII(Py_UNICODE *s, Py_ssize_t size)
指定されたサイズPy_UNICODE バッファー内のすべての10進数を、10進数値に応じて0〜9のASCII数字に置き換えて、Unicodeオブジェクトを作成します。 例外が発生した場合はNULLを返します。
Py_UNICODE *PyUnicode_AsUnicodeAndSize(PyObject *unicode, Py_ssize_t *size)

PyUnicode_AsUnicode()と同様ですが、 Py_UNICODE()配列の長さ(余分なヌルターミネータを除く)を size に保存します。 結果の Py_UNICODE * 文字列には、埋め込まれたnullコードポイントが含まれている可能性があることに注意してください。これにより、ほとんどのC関数で使用されるときに文字列が切り捨てられます。

バージョン3.3の新機能。

Py_UNICODE *PyUnicode_AsUnicodeCopy(PyObject *unicode)

nullコードポイントで終わるUnicode文字列のコピーを作成します。 NULLを返し、メモリ割り当ての失敗時に MemoryError 例外を発生させます。それ以外の場合は、新しく割り当てられたバッファを返します( PyMem_Free()を使用してバッファを解放します)。 結果の Py_UNICODE * 文字列には、埋め込まれたnullコードポイントが含まれている可能性があることに注意してください。これにより、ほとんどのC関数で使用されるときに文字列が切り捨てられます。

バージョン3.2の新機能。

PyUnicode_AsUCS4Copy()または同様の新しいAPIを使用するように移行してください。

Py_ssize_t PyUnicode_GetSize(PyObject *unicode)
非推奨の Py_UNICODE 表現のサイズをコード単位で返します(これには、2単位の代理ペアが含まれます)。
PyObject *PyUnicode_FromObject(PyObject *obj)

必要に応じて、Unicodeサブタイプのインスタンスを新しい真のUnicodeオブジェクトにコピーします。 obj がすでに真のUnicodeオブジェクト(サブタイプではない)である場合は、refcountをインクリメントして参照を返します。

Unicodeまたはそのサブタイプ以外のオブジェクトは、 TypeError を引き起こします。


ロケールエンコーディング

現在のロケールエンコーディングを使用して、オペレーティングシステムからテキストをデコードできます。

PyObject *PyUnicode_DecodeLocaleAndSize(const char *str, Py_ssize_t len, const char *errors)

AndroidおよびVxWorksのUTF-8から、または他のプラットフォームの現在のロケールエンコーディングから文字列をデコードします。 サポートされているエラーハンドラーは、"strict"および"surrogateescape" PEP 383 )です。 エラーNULLの場合、デコーダーは"strict"エラーハンドラーを使用します。 str はヌル文字で終了する必要がありますが、埋め込まれたヌル文字を含めることはできません。

PyUnicode_DecodeFSDefaultAndSize()を使用して、Py_FileSystemDefaultEncoding(Pythonの起動時に読み取られるロケールエンコーディング)から文字列をデコードします。

この関数は、PythonUTF-8モードを無視します。

も参照してください

Py_DecodeLocale()関数。

バージョン3.3の新機能。

バージョン3.7で変更:この関数は、Androidを除き、surrogateescapeエラーハンドラーの現在のロケールエンコーディングも使用するようになりました。 以前は、 Py_DecodeLocale()surrogateescapeに使用され、現在のロケールエンコーディングがstrictに使用されていました。

PyObject *PyUnicode_DecodeLocale(const char *str, const char *errors)

PyUnicode_DecodeLocaleAndSize()に似ていますが、strlen()を使用して文字列の長さを計算します。

バージョン3.3の新機能。

PyObject *PyUnicode_EncodeLocale(PyObject *unicode, const char *errors)

UnicodeオブジェクトをAndroidおよびVxWorksのUTF-8にエンコードするか、他のプラットフォームの現在のロケールエンコードにエンコードします。 サポートされているエラーハンドラーは、"strict"および"surrogateescape" PEP 383 )です。 エラーNULLの場合、エンコーダーは"strict"エラーハンドラーを使用します。 bytes オブジェクトを返します。 unicode にヌル文字を埋め込むことはできません。

PyUnicode_EncodeFSDefault()を使用して、文字列をPy_FileSystemDefaultEncoding(Pythonの起動時に読み取られるロケールエンコード)にエンコードします。

この関数は、PythonUTF-8モードを無視します。

も参照してください

Py_EncodeLocale()関数。

バージョン3.3の新機能。

バージョン3.7で変更:この関数は、Androidを除き、surrogateescapeエラーハンドラーの現在のロケールエンコーディングも使用するようになりました。 以前は、 Py_EncodeLocale()surrogateescapeに使用され、現在のロケールエンコーディングがstrictに使用されていました。


ファイルシステムエンコーディング

ファイル名やその他の環境文字列をエンコードおよびデコードするには、Py_FileSystemDefaultEncodingをエンコードとして使用し、Py_FileSystemDefaultEncodeErrorsをエラーハンドラーとして使用する必要があります( PEP 383 および PEP 529 )。 引数の解析中にファイル名を bytes にエンコードするには、"O&"コンバーターを使用し、変換関数として PyUnicode_FSConverter()を渡す必要があります。

int PyUnicode_FSConverter(PyObject *obj, void *result)

ParseTupleコンバーター: str オブジェクトをエンコードします–直接または os.PathLike インターフェースを介して– PyUnicode_EncodeFSDefault()を使用してバイトにエンコードします。 bytes オブジェクトはそのまま出力されます。 result PyBytesObject * である必要があり、使用されなくなったときに解放する必要があります。

バージョン3.1の新機能。

バージョン3.6で変更: パスのようなオブジェクトを受け入れます。

引数の解析中にファイル名を str にデコードするには、"O&"コンバーターを使用し、変換関数として PyUnicode_FSDecoder()を渡す必要があります。

int PyUnicode_FSDecoder(PyObject *obj, void *result)

ParseTupleコンバーター: bytes オブジェクト( os.PathLike インターフェイスを介して直接または間接的に取得)を PyUnicode_DecodeFSDefaultAndSize()を使用して str にデコードします。 str オブジェクトはそのまま出力されます。 result PyUnicodeObject * である必要があり、使用されなくなったときに解放する必要があります。

バージョン3.2の新機能。

バージョン3.6で変更: パスのようなオブジェクトを受け入れます。

PyObject *PyUnicode_DecodeFSDefaultAndSize(const char *s, Py_ssize_t size)

Py_FileSystemDefaultEncodingPy_FileSystemDefaultEncodeErrorsエラーハンドラーを使用して文字列をデコードします。

Py_FileSystemDefaultEncodingが設定されていない場合は、ロケールエンコーディングにフォールバックします。

Py_FileSystemDefaultEncodingは、起動時にロケールエンコーディングから初期化され、後で変更することはできません。 現在のロケールエンコーディングから文字列をデコードする必要がある場合は、 PyUnicode_DecodeLocaleAndSize()を使用してください。

も参照してください

Py_DecodeLocale()関数。

バージョン3.6で変更: Py_FileSystemDefaultEncodeErrorsエラーハンドラーを使用します。

PyObject *PyUnicode_DecodeFSDefault(const char *s)

Py_FileSystemDefaultEncodingおよびPy_FileSystemDefaultEncodeErrorsエラーハンドラーを使用して、nullで終了する文字列をデコードします。

Py_FileSystemDefaultEncodingが設定されていない場合は、ロケールエンコーディングにフォールバックします。

文字列の長さがわかっている場合は、 PyUnicode_DecodeFSDefaultAndSize()を使用してください。

バージョン3.6で変更: Py_FileSystemDefaultEncodeErrorsエラーハンドラーを使用します。

PyObject *PyUnicode_EncodeFSDefault(PyObject *unicode)

Py_FileSystemDefaultEncodeErrorsエラーハンドラーを使用してUnicodeオブジェクトをPy_FileSystemDefaultEncodingにエンコードし、バイトを返します。 結果の bytes オブジェクトにはnullバイトが含まれる場合があることに注意してください。

Py_FileSystemDefaultEncodingが設定されていない場合は、ロケールエンコーディングにフォールバックします。

Py_FileSystemDefaultEncodingは、起動時にロケールエンコーディングから初期化され、後で変更することはできません。 文字列を現在のロケールエンコーディングにエンコードする必要がある場合は、 PyUnicode_EncodeLocale()を使用してください。

も参照してください

Py_EncodeLocale()関数。

バージョン3.2の新機能。

バージョン3.6で変更: Py_FileSystemDefaultEncodeErrorsエラーハンドラーを使用します。


wchar_tサポート

wchar_tそれをサポートするプラットフォームのサポート:

PyObject *PyUnicode_FromWideChar(const wchar_t *w, Py_ssize_t size)
指定されたサイズwchar_tバッファ w からUnicodeオブジェクトを作成します。 -1size として渡すことは、関数自体がwcslenを使用して長さを計算する必要があることを示します。 失敗した場合はNULLを返します。
Py_ssize_t PyUnicode_AsWideChar(PyObject *unicode, wchar_t *w, Py_ssize_t size)
Unicodeオブジェクトの内容をwchar_tバッファ w にコピーします。 最大でサイズ wchar_t文字がコピーされます(末尾のヌル終了文字の可能性を除く)。 コピーされたwchar_t文字数、またはエラーの場合は-1を返します。 結果の wchar_t * 文字列は、nullで終了する場合と終了しない場合があることに注意してください。 アプリケーションで必要な場合に備えて、 wchar_t * 文字列がnullで終了していることを確認するのは呼び出し元の責任です。 また、 wchar_t * 文字列にヌル文字が含まれている可能性があることに注意してください。これにより、ほとんどのC関数で使用すると文字列が切り捨てられます。
wchar_t *PyUnicode_AsWideCharString(PyObject *unicode, Py_ssize_t *size)

Unicodeオブジェクトをワイド文字列に変換します。 出力文字列は常にヌル文字で終わります。 sizeNULLでない場合は、ワイド文字数(末尾のヌル終了文字を除く)を * size に書き込みます。 結果のwchar_t文字列にヌル文字が含まれる可能性があることに注意してください。これにより、ほとんどのC関数で使用すると文字列が切り捨てられます。 sizeNULLで、 wchar_t * 文字列にヌル文字が含まれている場合、 ValueError が発生します。

成功すると、PyMem_Alloc()によって割り当てられたバッファーを返します( PyMem_Free()を使用して解放します)。 エラーの場合、NULLを返し、 * size は未定義です。 メモリの割り当てに失敗すると、 MemoryError が発生します。

バージョン3.2の新機能。

バージョン3.7で変更: sizeNULLで、 wchar_t * 文字列にヌル文字が含まれている場合、 ValueError が発生します。


組み込みコーデック

Pythonは、速度を上げるためにCで記述された一連の組み込みコーデックを提供します。 これらのコーデックはすべて、次の関数を介して直接使用できます。

次のAPIの多くは、エンコードとエラーの2つの引数を取り、組み込みの str()文字列オブジェクトコンストラクターと同じセマンティクスを持っています。

エンコーディングをNULLに設定すると、デフォルトのエンコーディングであるUTF-8が使用されます。 ファイルシステムコールでは、ファイル名のエンコードに PyUnicode_FSConverter()を使用する必要があります。 これは、変数Py_FileSystemDefaultEncodingを内部的に使用します。 この変数は読み取り専用として扱う必要があります。一部のシステムでは、静的文字列へのポインタになり、他のシステムでは、実行時に(アプリケーションがsetlocaleを呼び出すときなど)変更されます。

エラー処理はエラーによって設定されます。エラーはNULLに設定することもできます。これは、コーデックに定義されているデフォルトの処理を使用することを意味します。 すべての組み込みコーデックのデフォルトのエラー処理は「厳密」です( ValueError が発生します)。

コーデックはすべて同様のインターフェイスを使用します。 簡単にするために、以下の一般的なものからの逸脱のみが文書化されています。

汎用コーデック

これらは一般的なコーデックAPIです。

PyObject *PyUnicode_Decode(const char *s, Py_ssize_t size, const char *encoding, const char *errors)
エンコードされた文字列 sサイズバイトをデコードして、Unicodeオブジェクトを作成します。 encoding および errors は、 str()組み込み関数の同じ名前のパラメーターと同じ意味を持ちます。 使用するコーデックは、Pythonコーデックレジストリを使用して検索されます。 コーデックによって例外が発生した場合は、NULLを返します。
PyObject *PyUnicode_AsEncodedString(PyObject *unicode, const char *encoding, const char *errors)
Unicodeオブジェクトをエンコードし、結果をPythonバイトオブジェクトとして返します。 encoding および errors は、Unicode encode()メソッドの同じ名前のパラメーターと同じ意味を持ちます。 使用するコーデックは、Pythonコーデックレジストリを使用して検索されます。 コーデックによって例外が発生した場合は、NULLを返します。
PyObject *PyUnicode_Encode(const Py_UNICODE *s, Py_ssize_t size, const char *encoding, const char *errors)
指定されたサイズPy_UNICODE バッファー s をエンコードし、Pythonバイトオブジェクトを返します。 encoding および errors は、Unicode encode()メソッドの同じ名前のパラメーターと同じ意味を持ちます。 使用するコーデックは、Pythonコーデックレジストリを使用して検索されます。 コーデックによって例外が発生した場合は、NULLを返します。


UTF-8コーデック

これらはUTF-8コーデックAPIです。

PyObject *PyUnicode_DecodeUTF8(const char *s, Py_ssize_t size, const char *errors)
UTF-8でエンコードされた文字列 sサイズバイトをデコードして、Unicodeオブジェクトを作成します。 コーデックによって例外が発生した場合は、NULLを返します。
PyObject *PyUnicode_DecodeUTF8Stateful(const char *s, Py_ssize_t size, const char *errors, Py_ssize_t *consumed)
消費NULLの場合、 PyUnicode_DecodeUTF8()のように動作します。 使用済みNULLでない場合、後続の不完全なUTF-8バイトシーケンスはエラーとして扱われません。 これらのバイトはデコードされず、デコードされたバイト数は使用済みに格納されます。
PyObject *PyUnicode_AsUTF8String(PyObject *unicode)
UTF-8を使用してUnicodeオブジェクトをエンコードし、結果をPythonバイトオブジェクトとして返します。 エラー処理は「厳密」です。 コーデックによって例外が発生した場合は、NULLを返します。
const char *PyUnicode_AsUTF8AndSize(PyObject *unicode, Py_ssize_t *size)

UnicodeオブジェクトのUTF-8エンコードへのポインターを返し、エンコードされた表現のサイズ(バイト単位)を size に格納します。 size 引数はNULLにすることができます。 この場合、サイズは保存されません。 返されるバッファには、他にnullコードポイントがあるかどうかに関係なく、常に追加のnullバイトが追加されます( size には含まれません)。

エラーの場合、NULLが例外セットとともに返され、サイズは格納されません。

これにより、文字列のUTF-8表現がUnicodeオブジェクトにキャッシュされ、後続の呼び出しで同じバッファーへのポインターが返されます。 呼び出し元は、バッファーの割り当てを解除する責任を負いません。

バージョン3.3の新機能。

バージョン3.7で変更:戻りタイプがchar *ではなくconst char *になりました。

const char *PyUnicode_AsUTF8(PyObject *unicode)

PyUnicode_AsUTF8AndSize()と同じですが、サイズは保存されません。

バージョン3.3の新機能。

バージョン3.7で変更:戻りタイプがchar *ではなくconst char *になりました。

PyObject *PyUnicode_EncodeUTF8(const Py_UNICODE *s, Py_ssize_t size, const char *errors)
指定されたサイズPy_UNICODE バッファー s をUTF-8を使用してエンコードし、Pythonバイトオブジェクトを返します。 コーデックによって例外が発生した場合は、NULLを返します。


UTF-32コーデック

これらはUTF-32コーデックAPIです。

PyObject *PyUnicode_DecodeUTF32(const char *s, Py_ssize_t size, const char *errors, int *byteorder)

UTF-32でエンコードされたバッファ文字列から size バイトをデコードし、対応するUnicodeオブジェクトを返します。 errorsNULL以外の場合)はエラー処理を定義します。 デフォルトは「strict」です。

byteorderNULL以外の場合、デコーダーは指定されたバイトオーダーを使用してデコードを開始します。

*byteorder == -1: little endian
*byteorder == 0:  native order
*byteorder == 1:  big endian

*byteorderがゼロで、入力データの最初の4バイトがバイトオーダーマーク(BOM)の場合、デコーダーはこのバイトオーダーに切り替わり、BOMは結果のUnicode文字列にコピーされません。 *byteorder-1または1の場合、任意のバイト順マークが出力にコピーされます。

完了後、 * byteorder は、入力データの最後の現在のバイトオーダーに設定されます。

byteorderNULLの場合、コーデックはネイティブオーダーモードで起動します。

コーデックによって例外が発生した場合は、NULLを返します。

PyObject *PyUnicode_DecodeUTF32Stateful(const char *s, Py_ssize_t size, const char *errors, int *byteorder, Py_ssize_t *consumed)
消費NULLの場合、 PyUnicode_DecodeUTF32()のように動作します。 使用済みNULLでない場合、 PyUnicode_DecodeUTF32Stateful()は、後続の不完全なUTF-32バイトシーケンス(4で割り切れないバイト数など)をエラー。 これらのバイトはデコードされず、デコードされたバイト数は使用済みに格納されます。
PyObject *PyUnicode_AsUTF32String(PyObject *unicode)
ネイティブバイトオーダーでUTF-32エンコーディングを使用してPythonバイト文字列を返します。 文字列は常にBOMマークで始まります。 エラー処理は「厳密」です。 コーデックによって例外が発生した場合は、NULLを返します。
PyObject *PyUnicode_EncodeUTF32(const Py_UNICODE *s, Py_ssize_t size, const char *errors, int byteorder)

s のUnicodeデータのUTF-32エンコード値を保持するPythonバイトオブジェクトを返します。 出力は、次のバイト順序に従って書き込まれます。

byteorder == -1: little endian
byteorder == 0:  native byte order (writes a BOM mark)
byteorder == 1:  big endian

バイトオーダーが0の場合、出力文字列は常にUnicode BOMマーク(U + FEFF)で始まります。 他の2つのモードでは、BOMマークは付加されません。

Py_UNICODE_WIDEが定義されていない場合、サロゲートペアは単一のコードポイントとして出力されます。

コーデックによって例外が発生した場合は、NULLを返します。


UTF-16コーデック

これらはUTF-16コーデックAPIです。

PyObject *PyUnicode_DecodeUTF16(const char *s, Py_ssize_t size, const char *errors, int *byteorder)

UTF-16でエンコードされたバッファ文字列から size バイトをデコードし、対応するUnicodeオブジェクトを返します。 errorsNULL以外の場合)はエラー処理を定義します。 デフォルトは「strict」です。

byteorderNULL以外の場合、デコーダーは指定されたバイトオーダーを使用してデコードを開始します。

*byteorder == -1: little endian
*byteorder == 0:  native order
*byteorder == 1:  big endian

*byteorderがゼロで、入力データの最初の2バイトがバイトオーダーマーク(BOM)の場合、デコーダーはこのバイトオーダーに切り替わり、BOMは結果のUnicode文字列にコピーされません。 *byteorder-1または1の場合、任意のバイト順マークが出力にコピーされます(\ufeffまたは\ufffe文字)。

完了後、 * byteorder は、入力データの最後の現在のバイトオーダーに設定されます。

byteorderNULLの場合、コーデックはネイティブオーダーモードで起動します。

コーデックによって例外が発生した場合は、NULLを返します。

PyObject *PyUnicode_DecodeUTF16Stateful(const char *s, Py_ssize_t size, const char *errors, int *byteorder, Py_ssize_t *consumed)
消費NULLの場合、 PyUnicode_DecodeUTF16()のように動作します。 使用済みNULLでない場合、 PyUnicode_DecodeUTF16Stateful()は、後続の不完全なUTF-16バイトシーケンス(奇数バイトや分割サロゲートペアなど)を処理しません。エラーとして。 これらのバイトはデコードされず、デコードされたバイト数は使用済みに格納されます。
PyObject *PyUnicode_AsUTF16String(PyObject *unicode)
ネイティブバイトオーダーでUTF-16エンコーディングを使用してPythonバイト文字列を返します。 文字列は常にBOMマークで始まります。 エラー処理は「厳密」です。 コーデックによって例外が発生した場合は、NULLを返します。
PyObject *PyUnicode_EncodeUTF16(const Py_UNICODE *s, Py_ssize_t size, const char *errors, int byteorder)

s のUnicodeデータのUTF-16エンコード値を保持するPythonバイトオブジェクトを返します。 出力は、次のバイト順序に従って書き込まれます。

byteorder == -1: little endian
byteorder == 0:  native byte order (writes a BOM mark)
byteorder == 1:  big endian

バイトオーダーが0の場合、出力文字列は常にUnicode BOMマーク(U + FEFF)で始まります。 他の2つのモードでは、BOMマークは付加されません。

Py_UNICODE_WIDEが定義されている場合、単一の Py_UNICODE 値がサロゲートペアとして表される場合があります。 定義されていない場合、各 Py_UNICODE 値はUCS-2文字として解釈されます。

コーデックによって例外が発生した場合は、NULLを返します。


UTF-7コーデック

これらはUTF-7コーデックAPIです。

PyObject *PyUnicode_DecodeUTF7(const char *s, Py_ssize_t size, const char *errors)
UTF-7でエンコードされた文字列 sサイズバイトをデコードして、Unicodeオブジェクトを作成します。 コーデックによって例外が発生した場合は、NULLを返します。
PyObject *PyUnicode_DecodeUTF7Stateful(const char *s, Py_ssize_t size, const char *errors, Py_ssize_t *consumed)
消費NULLの場合、 PyUnicode_DecodeUTF7()のように動作します。 使用済みNULLでない場合、後続の不完全なUTF-7base-64セクションはエラーとして扱われません。 これらのバイトはデコードされず、デコードされたバイト数は使用済みに格納されます。
PyObject *PyUnicode_EncodeUTF7(const Py_UNICODE *s, Py_ssize_t size, int base64SetO, int base64WhiteSpace, const char *errors)

UTF-7を使用して、指定されたサイズの Py_UNICODE バッファーをエンコードし、Pythonバイトオブジェクトを返します。 コーデックによって例外が発生した場合は、NULLを返します。

base64SetO がゼロ以外の場合、「Set O」(特別な意味を持たない句読点)はbase-64でエンコードされます。 base64WhiteSpace がゼロ以外の場合、空白はbase-64でエンコードされます。 Python「utf-7」コーデックでは、両方ともゼロに設定されています。


Unicode-エスケープコーデック

これらは「UnicodeEscape」コーデックAPIです。

PyObject *PyUnicode_DecodeUnicodeEscape(const char *s, Py_ssize_t size, const char *errors)
Unicodeエスケープでエンコードされた文字列 sサイズバイトをデコードして、Unicodeオブジェクトを作成します。 コーデックによって例外が発生した場合は、NULLを返します。
PyObject *PyUnicode_AsUnicodeEscapeString(PyObject *unicode)
Unicode-Escapeを使用してUnicodeオブジェクトをエンコードし、結果をバイトオブジェクトとして返します。 エラー処理は「厳密」です。 コーデックによって例外が発生した場合は、NULLを返します。
PyObject *PyUnicode_EncodeUnicodeEscape(const Py_UNICODE *s, Py_ssize_t size)
Unicode-Escapeを使用して、指定された sizePy_UNICODE バッファーをエンコードし、bytesオブジェクトを返します。 コーデックによって例外が発生した場合は、NULLを返します。


Raw-Unicode-エスケープコーデック

これらは「RawUnicodeEscape」コーデックAPIです。

PyObject *PyUnicode_DecodeRawUnicodeEscape(const char *s, Py_ssize_t size, const char *errors)
Raw-Unicode-Escapeでエンコードされた文字列 sサイズバイトをデコードして、Unicodeオブジェクトを作成します。 コーデックによって例外が発生した場合は、NULLを返します。
PyObject *PyUnicode_AsRawUnicodeEscapeString(PyObject *unicode)
Raw-Unicode-Escapeを使用してUnicodeオブジェクトをエンコードし、結果をバイトオブジェクトとして返します。 エラー処理は「厳密」です。 コーデックによって例外が発生した場合は、NULLを返します。
PyObject *PyUnicode_EncodeRawUnicodeEscape(const Py_UNICODE *s, Py_ssize_t size)
Raw-Unicode-Escapeを使用して、指定された sizePy_UNICODE バッファーをエンコードし、bytesオブジェクトを返します。 コーデックによって例外が発生した場合は、NULLを返します。


ラテン語-1コーデック

これらはLatin-1コーデックAPIです。Latin-1は最初の256のUnicode序数に対応し、エンコード中にコーデックによって受け入れられるのはこれらだけです。

PyObject *PyUnicode_DecodeLatin1(const char *s, Py_ssize_t size, const char *errors)
Latin-1でエンコードされた文字列 sサイズバイトをデコードして、Unicodeオブジェクトを作成します。 コーデックによって例外が発生した場合は、NULLを返します。
PyObject *PyUnicode_AsLatin1String(PyObject *unicode)
Latin-1を使用してUnicodeオブジェクトをエンコードし、結果をPythonバイトオブジェクトとして返します。 エラー処理は「厳密」です。 コーデックによって例外が発生した場合は、NULLを返します。
PyObject *PyUnicode_EncodeLatin1(const Py_UNICODE *s, Py_ssize_t size, const char *errors)
Latin-1を使用して、指定された sizePy_UNICODE バッファーをエンコードし、Pythonバイトオブジェクトを返します。 コーデックによって例外が発生した場合は、NULLを返します。


ASCIIコーデック

これらはASCIIコーデックAPIです。 7ビットのASCIIデータのみが受け入れられます。 他のすべてのコードはエラーを生成します。

PyObject *PyUnicode_DecodeASCII(const char *s, Py_ssize_t size, const char *errors)
ASCIIエンコードされた文字列 ssize バイトをデコードしてUnicodeオブジェクトを作成します。 コーデックによって例外が発生した場合は、NULLを返します。
PyObject *PyUnicode_AsASCIIString(PyObject *unicode)
ASCIIを使用してUnicodeオブジェクトをエンコードし、結果をPythonバイトオブジェクトとして返します。 エラー処理は「厳密」です。 コーデックによって例外が発生した場合は、NULLを返します。
PyObject *PyUnicode_EncodeASCII(const Py_UNICODE *s, Py_ssize_t size, const char *errors)
指定されたサイズPy_UNICODE バッファーをASCIIを使用してエンコードし、Pythonバイトオブジェクトを返します。 コーデックによって例外が発生した場合は、NULLを返します。


文字コード表コーデック

このコーデックは、多くの異なるコーデックを実装するために使用できるという点で特別です(実際、これはencodingsパッケージに含まれるほとんどの標準コーデックを取得するために行われたことです)。 コーデックは、マッピングを使用して文字をエンコードおよびデコードします。 提供されるマッピングオブジェクトは、__getitem__()マッピングインターフェイスをサポートする必要があります。 辞書とシーケンスはうまく機能します。

マッピングコーデックAPIは次のとおりです。

PyObject *PyUnicode_DecodeCharmap(const char *data, Py_ssize_t size, PyObject *mapping, const char *errors)

指定された mapping オブジェクトを使用して、エンコードされた文字列 ssize バイトをデコードしてUnicodeオブジェクトを作成します。 コーデックによって例外が発生した場合は、NULLを返します。

マッピングNULLの場合、Latin-1デコードが適用されます。 それ以外の場合、マッピングはバイト序数(0から255の範囲の整数)をUnicode文字列、整数(Unicode序数として解釈される)またはNoneにマップする必要があります。 マップされていないデータバイト– LookupError を引き起こすバイト、およびNone0xFFFE、または'\ufffe'にマップされるバイトは、未定義のマッピングとして扱われます。エラーを引き起こします。

PyObject *PyUnicode_AsCharmapString(PyObject *unicode, PyObject *mapping)

指定された mapping オブジェクトを使用してUnicodeオブジェクトをエンコードし、結果をバイトオブジェクトとして返します。 エラー処理は「厳密」です。 コーデックによって例外が発生した場合は、NULLを返します。

mapping オブジェクトは、Unicode序数整数をbytesオブジェクト、0〜255の範囲の整数、またはNoneにマップする必要があります。 マップされていない文字序数( LookupError を引き起こすもの)およびNoneにマップされたものは、「未定義のマッピング」として扱われ、エラーを引き起こします。

PyObject *PyUnicode_EncodeCharmap(const Py_UNICODE *s, Py_ssize_t size, PyObject *mapping, const char *errors)
指定された mapping オブジェクトを使用して、指定された sizePy_UNICODE バッファーをエンコードし、結果をバイトオブジェクトとして返します。 コーデックによって例外が発生した場合は、NULLを返します。

次のコーデックAPIは、UnicodeをUnicodeにマップするという点で特別です。

PyObject *PyUnicode_Translate(PyObject *str, PyObject *table, const char *errors)

文字マッピングテーブルを適用して文字列を変換し、結果のUnicodeオブジェクトを返します。 コーデックによって例外が発生した場合は、NULLを返します。

マッピングテーブルは、Unicode序数整数をUnicode序数整数またはNone(文字の削除を引き起こす)にマップする必要があります。

マッピングテーブルは、__getitem__()インターフェイスを提供するだけで済みます。 辞書とシーケンスはうまく機能します。 マップされていない文字の序数( LookupError を引き起こすもの)はそのまま残され、そのままコピーされます。

エラーは、コーデックの通常の意味を持ちます。 デフォルトのエラー処理を使用することを示すのはNULLの場合があります。

PyObject *PyUnicode_TranslateCharmap(const Py_UNICODE *s, Py_ssize_t size, PyObject *mapping, const char *errors)
指定されたサイズPy_UNICODE バッファーに文字マッピングテーブルを適用して変換し、結果のUnicodeオブジェクトを返します。 コーデックによって例外が発生した場合は、NULLを返します。


Windows用のMBCSコーデック

これらはMBCSコーデックAPIです。 これらは現在Windowsでのみ使用可能であり、Win32MBCSコンバーターを使用して変換を実装します。 MBCS(またはDBCS)は、1つだけではなく、エンコーディングのクラスであることに注意してください。 ターゲットエンコーディングは、コーデックを実行しているマシンのユーザー設定によって定義されます。

PyObject *PyUnicode_DecodeMBCS(const char *s, Py_ssize_t size, const char *errors)
MBCSでエンコードされた文字列 sサイズバイトをデコードして、Unicodeオブジェクトを作成します。 コーデックによって例外が発生した場合は、NULLを返します。
PyObject *PyUnicode_DecodeMBCSStateful(const char *s, Py_ssize_t size, const char *errors, Py_ssize_t *consumed)
消費NULLの場合、 PyUnicode_DecodeMBCS()のように動作します。 使用済みNULLでない場合、 PyUnicode_DecodeMBCSStateful()は後続の先行バイトをデコードせず、デコードされたバイト数は消費済みに格納されます。 X191X]。
PyObject *PyUnicode_AsMBCSString(PyObject *unicode)
MBCSを使用してUnicodeオブジェクトをエンコードし、結果をPythonバイトオブジェクトとして返します。 エラー処理は「厳密」です。 コーデックによって例外が発生した場合は、NULLを返します。
PyObject *PyUnicode_EncodeCodePage(int code_page, PyObject *unicode, const char *errors)

指定されたコードページを使用してUnicodeオブジェクトをエンコードし、Pythonバイトオブジェクトを返します。 コーデックによって例外が発生した場合は、NULLを返します。 CP_ACPコードページを使用して、MBCSエンコーダーを取得します。

バージョン3.3の新機能。

PyObject *PyUnicode_EncodeMBCS(const Py_UNICODE *s, Py_ssize_t size, const char *errors)
指定されたサイズPy_UNICODE バッファーを、MBCSを使用してエンコードし、Pythonバイトオブジェクトを返します。 コーデックによって例外が発生した場合は、NULLを返します。


メソッドとスロット

メソッドとスロット機能

次のAPIは、入力時にUnicodeオブジェクトと文字列を処理し(説明では文字列と呼びます)、必要に応じてUnicodeオブジェクトまたは整数を返します。

例外が発生した場合、それらはすべてNULLまたは-1を返します。

PyObject *PyUnicode_Concat(PyObject *left, PyObject *right)
2つの文字列を連結して、新しいUnicode文字列を作成します。
PyObject *PyUnicode_Split(PyObject *s, PyObject *sep, Py_ssize_t maxsplit)
文字列を分割して、Unicode文字列のリストを提供します。 sepNULLの場合、すべての空白文字列で分割が行われます。 それ以外の場合、分割は指定されたセパレータで発生します。 最大で maxsplit 分割が実行されます。 負の場合、制限は設定されません。 結果のリストにはセパレーターは含まれていません。
PyObject *PyUnicode_Splitlines(PyObject *s, int keepend)
Unicode文字列を改行で分割し、Unicode文字列のリストを返します。 CRLFは1つの改行と見なされます。 keepend0の場合、改行文字は結果の文字列に含まれません。
PyObject *PyUnicode_Join(PyObject *separator, PyObject *seq)
指定された separator を使用して文字列のシーケンスを結合し、結果のUnicode文字列を返します。
Py_ssize_t PyUnicode_Tailmatch(PyObject *str, PyObject *substr, Py_ssize_t start, Py_ssize_t end, int direction)
substr が指定されたテールエンドでstr[start:end]と一致する場合、1を返します( direction == -1はプレフィックス一致を行うことを意味し、 direction == 1サフィックスが一致します)、それ以外の場合は0。 エラーが発生した場合は、-1を返します。
Py_ssize_t PyUnicode_Find(PyObject *str, PyObject *substr, Py_ssize_t start, Py_ssize_t end, int direction)
指定された方向を使用してstr[start:end]substr の最初の位置を返します(方向 == 1は順方向を実行することを意味します検索、方向 == -1後方検索)。 戻り値は最初の一致のインデックスです。 -1の値は一致が見つからなかったことを示し、-2はエラーが発生して例外が設定されたことを示します。
Py_ssize_t PyUnicode_FindChar(PyObject *str, Py_UCS4 ch, Py_ssize_t start, Py_ssize_t end, int direction)

指定された方向を使用してstr[start:end]の文字 ch の最初の位置を返します(方向 == 1は実行することを意味します前方検索、方向 == -1後方検索)。 戻り値は最初の一致のインデックスです。 -1の値は一致が見つからなかったことを示し、-2はエラーが発生して例外が設定されたことを示します。

バージョン3.3の新機能。

バージョン3.7で変更: start および endstr[start:end]のように動作するように調整されました。

Py_ssize_t PyUnicode_Count(PyObject *str, PyObject *substr, Py_ssize_t start, Py_ssize_t end)
str[start:end]内の substr の重複しないオカレンスの数を返します。 エラーが発生した場合は、-1を返します。
PyObject *PyUnicode_Replace(PyObject *str, PyObject *substr, PyObject *replstr, Py_ssize_t maxcount)
str 内の substr の最大 maxcount オカレンスを replstr に置き換え、結果のUnicodeオブジェクトを返します。 maxcount == -1は、すべてのオカレンスを置き換えることを意味します。
int PyUnicode_Compare(PyObject *left, PyObject *right)

2つの文字列を比較し、-101をそれぞれ、より小さい、等しい、およびより大きい場合に返します。

この関数は失敗すると-1を返すため、 PyErr_Occurred()を呼び出してエラーをチェックする必要があります。

int PyUnicode_CompareWithASCIIString(PyObject *uni, const char *string)

Unicodeオブジェクト unistring と比較し、-101を以下、等しい、およびそれぞれより大きい。 ASCIIでエンコードされた文字列のみを渡すのが最善ですが、非ASCII文字が含まれている場合、関数は入力文字列をISO-8859-1として解釈します。

この関数は例外を発生させません。

PyObject *PyUnicode_RichCompare(PyObject *left, PyObject *right, int op)

2つのUnicode文字列をリッチ比較し、次のいずれかを返します。

  • NULL例外が発生した場合

  • 比較を成功させるには、Py_TrueまたはPy_False

  • Py_NotImplementedタイプの組み合わせが不明な場合

op に指定できる値は、Py_GTPy_GEPy_EQPy_NEPy_LT、およびPy_LE

PyObject *PyUnicode_Format(PyObject *format, PyObject *args)
format および args から新しい文字列オブジェクトを返します。 これはformat % argsに類似しています。
int PyUnicode_Contains(PyObject *container, PyObject *element)

elementcontainer に含まれているかどうかを確認し、それに応じてtrueまたはfalseを返します。

element は、1つの要素のUnicode文字列に強制変換する必要があります。 エラーが発生した場合は、-1が返されます。

void PyUnicode_InternInPlace(PyObject **string)
引数 * string をインターンします。 引数は、PythonUnicode文字列オブジェクトを指すポインタ変数のアドレスである必要があります。 * string と同じ既存のインターン文字列がある場合は、 * string を設定します(古い文字列オブジェクトの参照カウントをデクリメントし、インターンされた文字列オブジェクト)、それ以外の場合は、 * string をそのままにして、インターンします(参照カウントをインクリメントします)。 (明確化:参照カウントについては多くの話がありますが、この関数は参照カウントニュートラルと考えてください。呼び出し前にオブジェクトを所有している場合に限り、呼び出し後にオブジェクトを所有します。)
PyObject *PyUnicode_InternFromString(const char *v)
PyUnicode_FromString()PyUnicode_InternInPlace()の組み合わせで、インターンされた新しいUnicode文字列オブジェクト、または以前にインターンされた文字列オブジェクトへの新しい(「所有」)参照を返します同じ値で。