Unicode 型別¶

這些是 Python 中用於 Unicode 實作的基本 Unicode 物件型別：

typePy_UCS4¶

typePy_UCS2¶

typePy_UCS1¶

為穩定 ABI 的一部分.

These types are typedefs for unsigned integer types wide enough to containcharacters of 32 bits, 16 bits and 8 bits, respectively. When dealing withsingle Unicode characters, usePy_UCS4.

在 3.3 版被加入.

typePy_UNICODE¶

This is a typedef ofwchar_t, which is a 16-bit type or 32-bit typedepending on the platform.

在 3.3 版的變更:In previous versions, this was a 16-bit type or a 32-bit type depending onwhether you selected a "narrow" or "wide" Unicode version of Python atbuild time.

Deprecated since version 3.13, will be removed in version 3.15.

typePyASCIIObject¶

typePyCompactUnicodeObject¶

typePyUnicodeObject¶

These subtypes ofPyObject represent a Python Unicode object. Inalmost all cases, they shouldn't be used directly, since all API functionsthat deal with Unicode objects take and returnPyObject pointers.

在 3.3 版被加入.

PyTypeObjectPyUnicode_Type¶

為穩定 ABI 的一部分.

This instance ofPyTypeObject represents the Python Unicode type.It is exposed to Python code asstr.

PyTypeObjectPyUnicodeIter_Type¶

為穩定 ABI 的一部分.

This instance ofPyTypeObject represents the Python Unicodeiterator type. It is used to iterate over Unicode string objects.

The following APIs are C macros and static inlined functions for fast checks andaccess to internal read-only data of Unicode objects:

intPyUnicode_Check(PyObject*obj)¶

Return true if the objectobj is a Unicode object or an instance of a Unicodesubtype. This function always succeeds.

intPyUnicode_CheckExact(PyObject*obj)¶

Return true if the objectobj is a Unicode object, but not an instance of asubtype. This function always succeeds.

intPyUnicode_READY(PyObject*unicode)¶

回傳0。此 API 僅保留以維持向後相容性。

在 3.3 版被加入.

在 3.10 版之後被棄用:自 Python 3.12 起，此 API 不再執行任何動作。

Py_ssize_tPyUnicode_GET_LENGTH(PyObject*unicode)¶

Return the length of the Unicode string, in code points.unicode has to be aUnicode object in the "canonical" representation (not checked).

在 3.3 版被加入.

Py_UCS1*PyUnicode_1BYTE_DATA(PyObject*unicode)¶

Py_UCS2*PyUnicode_2BYTE_DATA(PyObject*unicode)¶

Py_UCS4*PyUnicode_4BYTE_DATA(PyObject*unicode)¶

Return a pointer to the canonical representation cast to UCS1, UCS2 or UCS4integer types for direct character access. No checks are performed if thecanonical representation has the correct character size; usePyUnicode_KIND() to select the right function.

在 3.3 版被加入.

PyUnicode_1BYTE_KIND¶

PyUnicode_2BYTE_KIND¶

PyUnicode_4BYTE_KIND¶

Return values of thePyUnicode_KIND() macro.

在 3.3 版被加入.

在 3.12 版的變更:PyUnicode_WCHAR_KIND 已被移除。

intPyUnicode_KIND(PyObject*unicode)¶

Return one of the PyUnicode kind constants (see above) that indicate how manybytes per character this Unicode object uses to store its data.unicode has tobe a Unicode object in the "canonical" representation (not checked).

在 3.3 版被加入.

void*PyUnicode_DATA(PyObject*unicode)¶

Return a void pointer to the raw Unicode buffer.unicode has to be a Unicodeobject in the "canonical" representation (not checked).

在 3.3 版被加入.

voidPyUnicode_WRITE(intkind,void*data,Py_ssize_tindex,Py_UCS4value)¶

Write into a canonical representationdata (as obtained withPyUnicode_DATA()). This function performs no sanity checks, and isintended for usage in loops. The caller should cache thekind value anddata pointer as obtained from other calls.index is the index inthe string (starts at 0) andvalue is the new code point value which shouldbe written to that location.

在 3.3 版被加入.

Py_UCS4PyUnicode_READ(intkind,void*data,Py_ssize_tindex)¶

Read a code point from a canonical representationdata (as obtained withPyUnicode_DATA()). No checks or ready calls are performed.

在 3.3 版被加入.

Py_UCS4PyUnicode_READ_CHAR(PyObject*unicode,Py_ssize_tindex)¶

Read a character from a Unicode objectunicode, which must be in the "canonical"representation. This is less efficient thanPyUnicode_READ() if youdo multiple consecutive reads.

在 3.3 版被加入.

Py_UCS4PyUnicode_MAX_CHAR_VALUE(PyObject*unicode)¶

Return the maximum code point that is suitable for creating another stringbased onunicode, which must be in the "canonical" representation. This isalways an approximation but more efficient than iterating over the string.

在 3.3 版被加入.

intPyUnicode_IsIdentifier(PyObject*unicode)¶

為穩定 ABI 的一部分.

Return1 if the string is a valid identifier according to the languagedefinition, sectionIdentifiers and keywords. Return0 otherwise.

在 3.9 版的變更:The function does not callPy_FatalError() anymore if the stringis not ready.

Unicode Character Properties¶

Unicode provides many different character properties. The most often needed onesare available through these macros which are mapped to C functions depending onthe Python configuration.

intPy_UNICODE_ISSPACE(Py_UCS4ch)¶

根據ch 是否為空白字元來回傳1 或0。

intPy_UNICODE_ISLOWER(Py_UCS4ch)¶

