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によって作成されたすべてのオブジェクトです。 それらは、実装によって許可された最も効率的な表現を使用します。
- 「レガシー」ユニコードオブジェクトは、非推奨のAPIの1つ(通常は PyUnicode_FromUnicode())を介して作成されており、
Py_UNICODE*
表現のみを備えています。 他のAPIを呼び出す前に、それらに対して PyUnicode_READY()を呼び出す必要があります。
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の新機能。
- 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)
正規表現 data ( PyUnicode_DATA()で取得)からコードポイントを読み取ります。 チェックやレディコールは実行されません。
バージョン3.3の新機能。
- Py_UCS4 PyUnicode_READ_CHAR(PyObject *o, Py_ssize_t index)
Unicodeオブジェクト o から文字を読み取ります。これは「正規」表現である必要があります。 複数の連続した読み取りを行う場合、これは PyUnicode_READ()よりも効率的ではありません。
バージョン3.3の新機能。
- PyUnicode_MAX_CHAR_VALUE(PyObject *o)
o に基づいて別の文字列を作成するのに適した最大コードポイントを返します。これは、「正規」表現である必要があります。 これは常に概算ですが、文字列を反復処理するよりも効率的です。
バージョン3.3の新機能。
- int PyUnicode_ClearFreeList()
- フリーリストをクリアします。 解放されたアイテムの総数を返します。
- 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 [X196Xを返す] ]例外セット付き)。 新しい
PyUnicode_nBYTE_DATA()
マクロを使用するようにコードを移植するか、 PyUnicode_WRITE()または PyUnicode_READ()を使用してみてください。
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値を返します。 high と low は、それぞれサロゲートペアの先頭と末尾のサロゲートです。
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 でない場合、戻り値は共有オブジェクトである可能性があります。 データの変更は許可されていません。
u が NULL の場合、この関数は PyUnicode_FromUnicode()のように動作し、バッファーは NULL に設定されます。 PyUnicode_New()を優先して、この使用法は非推奨になりました。
- PyObject *PyUnicode_FromString(const char *u)
- UTF-8でエンコードされたnullで終了するcharバッファ u からUnicodeオブジェクトを作成します。
- PyObject *PyUnicode_FromFormat(const char *format, ...)
C
printf()
スタイルの format 文字列と可変数の引数を取り、結果のPythonユニコード文字列のサイズを計算し、値がフォーマットされた文字列を返します。 可変引数はCタイプである必要があり、 format ASCIIエンコード文字列のフォーマット文字に正確に対応している必要があります。 次のフォーマット文字を使用できます。文字のフォーマット
タイプ
コメント
%%
該当なし
The literal % character.
%c
int
Cintとして表される単一の文字。
%d
int
printf("%d")
とまったく同じです。%u
unsigned int
printf("%u")
とまったく同じです。%ld
長いです
printf("%ld")
とまったく同じです。%li
長いです
printf("%li")
とまったく同じです。%lu
unsigned long
printf("%lu")
とまったく同じです。%lld
長い長い
printf("%lld")
とまったく同じです。%lli
長い長い
printf("%lli")
とまったく同じです。%llu
unsigned long long
printf("%llu")
とまったく同じです。%zd
Py_ssize_t
printf("%zd")
とまったく同じです。%zi
Py_ssize_t
printf("%zi")
とまったく同じです。%zu
size_t
printf("%zu")
とまったく同じです。%i
int
printf("%i")
とまったく同じです。%x
int
printf("%x")
とまったく同じです。%s
char *
ヌル終了C文字配列。
%p
空所*
Cポインターの16進表現。 プラットフォームの
printf
が何を生成するかに関係なく、リテラル0x
で開始することが保証されていることを除いて、printf("%p")
とほぼ同等です。%A
PyObject *
ascii()を呼び出した結果。
%U
PyObject *
ユニコードオブジェクト。
%V
PyObject *、char *
ユニコードオブジェクト( NULL の場合があります)および2番目のパラメーターとしてのnullで終了するC文字配列(最初のパラメーターが NULL の場合に使用されます)。
%S
PyObject *
PyObject_Str()を呼び出した結果。
%R
PyObject *
PyObject_Repr()を呼び出した結果。
認識されないフォーマット文字により、フォーマット文字列の残りのすべてがそのまま結果文字列にコピーされ、余分な引数は破棄されます。
ノート
幅フォーマッタの単位は、バイトではなく文字数です。 精度フォーマッタの単位は、
"%s"
および"%V"
(PyObject*
引数がNULLの場合)のバイト数、および"%A"
、[ X155X] 、"%S"
、"%R"
、および"%V"
(PyObject*
引数がNULLでない場合)。バージョン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オブジェクトにデコードします。
bytes 、 bytearray およびその他の 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_char を
unicode[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 を返し、エラー時に例外を設定します(特に、 buflen が u の長さよりも小さい場合は SystemError )。 buffer は、成功すると返されます。
バージョン3.3の新機能。
- Py_UCS4 *PyUnicode_AsUCS4Copy(PyObject *u)
文字列 u を、 PyMem_Malloc()を使用して割り当てられた新しいUCS4バッファーにコピーします。 これが失敗した場合、 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オブジェクトを作成します。 u は NULL である可能性があり、これにより内容が未定義になります。 必要なデータを入力するのはユーザーの責任です。 バッファが新しいオブジェクトにコピーされます。
バッファが NULL でない場合、戻り値は共有オブジェクトである可能性があります。 したがって、結果のUnicodeオブジェクトの変更は、 u が NULL の場合にのみ許可されます。
バッファが NULL の場合、 PyUnicode_KIND()などのアクセスマクロを使用する前に、文字列の内容が入力されたら PyUnicode_READY()を呼び出す必要があります。
PyUnicode_FromKindAndData()、 PyUnicode_FromWideChar()、または PyUnicode_New()の使用に移行してください。
- Py_UNICODE *PyUnicode_AsUnicode(PyObject *unicode)
Unicodeオブジェクトの内部 Py_UNICODE バッファーへの読み取り専用ポインターを返すか、エラーの場合は NULL を返します。 これにより、オブジェクトがまだ使用できない場合、オブジェクトの
Py_UNICODE*
表現が作成されます。 バッファは常に余分なヌルコードポイントで終了します。 結果の Py_UNICODE 文字列には、埋め込まれたnullコードポイントも含まれる可能性があることに注意してください。これにより、ほとんどのC関数で使用されるときに文字列が切り捨てられます。PyUnicode_AsUCS4()、 PyUnicode_AsWideChar()、 PyUnicode_ReadChar()または同様の新しいAPIを使用するように移行してください。
- 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()配列の長さ(余分なヌルターミネータを除く)もサイズで保存します。 結果の
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単位の代理ペアが含まれます)。
PyUnicode_GetLength()の使用に移行してください。
- 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)
現在のロケールエンコーディングから文字列をデコードします。 サポートされているエラーハンドラーは、
"strict"
および"surrogateescape"
( PEP 383 )です。 エラーがNULL
の場合、デコーダーは"strict"
エラーハンドラーを使用します。 str はヌル文字で終了する必要がありますが、埋め込まれたヌル文字を含めることはできません。PyUnicode_DecodeFSDefaultAndSize()を使用して、
Py_FileSystemDefaultEncoding
(Pythonの起動時に読み取られるロケールエンコーディング)から文字列をデコードします。も参照してください
バージョン3.3の新機能。
バージョン3.6.5で変更:この関数は、
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オブジェクトを現在のロケールエンコーディングにエンコードします。 サポートされているエラーハンドラーは、
"strict"
および"surrogateescape"
( PEP 383 )です。 エラーがNULL
の場合、エンコーダーは"strict"
エラーハンドラーを使用します。 bytes オブジェクトを返します。 unicode にヌル文字を埋め込むことはできません。PyUnicode_EncodeFSDefault()を使用して、文字列を
Py_FileSystemDefaultEncoding
(Pythonの起動時に読み取られるロケールエンコード)にエンコードします。も参照してください
バージョン3.3の新機能。
バージョン3.6.5で変更:この関数は、
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_FileSystemDefaultEncoding
とPy_FileSystemDefaultEncodeErrors
エラーハンドラーを使用して文字列をデコードします。Py_FileSystemDefaultEncoding
が設定されていない場合は、ロケールエンコーディングにフォールバックします。Py_FileSystemDefaultEncoding
は、起動時にロケールエンコーディングから初期化され、後で変更することはできません。 現在のロケールエンコーディングから文字列をデコードする必要がある場合は、 PyUnicode_DecodeLocaleAndSize()を使用してください。も参照してください
バージョン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()を使用してください。も参照してください
バージョン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オブジェクトを作成します。-1
を size として渡すことは、関数自体が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オブジェクトをワイド文字列に変換します。 出力文字列は常にヌル文字で終わります。 size が NULL でない場合は、ワイド文字数(末尾のヌル終了文字を除く)を * size に書き込みます。
成功すると、
PyMem_Alloc()
によって割り当てられたバッファーを返します( PyMem_Free()を使用して解放します)。 エラーの場合、 NULL を返し、 * size は未定義であり、 MemoryError を発生させます。 結果のwchar_t
文字列にヌル文字が含まれる可能性があることに注意してください。これにより、ほとんどのC関数で使用すると文字列が切り捨てられます。バージョン3.2の新機能。
組み込みコーデック
Pythonは、速度を上げるためにCで記述された一連の組み込みコーデックを提供します。 これらのコーデックはすべて、次の関数を介して直接使用できます。
次のAPIの多くは、エンコードとエラーの2つの引数を取り、組み込みの str()文字列オブジェクトコンストラクターと同じセマンティクスを持っています。
エンコーディングを NULL に設定すると、デフォルトのエンコーディングであるASCIIが使用されます。 ファイルシステムコールでは、ファイル名のエンコードに 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 を返します。
- 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バイトシーケンスはエラーとして扱われません。 これらのバイトはデコードされず、デコードされたバイト数は使用済みに格納されます。
- UTF-8を使用してUnicodeオブジェクトをエンコードし、結果をPythonバイトオブジェクトとして返します。 エラー処理は「厳密」です。 コーデックによって例外が発生した場合は、 NULL を返します。
- char *PyUnicode_AsUTF8AndSize(PyObject *unicode, Py_ssize_t *size)
UnicodeオブジェクトのUTF-8エンコーディングへのポインタを返し、エンコードされた表現のサイズ(バイト単位)を size に格納します。 size 引数は NULL にすることができます。 この場合、サイズは保存されません。 返されるバッファには、他にnullコードポイントがあるかどうかに関係なく、常に追加のnullバイトが追加されます( size には含まれません)。
エラーの場合、 NULL が例外セットとともに返され、 size は格納されません。
これにより、文字列のUTF-8表現がUnicodeオブジェクトにキャッシュされ、後続の呼び出しで同じバッファーへのポインターが返されます。 呼び出し元は、バッファーの割り当てを解除する責任を負いません。
バージョン3.3の新機能。
- char *PyUnicode_AsUTF8(PyObject *unicode)
PyUnicode_AsUTF8AndSize()と同じですが、サイズは保存されません。
バージョン3.3の新機能。
- 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オブジェクトを返します。 errors ( NULL 以外の場合)は、エラー処理を定義します。 デフォルトは「strict」です。
byteorder が NULL 以外の場合、デコーダーは指定されたバイトオーダーを使用してデコードを開始します。
*byteorder == -1: little endian *byteorder == 0: native order *byteorder == 1: big endian
*byteorder
がゼロで、入力データの最初の4バイトがバイトオーダーマーク(BOM)の場合、デコーダーはこのバイトオーダーに切り替わり、BOMは結果のUnicode文字列にコピーされません。*byteorder
が-1
または1
の場合、任意のバイト順マークが出力にコピーされます。完了後、 * byteorder は、入力データの最後の現在のバイトオーダーに設定されます。
byteorder が NULL の場合、コーデックはネイティブオーダーモードで起動します。
コーデックによって例外が発生した場合は、 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で割り切れないバイト数など)を次のように扱いません。エラー。 これらのバイトはデコードされず、デコードされたバイト数は使用済みに格納されます。
- ネイティブバイトオーダーで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オブジェクトを返します。 errors ( NULL 以外の場合)は、エラー処理を定義します。 デフォルトは「strict」です。
byteorder が NULL 以外の場合、デコーダーは指定されたバイトオーダーを使用してデコードを開始します。
*byteorder == -1: little endian *byteorder == 0: native order *byteorder == 1: big endian
*byteorder
がゼロで、入力データの最初の2バイトがバイトオーダーマーク(BOM)の場合、デコーダーはこのバイトオーダーに切り替わり、BOMは結果のUnicode文字列にコピーされません。*byteorder
が-1
または1
の場合、任意のバイト順マークが出力にコピーされます(\ufeff
または\ufffe
文字)。完了後、 * byteorder は、入力データの最後の現在のバイトオーダーに設定されます。
byteorder が NULL の場合、コーデックはネイティブオーダーモードで起動します。
コーデックによって例外が発生した場合は、 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バイトシーケンス(奇数バイト数や分割サロゲートペアなど)を処理しません。 )エラーとして。 これらのバイトはデコードされず、デコードされたバイト数は使用済みに格納されます。
- ネイティブバイトオーダーで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 を返します。
- Unicode-Escapeを使用してUnicodeオブジェクトをエンコードし、結果をバイトオブジェクトとして返します。 エラー処理は「厳密」です。 コーデックによって例外が発生した場合は、 NULL を返します。
- PyObject *PyUnicode_EncodeUnicodeEscape(const Py_UNICODE *s, Py_ssize_t size)
- Unicode-Escapeを使用して、指定された size の Py_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 を返します。
- Raw-Unicode-Escapeを使用してUnicodeオブジェクトをエンコードし、結果をバイトオブジェクトとして返します。 エラー処理は「厳密」です。 コーデックによって例外が発生した場合は、 NULL を返します。
- PyObject *PyUnicode_EncodeRawUnicodeEscape(const Py_UNICODE *s, Py_ssize_t size)
- Raw-Unicode-Escapeを使用して、指定された size の Py_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 を返します。
- Latin-1を使用してUnicodeオブジェクトをエンコードし、結果をPythonバイトオブジェクトとして返します。 エラー処理は「厳密」です。 コーデックによって例外が発生した場合は、 NULL を返します。
- PyObject *PyUnicode_EncodeLatin1(const Py_UNICODE *s, Py_ssize_t size, const char *errors)
- Latin-1を使用して、指定された size の Py_UNICODE バッファーをエンコードし、Pythonバイトオブジェクトを返します。 コーデックによって例外が発生した場合は、 NULL を返します。
ASCIIコーデック
これらはASCIIコーデックAPIです。 7ビットのASCIIデータのみが受け入れられます。 他のすべてのコードはエラーを生成します。
- PyObject *PyUnicode_DecodeASCII(const char *s, Py_ssize_t size, const char *errors)
- ASCIIエンコードされた文字列 s の size バイトをデコードしてUnicodeオブジェクトを作成します。 コーデックによって例外が発生した場合は、 NULL を返します。
- 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 オブジェクトを使用して、エンコードされた文字列 s の size バイトをデコードしてUnicodeオブジェクトを作成します。 コーデックによって例外が発生した場合は、 NULL を返します。
マッピングが NULL の場合、Latin-1デコードが適用されます。 それ以外の場合、マッピングはバイト序数(0から255の範囲の整数)をUnicode文字列、整数(Unicode序数として解釈される)または
None
にマップする必要があります。 マップされていないデータバイト– LookupError を引き起こすバイト、およびNone
、0xFFFE
、または'\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 オブジェクトを使用して、指定された size の Py_UNICODE バッファーをエンコードし、結果をバイトオブジェクトとして返します。 コーデックによって例外が発生した場合は、 NULL を返します。
次のコーデックAPIは、UnicodeをUnicodeにマップするという点で特別です。
- PyObject *PyUnicode_Translate(PyObject *unicode, PyObject *mapping, const char *errors)
指定された mapping オブジェクトを使用してUnicodeオブジェクトを変換し、結果のUnicodeオブジェクトを返します。 コーデックによって例外が発生した場合は、 NULL を返します。
mapping オブジェクトは、Unicode序数整数をUnicode文字列、整数(Unicode序数として解釈される)または
None
(文字の削除を引き起こす)にマップする必要があります。 マップされていない文字の序数( LookupError を引き起こすもの)はそのまま残され、そのままコピーされます。
- 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()は後続の先行バイトをデコードせず、デコードされたバイト数は消費済みに格納されます。
- 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
を返します。
- 2つの文字列を連結して、新しいUnicode文字列を作成します。
- 文字列を分割して、Unicode文字列のリストを提供します。 sep が NULL の場合、すべての空白文字列で分割が行われます。 それ以外の場合、分割は指定されたセパレータで発生します。 最大で maxsplit 分割が実行されます。 負の場合、制限は設定されません。 結果のリストにはセパレーターは含まれません。
- Unicode文字列を改行で分割し、Unicode文字列のリストを返します。 CRLFは1つの改行と見なされます。 keepend が
0
の場合、改行文字は結果の文字列に含まれません。
- PyObject *PyUnicode_Translate(PyObject *str, PyObject *table, const char *errors)
文字マッピングテーブルを適用して文字列を変換し、結果のUnicodeオブジェクトを返します。
マッピングテーブルは、Unicode序数整数をUnicode序数整数または
None
(文字の削除を引き起こす)にマップする必要があります。マッピングテーブルは、
__getitem__()
インターフェイスを提供するだけで済みます。 辞書とシーケンスはうまく機能します。 マップされていない文字の序数( LookupError を引き起こすもの)はそのまま残され、そのままコピーされます。エラーは、コーデックの通常の意味を持ちます。 デフォルトのエラー処理を使用することを示す NULL の場合があります。
- 指定された 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の新機能。
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つの文字列を比較し、
-1
、0
、1
をそれぞれ、より小さい、等しい、およびより大きい場合に返します。この関数は失敗すると
-1
を返すため、 PyErr_Occurred()を呼び出してエラーをチェックする必要があります。
- int PyUnicode_CompareWithASCIIString(PyObject *uni, const char *string)
ユニコードオブジェクト uni を string と比較し、
-1
、0
、1
を以下、等しい、およびそれぞれより大きい。 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_GT
、Py_GE
、Py_EQ
、Py_NE
、Py_LT
、およびPy_LE
。
- format および args から新しい文字列オブジェクトを返します。 これは
format % args
に類似しています。
- int PyUnicode_Contains(PyObject *container, PyObject *element)
element が container に含まれているかどうかを確認し、それに応じてtrueまたはfalseを返します。
element は、1つの要素のUnicode文字列に強制変換する必要があります。 エラーが発生した場合は、
-1
が返されます。
- void PyUnicode_InternInPlace(PyObject **string)
- 引数 * string をインターンします。 引数は、Pythonユニコード文字列オブジェクトを指すポインタ変数のアドレスである必要があります。 * string と同じ既存のインターン文字列がある場合は、 * string を設定します(古い文字列オブジェクトの参照カウントをデクリメントし、インターンされた文字列オブジェクト)、それ以外の場合は、 * string をそのままにして、インターンします(参照カウントをインクリメントします)。 (明確化:参照カウントについては多くの話がありますが、この関数は参照カウントニュートラルと考えてください。呼び出し前にオブジェクトを所有している場合に限り、呼び出し後にオブジェクトを所有します。)
- PyObject *PyUnicode_InternFromString(const char *v)
- PyUnicode_FromString()と PyUnicode_InternInPlace()の組み合わせで、インターンされた新しいUnicode文字列オブジェクト、または以前にインターンされた文字列オブジェクトへの新しい(「所有」)参照を返します同じ値で。