根據ch 是否為小寫字元來回傳1 或0。

intPy_UNICODE_ISUPPER(Py_UCS4ch)¶

根據ch 是否為大寫字元來回傳1 或0。

intPy_UNICODE_ISTITLE(Py_UCS4ch)¶

根據ch 是否為首字大寫字元來回傳1 或0。

intPy_UNICODE_ISLINEBREAK(Py_UCS4ch)¶

根據ch 是否為換行字元來回傳1 或0。

intPy_UNICODE_ISDECIMAL(Py_UCS4ch)¶

根據ch 是否為十進位字元來回傳1 或0。

intPy_UNICODE_ISDIGIT(Py_UCS4ch)¶

根據ch 是否為數字 (digit) 字元來回傳1 或0。

intPy_UNICODE_ISNUMERIC(Py_UCS4ch)¶

根據ch 是否為數值 (numeric) 字元來回傳1 或0。

intPy_UNICODE_ISALPHA(Py_UCS4ch)¶

根據ch 是否為字母字元來回傳1 或0。

intPy_UNICODE_ISALNUM(Py_UCS4ch)¶

根據ch 是否為字母數字 (alphanumeric) 字元來回傳1 或0。

intPy_UNICODE_ISPRINTABLE(Py_UCS4ch)¶

根據ch 是否為可列印字元（如str.isprintable() 所定義）來回傳1 或0。

這些 API 可用於快速直接字元轉換：

Py_UCS4Py_UNICODE_TOLOWER(Py_UCS4ch)¶

回傳轉換為小寫的ch 字元。

Py_UCS4Py_UNICODE_TOUPPER(Py_UCS4ch)¶

回傳轉換為大寫的ch 字元。

Py_UCS4Py_UNICODE_TOTITLE(Py_UCS4ch)¶

回傳轉換為首字大寫的ch 字元。

intPy_UNICODE_TODECIMAL(Py_UCS4ch)¶

回傳轉換為十進位正整數的ch 字元，若無法轉換則回傳-1。此函式不會引發例外。

intPy_UNICODE_TODIGIT(Py_UCS4ch)¶

回傳轉換為單一數字整數的ch 字元，若無法轉換則回傳-1。此函式不會引發例外。

doublePy_UNICODE_TONUMERIC(Py_UCS4ch)¶

回傳轉換為雙精度浮點數 (double) 的ch 字元，若無法轉換則回傳-1.0。此函式不會引發例外。

這些 API 可用於處理代理字元：

intPy_UNICODE_IS_SURROGATE(Py_UCS4ch)¶

檢查ch 是否為代理字元 (surrogate,0xD800<=ch<=0xDFFF)。

intPy_UNICODE_IS_HIGH_SURROGATE(Py_UCS4ch)¶

檢查ch 是否為高代理字元 (high surrogate,0xD800<=ch<=0xDBFF)。

intPy_UNICODE_IS_LOW_SURROGATE(Py_UCS4ch)¶

檢查ch 是否為低代理字元 (low surrogate,0xDC00<=ch<=0xDFFF)。

Py_UCS4Py_UNICODE_JOIN_SURROGATES(Py_UCS4high,Py_UCS4low)¶

Join two surrogate code points and return a singlePy_UCS4 value.high andlow are respectively the leading and trailing surrogates in asurrogate pair.high must be in the range [0xD800; 0xDBFF] andlow mustbe in the range [0xDC00; 0xDFFF].

Creating and accessing Unicode strings¶

To create Unicode objects and access their basic sequence properties, use theseAPIs:

PyObject*PyUnicode_New(Py_ssize_tsize,Py_UCS4maxchar)¶

回傳值：新的參照。

Create a new Unicode object.maxchar should be the true maximum code pointto be placed in the string. As an approximation, it can be rounded up to thenearest value in the sequence 127, 255, 65535, 1114111.

This is the recommended way to allocate a new Unicode object. Objectscreated using this function are not resizable.

On error, set an exception and returnNULL.

在 3.3 版被加入.

PyObject*PyUnicode_FromKindAndData(intkind,constvoid*buffer,Py_ssize_tsize)¶

回傳值：新的參照。

Create a new Unicode object with the givenkind (possible values arePyUnicode_1BYTE_KIND etc., as returned byPyUnicode_KIND()). Thebuffer must point to an array ofsizeunits of 1, 2 or 4 bytes per character, as given by the kind.

If necessary, the inputbuffer is copied and transformed into thecanonical representation. For example, if thebuffer is a UCS4 string(PyUnicode_4BYTE_KIND) and it consists only of codepoints inthe UCS1 range, it will be transformed into UCS1(PyUnicode_1BYTE_KIND).

在 3.3 版被加入.

PyObject*PyUnicode_FromStringAndSize(constchar*str,Py_ssize_tsize)¶

回傳值：新的參照。 為穩定 ABI 的一部分.

Create a Unicode object from the char bufferstr. The bytes will beinterpreted as being UTF-8 encoded. The buffer is copied into the newobject.The return value might be a shared object, i.e. modification of the data isnot allowed.

此函式在以下情況下會引發SystemError：

• size < 0，

• str 為NULL 且size > 0

在 3.12 版的變更:str ==NULL 且size > 0 不再被允許。

PyObject*PyUnicode_FromString(constchar*str)¶

回傳值：新的參照。 為穩定 ABI 的一部分.

Create a Unicode object from a UTF-8 encoded null-terminated char bufferstr.

PyObject*PyUnicode_FromFormat(constchar*format,...)¶

回傳值：新的參照。 為穩定 ABI 的一部分.

Take a Cprintf()-styleformat string and a variable number ofarguments, calculate the size of the resulting Python Unicode string and returna string with the values formatted into it. The variable arguments must be Ctypes and must correspond exactly to the format characters in theformatASCII-encoded string.

A conversion specifier contains two or more characters and has the followingcomponents, which must occur in this order:

1. The'%' character, which marks the start of the specifier.

2. Conversion flags (optional), which affect the result of some conversiontypes.

3. Minimum field width (optional).If specified as an'*' (asterisk), the actual width is given in thenext argument, which must be of typeint, and the object toconvert comes after the minimum field width and optional precision.

4. Precision (optional), given as a'.' (dot) followed by the precision.If specified as'*' (an asterisk), the actual precision is given inthe next argument, which must be of typeint, and the value toconvert comes after the precision.

5. Length modifier (optional).

6. Conversion type.

The conversion flag characters are:

旗標	含義
0	The conversion will be zero padded for numeric values.
-	The converted value is left adjusted (overrides the0flag if both are given).

The length modifiers for following integer conversions (d,i,o,u,x, orX) specify the type of the argument(int by default):

Modifier	Types
l	long 或unsignedlong
ll	longlong 或unsignedlonglong
j	intmax_t 或uintmax_t
z	size_t 或ssize_t
t	ptrdiff_t

The length modifierl for following conversionss orV specifythat the type of the argument isconstwchar_t*.

The conversion specifiers are:

Conversion Specifier	Type	Comment
%	n/a	字面% 字元。
d,i	Specified by the length modifier	一個有符號 C 整數的十進位表示法。
u	Specified by the length modifier	一個無符號 C 整數的十進位表示法。
o	Specified by the length modifier	一個無符號 C 整數的八進位表示法。
x	Specified by the length modifier	一個無符號 C 整數的十六進位表示法（小寫）。
X	Specified by the length modifier	一個無符號 C 整數的十六進位表示法（大寫）。
c	int	一個單一字元。
s	constchar* 或constwchar_t*	一個以 null 結尾的 C 字元陣列。
p	constvoid*	The hex representation of a C pointer.Mostly equivalent toprintf("%p") except that it is guaranteed tostart with the literal0x regardless of what the platform'sprintf yields.
A	PyObject*	呼叫ascii() 的結果。
U	PyObject*	一個 Unicode 物件。
V	PyObject*、constchar* 或constwchar_t*	A Unicode object (which may beNULL) and a null-terminatedC character array as a second parameter (which will be used,if the first parameter isNULL).
S	PyObject*	呼叫PyObject_Str() 的結果。
R	PyObject*	呼叫PyObject_Repr() 的結果。
T	PyObject*	Get the fully qualified name of an object type;callPyType_GetFullyQualifiedName().
#T	PyObject*	Similar toT format, but use a colon (:) as separator betweenthe module name and the qualified name.
N	PyTypeObject*	Get the fully qualified name of a type;callPyType_GetFullyQualifiedName().
#N	PyTypeObject*	Similar toN format, but use a colon (:) as separator betweenthe module name and the qualified name.

備註

The width formatter unit is number of characters rather than bytes.The precision formatter unit is number of bytes orwchar_titems (if the length modifierl is used) for"%s" and"%V" (if thePyObject* argument isNULL), and a number ofcharacters for"%A","%U","%S","%R" and"%V"(if thePyObject* argument is notNULL).

備註

Unlike to Cprintf() the0 flag has effect even whena precision is given for integer conversions (d,i,u,o,x, orX).

在 3.2 版的變更:新增對"%lld" 和"%llu" 的支援。

在 3.3 版的變更:新增對"%li"、"%lli" 和"%zi" 的支援。

在 3.4 版的變更:新增對"%s"、"%A"、"%U"、"%V"、"%S"、"%R" 的寬度和精確度格式化支援。

在 3.12 版的變更:Support for conversion specifierso andX.Support for length modifiersj andt.Length modifiers are now applied to all integer conversions.Length modifierl is now applied to conversion specifierss andV.Support for variable width and precision*.Support for flag-.

An unrecognized format character now sets aSystemError.In previous versions it caused all the rest of the format string to becopied as-is to the result string, and any extra arguments discarded.

在 3.13 版的變更:新增對%T、%#T、%N 和%#N 格式的支援。

PyObject*PyUnicode_FromFormatV(constchar*format,va_listvargs)¶

回傳值：新的參照。 為穩定 ABI 的一部分.

Identical toPyUnicode_FromFormat() except that it takes exactly twoarguments.

PyObject*PyUnicode_FromObject(PyObject*obj)¶

回傳值：新的參照。 為穩定 ABI 的一部分.

Copy an instance of a Unicode subtype to a new true Unicode object ifnecessary. Ifobj is already a true Unicode object (not a subtype),return a newstrong reference to the object.

Objects other than Unicode or its subtypes will cause aTypeError.

PyObject*PyUnicode_FromOrdinal(intordinal)¶

回傳值：新的參照。 為穩定 ABI 的一部分.

Create a Unicode Object from the given Unicode code pointordinal.

The ordinal must be inrange(0x110000). AValueError israised in the case it is not.

PyObject*PyUnicode_FromEncodedObject(PyObject*obj,constchar*encoding,constchar*errors)¶

回傳值：新的參照。 為穩定 ABI 的一部分.

Decode an encoded objectobj to a Unicode object.

bytes,bytearray and otherbytes-like objectsare decoded according to the givenencoding and using the error handlingdefined byerrors. Both can beNULL to have the interface use the defaultvalues (see內建編解碼器 for details).

All other objects, including Unicode objects, cause aTypeError to beset.

The API returnsNULL if there was an error. The caller is responsible fordecref'ing the returned objects.

PyObject*PyUnicode_BuildEncodingMap(PyObject*string)¶

回傳值：新的參照。 為穩定 ABI 的一部分.

Return a mapping suitable for decoding a custom single-byte encoding.Given a Unicode stringstring of up to 256 characters representing an encodingtable, returns either a compact internal mapping object or a dictionarymapping character ordinals to byte values. Raises aTypeError andreturnNULL on invalid input... versionadded:: 3.2

constchar*PyUnicode_GetDefaultEncoding(void)¶

為穩定 ABI 的一部分.

Return the name of the default string encoding,"utf-8".Seesys.getdefaultencoding().

The returned string does not need to be freed, and is validuntil interpreter shutdown.

Py_ssize_tPyUnicode_GetLength(PyObject*unicode)¶

為穩定 ABI 的一部分 自 3.7 版本開始.

Return the length of the Unicode object, in code points.

發生錯誤時，設定例外並回傳-1。

在 3.3 版被加入.

Py_ssize_tPyUnicode_CopyCharacters(PyObject*to,Py_ssize_tto_start,PyObject*from,Py_ssize_tfrom_start,Py_ssize_thow_many)¶

Copy characters from one Unicode object into another. This function performscharacter conversion when necessary and falls back tomemcpy() ifpossible. Returns-1 and sets an exception on error, otherwise returnsthe number of copied characters.

在 3.3 版被加入.

Py_ssize_tPyUnicode_Fill(PyObject*unicode,Py_ssize_tstart,Py_ssize_tlength,Py_UCS4fill_char)¶

Fill a string with a character: writefill_char intounicode[start:start+length].

Fail iffill_char is bigger than the string maximum character, or if thestring has more than 1 reference.

Return the number of written character, or return-1 and raise anexception on error.

在 3.3 版被加入.

intPyUnicode_WriteChar(PyObject*unicode,Py_ssize_tindex,Py_UCS4character)¶

為穩定 ABI 的一部分 自 3.7 版本開始.

Write a character to a string. The string must have been created throughPyUnicode_New(). Since Unicode strings are supposed to be immutable,the string must not be shared, or have been hashed yet.

This function checks thatunicode is a Unicode object, that the index isnot out of bounds, and that the object can be modified safely (i.e. that itits reference count is one).

成功時回傳0，發生錯誤時設定例外並回傳-1。

在 3.3 版被加入.

Py_UCS4PyUnicode_ReadChar(PyObject*unicode,Py_ssize_tindex)¶

為穩定 ABI 的一部分 自 3.7 版本開始.

Read a character from a string. This function checks thatunicode is aUnicode object and the index is not out of bounds, in contrast toPyUnicode_READ_CHAR(), which performs no error checking.

成功時回傳字元，發生錯誤時設定例外並回傳-1。

在 3.3 版被加入.

PyObject*PyUnicode_Substring(PyObject*unicode,Py_ssize_tstart,Py_ssize_tend)¶

回傳值：新的參照。 為穩定 ABI 的一部分 自 3.7 版本開始.

Return a substring ofunicode, from character indexstart (included) tocharacter indexend (excluded). Negative indices are not supported.On error, set an exception and returnNULL.

在 3.3 版被加入.

Py_UCS4*PyUnicode_AsUCS4(PyObject*unicode,Py_UCS4*buffer,Py_ssize_tbuflen,intcopy_null)¶

為穩定 ABI 的一部分 自 3.7 版本開始.

Copy the stringunicode into a UCS4 buffer, including a null character, ifcopy_null is set. ReturnsNULL and sets an exception on error (inparticular, aSystemError ifbuflen is smaller than the length ofunicode).buffer is returned on success.

在 3.3 版被加入.

Py_UCS4*PyUnicode_AsUCS4Copy(PyObject*unicode)¶

為穩定 ABI 的一部分 自 3.7 版本開始.

Copy the stringunicode into a new UCS4 buffer that is allocated usingPyMem_Malloc(). If this fails,NULL is returned with aMemoryError set. The returned buffer always has an extranull code point appended.

在 3.3 版被加入.

Locale Encoding¶

The current locale encoding can be used to decode text from the operatingsystem.

PyObject*PyUnicode_DecodeLocaleAndSize(constchar*str,Py_ssize_tlength,constchar*errors)¶

回傳值：新的參照。 為穩定 ABI 的一部分 自 3.7 版本開始.

Decode a string from UTF-8 on Android and VxWorks, or from the currentlocale encoding on other platforms. The supportederror handlers are"strict" and"surrogateescape"(PEP 383). The decoder uses"strict" error handler iferrors isNULL.str must end with a null character butcannot contain embedded null characters.

UsePyUnicode_DecodeFSDefaultAndSize() to decode a string fromthefilesystem encoding and error handler.

此函式會忽略Python UTF-8 模式。

也參考

Py_DecodeLocale() 函式。

在 3.3 版被加入.

在 3.7 版的變更:The function now also uses the current locale encoding for thesurrogateescape error handler, except on Android. Previously,Py_DecodeLocale()was used for thesurrogateescape, and the current locale encoding wasused forstrict.

PyObject*PyUnicode_DecodeLocale(constchar*str,constchar*errors)¶

回傳值：新的參照。 為穩定 ABI 的一部分 自 3.7 版本開始.

類似於PyUnicode_DecodeLocaleAndSize()，但使用strlen() 計算字串長度。

在 3.3 版被加入.

PyObject*PyUnicode_EncodeLocale(PyObject*unicode,constchar*errors)¶

回傳值：新的參照。 為穩定 ABI 的一部分 自 3.7 版本開始.

Encode a Unicode object to UTF-8 on Android and VxWorks, or to the currentlocale encoding on other platforms. Thesupported error handlers are"strict" and"surrogateescape"(PEP 383). The encoder uses"strict" error handler iferrors isNULL. Return abytes object.unicode cannotcontain embedded null characters.

UsePyUnicode_EncodeFSDefault() to encode a string to thefilesystem encoding and error handler.

此函式會忽略Python UTF-8 模式。

也參考

Py_EncodeLocale() 函式。

在 3.3 版被加入.

在 3.7 版的變更:The function now also uses the current locale encoding for thesurrogateescape error handler, except on Android. Previously,Py_EncodeLocale()was used for thesurrogateescape, and the current locale encoding wasused forstrict.

檔案系統編碼¶

Functions encoding to and decoding from thefilesystem encoding anderror handler (PEP 383 andPEP 529).

To encode file names tobytes during argument parsing, the"O&"converter should be used, passingPyUnicode_FSConverter() as theconversion function:

intPyUnicode_FSConverter(PyObject*obj,void*result)¶

為穩定 ABI 的一部分.

PyArg_Parse* converter: encodestr objects -- obtained directly orthrough theos.PathLike interface -- tobytes usingPyUnicode_EncodeFSDefault();bytes objects are output as-is.result must be an address of a C variable of typePyObject*(orPyBytesObject*).On success, set the variable to a newstrong reference toabytes object which must be releasedwhen it is no longer used and return a non-zero value(Py_CLEANUP_SUPPORTED).Embedded null bytes are not allowed in the result.On failure, return0 with an exception set.

Ifobj isNULL, the function releases a strong referencestored in the variable referred byresult and returns1.

在 3.1 版被加入.

在 3.6 版的變更:接受一個path-like object。

To decode file names tostr during argument parsing, the"O&"converter should be used, passingPyUnicode_FSDecoder() as theconversion function:

intPyUnicode_FSDecoder(PyObject*obj,void*result)¶

為穩定 ABI 的一部分.

PyArg_Parse* converter: decodebytes objects -- obtained eitherdirectly or indirectly through theos.PathLike interface -- tostr usingPyUnicode_DecodeFSDefaultAndSize();strobjects are output as-is.result must be an address of a C variable of typePyObject*(orPyUnicodeObject*).On success, set the variable to a newstrong reference toaUnicode object which must be releasedwhen it is no longer used and return a non-zero value(Py_CLEANUP_SUPPORTED).Embedded null characters are not allowed in the result.On failure, return0 with an exception set.

Ifobj isNULL, release the strong referenceto the object referred to byresult and return1.

在 3.2 版被加入.

在 3.6 版的變更:接受一個path-like object。

PyObject*PyUnicode_DecodeFSDefaultAndSize(constchar*str,Py_ssize_tsize)¶

回傳值：新的參照。 為穩定 ABI 的一部分.

Decode a string from thefilesystem encoding and error handler.

If you need to decode a string from the current locale encoding, usePyUnicode_DecodeLocaleAndSize().

也參考

Py_DecodeLocale() 函式。

在 3.6 版的變更:Thefilesystem error handler is now used.

PyObject*PyUnicode_DecodeFSDefault(constchar*str)¶

回傳值：新的參照。 為穩定 ABI 的一部分.

Decode a null-terminated string from thefilesystem encoding anderror handler.

如果字串長度已知，請使用PyUnicode_DecodeFSDefaultAndSize()。

在 3.6 版的變更:Thefilesystem error handler is now used.

PyObject*PyUnicode_EncodeFSDefault(PyObject*unicode)¶

回傳值：新的參照。 為穩定 ABI 的一部分.

Encode a Unicode object to thefilesystem encoding and errorhandler, and returnbytes. Note that the resultingbytesobject can contain null bytes.

If you need to encode a string to the current locale encoding, usePyUnicode_EncodeLocale().

也參考

Py_EncodeLocale() 函式。

在 3.2 版被加入.

在 3.6 版的變更:Thefilesystem error handler is now used.

wchar_t 支援¶

對支援wchar_t 的平台提供支援：

PyObject*PyUnicode_FromWideChar(constwchar_t*wstr,Py_ssize_tsize)¶

回傳值：新的參照。 為穩定 ABI 的一部分.

Create a Unicode object from thewchar_t bufferwstr of the givensize.Passing-1 as thesize indicates that the function must itself compute the length,usingwcslen().ReturnNULL on failure.

Py_ssize_tPyUnicode_AsWideChar(PyObject*unicode,wchar_t*wstr,Py_ssize_tsize)¶

為穩定 ABI 的一部分.

Copy the Unicode object contents into thewchar_t bufferwstr. At mostsizewchar_t characters are copied (excluding a possibly trailingnull termination character). Return the number ofwchar_t characterscopied or-1 in case of an error.

Whenwstr isNULL, instead return thesize that would be requiredto store all ofunicode including a terminating null.

Note that the resultingwchar_t*string may or may not be null-terminated. It is the responsibility of the callerto make sure that thewchar_t* string is null-terminated in case this isrequired by the application. Also, note that thewchar_t* stringmight contain null characters, which would cause the string to be truncatedwhen used with most C functions.

wchar_t*PyUnicode_AsWideCharString(PyObject*unicode,Py_ssize_t*size)¶

為穩定 ABI 的一部分 自 3.7 版本開始.

Convert the Unicode object to a wide character string. The output stringalways ends with a null character. Ifsize is notNULL, write the numberof wide characters (excluding the trailing null termination character) into*size. Note that the resultingwchar_t string might containnull characters, which would cause the string to be truncated when used withmost C functions. Ifsize isNULL and thewchar_t* stringcontains null characters aValueError is raised.

Returns a buffer allocated byPyMem_New (usePyMem_Free() to free it) on success. On error, returnsNULLand*size is undefined. Raises aMemoryError if memory allocationis failed.

在 3.2 版被加入.

在 3.7 版的變更:Raises aValueError ifsize isNULL and thewchar_t*string contains null characters.

泛用編解碼器¶

這些是泛用編解碼器的 API：

PyObject*PyUnicode_Decode(constchar*str,Py_ssize_tsize,constchar*encoding,constchar*errors)¶

回傳值：新的參照。 為穩定 ABI 的一部分.

Create a Unicode object by decodingsize bytes of the encoded stringstr.encoding anderrors have the same meaning as the parameters of the same namein thestr() built-in function. The codec to be used is looked upusing the Python codec registry. ReturnNULL if an exception was raised bythe codec.

PyObject*PyUnicode_AsEncodedString(PyObject*unicode,constchar*encoding,constchar*errors)¶

回傳值：新的參照。 為穩定 ABI 的一部分.

Encode a Unicode object and return the result as Python bytes object.encoding anderrors have the same meaning as the parameters of the samename in the Unicodeencode() method. The codec to be used is looked upusing the Python codec registry. ReturnNULL if an exception was raised bythe codec.

UTF-8 編解碼器¶

這些是 UTF-8 編解碼器的 API：

PyObject*PyUnicode_DecodeUTF8(constchar*str,Py_ssize_tsize,constchar*errors)¶

回傳值：新的參照。 為穩定 ABI 的一部分.

Create a Unicode object by decodingsize bytes of the UTF-8 encoded stringstr. ReturnNULL if an exception was raised by the codec.

PyObject*PyUnicode_DecodeUTF8Stateful(constchar*str,Py_ssize_tsize,constchar*errors,Py_ssize_t*consumed)¶

回傳值：新的參照。 為穩定 ABI 的一部分.

Ifconsumed isNULL, behave likePyUnicode_DecodeUTF8(). Ifconsumed is notNULL, trailing incomplete UTF-8 byte sequences will not betreated as an error. Those bytes will not be decoded and the number of bytesthat have been decoded will be stored inconsumed.

PyObject*PyUnicode_AsUTF8String(PyObject*unicode)¶

回傳值：新的參照。 為穩定 ABI 的一部分.

Encode a Unicode object using UTF-8 and return the result as Python bytesobject. Error handling is "strict". ReturnNULL if an exception wasraised by the codec.

The function fails if the string contains surrogate code points(U+D800 -U+DFFF).

constchar*PyUnicode_AsUTF8AndSize(PyObject*unicode,Py_ssize_t*size)¶

為穩定 ABI 的一部分 自 3.10 版本開始.

Return a pointer to the UTF-8 encoding of the Unicode object, andstore the size of the encoded representation (in bytes) insize. Thesize argument can beNULL; in this case no size will be stored. Thereturned buffer always has an extra null byte appended (not included insize), regardless of whether there are any other null code points.

發生錯誤時，設定例外並將size 設為-1（如果不是 NULL），並回傳NULL。

The function fails if the string contains surrogate code points(U+D800 -U+DFFF).

This caches the UTF-8 representation of the string in the Unicode object, andsubsequent calls will return a pointer to the same buffer. The caller is notresponsible for deallocating the buffer. The buffer is deallocated andpointers to it become invalid when the Unicode object is garbage collected.

在 3.3 版被加入.

在 3.7 版的變更:回傳型別現在是constchar* 而不是char*。

在 3.10 版的變更:This function is a part of thelimited API.

constchar*PyUnicode_AsUTF8(PyObject*unicode)¶

與PyUnicode_AsUTF8AndSize() 類似，但不儲存大小。

警告

This function does not have any special behavior fornull characters embedded withinunicode. As a result, strings containing null characters will remain in the returnedstring, which some C functions might interpret as the end of the string, leading totruncation. If truncation is an issue, it is recommended to usePyUnicode_AsUTF8AndSize()instead.

在 3.3 版被加入.

在 3.7 版的變更:回傳型別現在是constchar* 而不是char*。

UTF-32 編解碼器¶

這些是 UTF-32 編解碼器的 API：

PyObject*PyUnicode_DecodeUTF32(constchar*str,Py_ssize_tsize,constchar*errors,int*byteorder)¶

回傳值：新的參照。 為穩定 ABI 的一部分.

Decodesize bytes from a UTF-32 encoded buffer string and return thecorresponding Unicode object.errors (if non-NULL) defines the errorhandling. It defaults to "strict".

Ifbyteorder is non-NULL, the decoder starts decoding using the given byteorder:

*byteorder==-1:littleendian*byteorder==0:nativeorder*byteorder==1:bigendian

If*byteorder is zero, and the first four bytes of the input data are abyte order mark (BOM), the decoder switches to this byte order and the BOM isnot copied into the resulting Unicode string. If*byteorder is-1 or1, any byte order mark is copied to the output.

After completion,*byteorder is set to the current byte order at the endof input data.

Ifbyteorder isNULL, the codec starts in native order mode.

如果編解碼器引發例外則回傳NULL。

PyObject*PyUnicode_DecodeUTF32Stateful(constchar*str,Py_ssize_tsize,constchar*errors,int*byteorder,Py_ssize_t*consumed)¶

回傳值：新的參照。 為穩定 ABI 的一部分.

Ifconsumed isNULL, behave likePyUnicode_DecodeUTF32(). Ifconsumed is notNULL,PyUnicode_DecodeUTF32Stateful() will not treattrailing incomplete UTF-32 byte sequences (such as a number of bytes not divisibleby four) as an error. Those bytes will not be decoded and the number of bytesthat have been decoded will be stored inconsumed.

PyObject*PyUnicode_AsUTF32String(PyObject*unicode)¶

回傳值：新的參照。 為穩定 ABI 的一部分.

Return a Python byte string using the UTF-32 encoding in native byteorder. The string always starts with a BOM mark. Error handling is "strict".ReturnNULL if an exception was raised by the codec.

UTF-16 編解碼器¶

這些是 UTF-16 編解碼器的 API：

PyObject*PyUnicode_DecodeUTF16(constchar*str,Py_ssize_tsize,constchar*errors,int*byteorder)¶

回傳值：新的參照。 為穩定 ABI 的一部分.

Decodesize bytes from a UTF-16 encoded buffer string and return thecorresponding Unicode object.errors (if non-NULL) defines the errorhandling. It defaults to "strict".

Ifbyteorder is non-NULL, the decoder starts decoding using the given byteorder:

*byteorder==-1:littleendian*byteorder==0:nativeorder*byteorder==1:bigendian

If*byteorder is zero, and the first two bytes of the input data are abyte order mark (BOM), the decoder switches to this byte order and the BOM isnot copied into the resulting Unicode string. If*byteorder is-1 or1, any byte order mark is copied to the output (where it will result ineither a\ufeff or a\ufffe character).

After completion,*byteorder is set to the current byte order at the endof input data.

Ifbyteorder isNULL, the codec starts in native order mode.

如果編解碼器引發例外則回傳NULL。

PyObject*PyUnicode_DecodeUTF16Stateful(constchar*str,Py_ssize_tsize,constchar*errors,int*byteorder,Py_ssize_t*consumed)¶

回傳值：新的參照。 為穩定 ABI 的一部分.

Ifconsumed isNULL, behave likePyUnicode_DecodeUTF16(). Ifconsumed is notNULL,PyUnicode_DecodeUTF16Stateful() will not treattrailing incomplete UTF-16 byte sequences (such as an odd number of bytes or asplit surrogate pair) as an error. Those bytes will not be decoded and thenumber of bytes that have been decoded will be stored inconsumed.

PyObject*PyUnicode_AsUTF16String(PyObject*unicode)¶

回傳值：新的參照。 為穩定 ABI 的一部分.

Return a Python byte string using the UTF-16 encoding in native byteorder. The string always starts with a BOM mark. Error handling is "strict".ReturnNULL if an exception was raised by the codec.

UTF-7 編解碼器¶

這些是 UTF-7 編解碼器的 API：

PyObject*PyUnicode_DecodeUTF7(constchar*str,Py_ssize_tsize,constchar*errors)¶

回傳值：新的參照。 為穩定 ABI 的一部分.

Create a Unicode object by decodingsize bytes of the UTF-7 encoded stringstr. ReturnNULL if an exception was raised by the codec.

PyObject*PyUnicode_DecodeUTF7Stateful(constchar*str,Py_ssize_tsize,constchar*errors,Py_ssize_t*consumed)¶

回傳值：新的參照。 為穩定 ABI 的一部分.

Ifconsumed isNULL, behave likePyUnicode_DecodeUTF7(). Ifconsumed is notNULL, trailing incomplete UTF-7 base-64 sections will notbe treated as an error. Those bytes will not be decoded and the number ofbytes that have been decoded will be stored inconsumed.

Unicode-Escape Codecs¶

These are the "Unicode Escape" codec APIs:

PyObject*PyUnicode_DecodeUnicodeEscape(constchar*str,Py_ssize_tsize,constchar*errors)¶

回傳值：新的參照。 為穩定 ABI 的一部分.

Create a Unicode object by decodingsize bytes of the Unicode-Escape encodedstringstr. ReturnNULL if an exception was raised by the codec.

PyObject*PyUnicode_AsUnicodeEscapeString(PyObject*unicode)¶

回傳值：新的參照。 為穩定 ABI 的一部分.

Encode a Unicode object using Unicode-Escape and return the result as abytes object. Error handling is "strict". ReturnNULL if an exception wasraised by the codec.

Raw-Unicode-Escape Codecs¶

These are the "Raw Unicode Escape" codec APIs:

PyObject*PyUnicode_DecodeRawUnicodeEscape(constchar*str,Py_ssize_tsize,constchar*errors)¶

回傳值：新的參照。 為穩定 ABI 的一部分.

Create a Unicode object by decodingsize bytes of the Raw-Unicode-Escapeencoded stringstr. ReturnNULL if an exception was raised by the codec.

PyObject*PyUnicode_AsRawUnicodeEscapeString(PyObject*unicode)¶

回傳值：新的參照。 為穩定 ABI 的一部分.

Encode a Unicode object using Raw-Unicode-Escape and return the result asa bytes object. Error handling is "strict". ReturnNULL if an exceptionwas raised by the codec.

Latin-1 編解碼器¶

These are the Latin-1 codec APIs: Latin-1 corresponds to the first 256 Unicodeordinals and only these are accepted by the codecs during encoding.

PyObject*PyUnicode_DecodeLatin1(constchar*str,Py_ssize_tsize,constchar*errors)¶

回傳值：新的參照。 為穩定 ABI 的一部分.

Create a Unicode object by decodingsize bytes of the Latin-1 encoded stringstr. ReturnNULL if an exception was raised by the codec.

PyObject*PyUnicode_AsLatin1String(PyObject*unicode)¶

回傳值：新的參照。 為穩定 ABI 的一部分.

Encode a Unicode object using Latin-1 and return the result as Python bytesobject. Error handling is "strict". ReturnNULL if an exception wasraised by the codec.

ASCII 編解碼器¶

These are the ASCII codec APIs. Only 7-bit ASCII data is accepted. All othercodes generate errors.

PyObject*PyUnicode_DecodeASCII(constchar*str,Py_ssize_tsize,constchar*errors)¶

回傳值：新的參照。 為穩定 ABI 的一部分.

Create a Unicode object by decodingsize bytes of the ASCII encoded stringstr. ReturnNULL if an exception was raised by the codec.

PyObject*PyUnicode_AsASCIIString(PyObject*unicode)¶

回傳值：新的參照。 為穩定 ABI 的一部分.

Encode a Unicode object using ASCII and return the result as Python bytesobject. Error handling is "strict". ReturnNULL if an exception wasraised by the codec.

Character Map Codecs¶

This codec is special in that it can be used to implement many different codecs(and this is in fact what was done to obtain most of the standard codecsincluded in theencodings package). The codec uses mappings to encode anddecode characters. The mapping objects provided must support the__getitem__() mapping interface; dictionaries and sequences work well.

這些是對映編解碼器的 API：

PyObject*PyUnicode_DecodeCharmap(constchar*str,Py_ssize_tlength,PyObject*mapping,constchar*errors)¶

回傳值：新的參照。 為穩定 ABI 的一部分.

Create a Unicode object by decodingsize bytes of the encoded stringstrusing the givenmapping object. ReturnNULL if an exception was raisedby the codec.

Ifmapping isNULL, Latin-1 decoding will be applied. Elsemapping must map bytes ordinals (integers in the range from 0 to 255)to Unicode strings, integers (which are then interpreted as Unicodeordinals) orNone. Unmapped data bytes -- ones which cause aLookupError, as well as ones which get mapped toNone,0xFFFE or'\ufffe', are treated as undefined mappings and causean error.

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

回傳值：新的參照。 為穩定 ABI 的一部分.

Encode a Unicode object using the givenmapping object and return theresult as a bytes object. Error handling is "strict". ReturnNULL if anexception was raised by the codec.

Themapping object must map Unicode ordinal integers to bytes objects,integers in the range from 0 to 255 orNone. Unmapped characterordinals (ones which cause aLookupError) as well as mapped toNone are treated as "undefined mapping" and cause an error.

The following codec API is special in that maps Unicode to Unicode.

PyObject*PyUnicode_Translate(PyObject*unicode,PyObject*table,constchar*errors)¶

回傳值：新的參照。 為穩定 ABI 的一部分.

Translate a string by applying a character mapping table to it and return theresulting Unicode object. ReturnNULL if an exception was raised by thecodec.

The mapping table must map Unicode ordinal integers to Unicode ordinal integersorNone (causing deletion of the character).

Mapping tables need only provide the__getitem__() interface; dictionariesand sequences work well. Unmapped character ordinals (ones which cause aLookupError) are left untouched and are copied as-is.

errors has the usual meaning for codecs. It may beNULL which indicates touse the default error handling.

Windows 的 MBCS 編解碼器¶

These are the MBCS codec APIs. They are currently only available on Windows anduse the Win32 MBCS converters to implement the conversions. Note that MBCS (orDBCS) is a class of encodings, not just one. The target encoding is defined bythe user settings on the machine running the codec.

PyObject*PyUnicode_DecodeMBCS(constchar*str,Py_ssize_tsize,constchar*errors)¶

回傳值：新的參照。 為穩定 ABI 的一部分 on Windows 自 3.7 版本開始.

Create a Unicode object by decodingsize bytes of the MBCS encoded stringstr.ReturnNULL if an exception was raised by the codec.

PyObject*PyUnicode_DecodeMBCSStateful(constchar*str,Py_ssize_tsize,constchar*errors,Py_ssize_t*consumed)¶

回傳值：新的參照。 為穩定 ABI 的一部分 on Windows 自 3.7 版本開始.

Ifconsumed isNULL, behave likePyUnicode_DecodeMBCS(). Ifconsumed is notNULL,PyUnicode_DecodeMBCSStateful() will not decodetrailing lead byte and the number of bytes that have been decoded will be storedinconsumed.

PyObject*PyUnicode_DecodeCodePageStateful(intcode_page,constchar*str,Py_ssize_tsize,constchar*errors,Py_ssize_t*consumed)¶

回傳值：新的參照。 為穩定 ABI 的一部分 on Windows 自 3.7 版本開始.

Similar toPyUnicode_DecodeMBCSStateful(), except uses the code pagespecified bycode_page.

PyObject*PyUnicode_AsMBCSString(PyObject*unicode)¶

回傳值：新的參照。 為穩定 ABI 的一部分 on Windows 自 3.7 版本開始.

Encode a Unicode object using MBCS and return the result as Python bytesobject. Error handling is "strict". ReturnNULL if an exception wasraised by the codec.

PyObject*PyUnicode_EncodeCodePage(intcode_page,PyObject*unicode,constchar*errors)¶

回傳值：新的參照。 為穩定 ABI 的一部分 on Windows 自 3.7 版本開始.

Encode the Unicode object using the specified code page and return a Pythonbytes object. ReturnNULL if an exception was raised by the codec. UseCP_ACP code page to get the MBCS encoder.

在 3.3 版被加入.

Methods & Slots¶