`unicode.md`

1002 строк · 66.7 КБ · обычная страница · сырой текст · скачать
1> **Источник:** https://python-all.ru/3.0/c-api/unicode.html2>3> «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor.45---67# Объекты Unicode и кодеки89## Объекты Unicode1011Это основные типы объектов Unicode, используемые в реализации Unicode в Python:1213**\[Py\_UNICODE\]`Py_UNICODE`**1415Этот тип представляет тип хранения, который используется внутри Python в качестве основы для хранения порядковых номеров символов Unicode. В стандартной сборке Python используется 16-битный тип для1617[`Py_UNICODE`](https://python-all.ru/3.0/c-api/unicode.html#Py_UNICODE)1819, и значения Unicode хранятся внутри в UCS2. Также возможна сборка Python с UCS4 (большинство современных дистрибутивов Linux поставляются с UCS4-сборками Python). В таких сборках используется 32-битный тип для2021[`Py_UNICODE`](https://python-all.ru/3.0/c-api/unicode.html#Py_UNICODE)2223, и данные Unicode хранятся внутри в UCS4. На платформах, где2425`wchar_t`2627доступен и совместим с выбранным вариантом сборки Unicode Python,2829[`Py_UNICODE`](https://python-all.ru/3.0/c-api/unicode.html#Py_UNICODE)3031является псевдонимом typedef для3233`wchar_t`3435для улучшения совместимости с нативной платформой. На всех остальных платформах3637[`Py_UNICODE`](https://python-all.ru/3.0/c-api/unicode.html#Py_UNICODE)3839является псевдонимом typedef для4041`unsigned short`4243(UCS2) или4445`unsigned long`4647(UCS4).4849Обратите внимание, что сборки Python с UCS2 и UCS4 не являются двоично совместимыми. Учитывайте это при написании расширений или интерфейсов.5051**\[PyUnicodeObject\]`PyUnicodeObject`**5253Этот подтип5455[`PyObject`](https://python-all.ru/3.0/c-api/structures.html#PyObject)5657представляет объект Unicode в Python.5859**\[PyUnicode\_Type\][PyTypeObject](https://python-all.ru/3.0/c-api/type.html#PyTypeObject) `PyUnicode_Type`**6061Этот экземпляр6263[`PyTypeObject`](https://python-all.ru/3.0/c-api/type.html#PyTypeObject)6465представляет тип Unicode в Python. Он доступен в коде Python как6667`str`6869.7071Следующие API на самом деле являются макросами C и могут использоваться для быстрых проверок и доступа к внутренним данным Unicode объектов только для чтения:7273**\[PyUnicode\_Check\]int `PyUnicode_Check`([PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject) *\*o*)**7475Возвращает true, если объект7677*o*7879является объектом Unicode или экземпляром подтипа Unicode.8081**\[PyUnicode\_CheckExact\]int `PyUnicode_CheckExact`([PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject) *\*o*)**8283Возвращает true, если объект8485*o*8687является объектом Unicode, но не экземпляром подтипа.8889**\[PyUnicode\_GET\_SIZE\]Py\_ssize\_t `PyUnicode_GET_SIZE`([PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject) *\*o*)**9091Возвращает размер объекта.9293*o*9495должен быть9697[`PyUnicodeObject`](https://python-all.ru/3.0/c-api/unicode.html#PyUnicodeObject)9899(не проверяется).100101**\[PyUnicode\_GET\_DATA\_SIZE\]Py\_ssize\_t `PyUnicode_GET_DATA_SIZE`([PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject) *\*o*)**102103Возвращает размер внутреннего буфера объекта в байтах.104105*o*106107должен быть108109[`PyUnicodeObject`](https://python-all.ru/3.0/c-api/unicode.html#PyUnicodeObject)110111(не проверяется).112113**\[PyUnicode\_AS\_UNICODE\][Py\_UNICODE](https://python-all.ru/3.0/c-api/unicode.html#Py_UNICODE)\* `PyUnicode_AS_UNICODE`([PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject) *\*o*)**114115Возвращает указатель на внутренний буфер116117[`Py_UNICODE`](https://python-all.ru/3.0/c-api/unicode.html#Py_UNICODE)118119объекта.120121*o*122123должен быть124125[`PyUnicodeObject`](https://python-all.ru/3.0/c-api/unicode.html#PyUnicodeObject)126127(не проверяется).128129**\[PyUnicode\_AS\_DATA\]const char\* `PyUnicode_AS_DATA`([PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject) *\*o*)**130131Возвращает указатель на внутренний буфер объекта.132133*o*134135должен быть136137[`PyUnicodeObject`](https://python-all.ru/3.0/c-api/unicode.html#PyUnicodeObject)138139(не проверяется).140141**\[PyUnicode\_ClearFreeList\]int `PyUnicode_ClearFreeList`(void)**142143Очищает список свободных элементов. Возвращает общее количество освобождённых элементов.144145Unicode предоставляет множество различных свойств символов. Наиболее востребованные из них доступны через следующие макросы, которые сопоставляются с функциями на C в зависимости от конфигурации Python.146147**\[Py\_UNICODE\_ISSPACE\]int `Py_UNICODE_ISSPACE`([Py\_UNICODE](https://python-all.ru/3.0/c-api/unicode.html#Py_UNICODE) *ch*)**148149Возвращает 1 или 0 в зависимости от того, является ли150151*ch*152153пробельным символом.154155**\[Py\_UNICODE\_ISLOWER\]int `Py_UNICODE_ISLOWER`([Py\_UNICODE](https://python-all.ru/3.0/c-api/unicode.html#Py_UNICODE) *ch*)**156157Возвращает 1 или 0 в зависимости от того, является ли158159*ch*160161символом нижнего регистра.162163**\[Py\_UNICODE\_ISUPPER\]int `Py_UNICODE_ISUPPER`([Py\_UNICODE](https://python-all.ru/3.0/c-api/unicode.html#Py_UNICODE) *ch*)**164165Возвращает 1 или 0 в зависимости от того, является ли166167*ch*168169символом верхнего регистра.170171**\[Py\_UNICODE\_ISTITLE\]int `Py_UNICODE_ISTITLE`([Py\_UNICODE](https://python-all.ru/3.0/c-api/unicode.html#Py_UNICODE) *ch*)**172173Возвращает 1 или 0 в зависимости от того, является ли174175*ch*176177символом в регистре заголовка.178179**\[Py\_UNICODE\_ISLINEBREAK\]int `Py_UNICODE_ISLINEBREAK`([Py\_UNICODE](https://python-all.ru/3.0/c-api/unicode.html#Py_UNICODE) *ch*)**180181Возвращает 1 или 0 в зависимости от того, является ли182183*ch*184185символом разрыва строки.186187**\[Py\_UNICODE\_ISDECIMAL\]int `Py_UNICODE_ISDECIMAL`([Py\_UNICODE](https://python-all.ru/3.0/c-api/unicode.html#Py_UNICODE) *ch*)**188189Возвращает 1 или 0 в зависимости от того, является ли190191*ch*192193десятичной цифрой.194195**\[Py\_UNICODE\_ISDIGIT\]int `Py_UNICODE_ISDIGIT`([Py\_UNICODE](https://python-all.ru/3.0/c-api/unicode.html#Py_UNICODE) *ch*)**196197Возвращает 1 или 0 в зависимости от того, является ли198199*ch*200201цифровым символом.202203**\[Py\_UNICODE\_ISNUMERIC\]int `Py_UNICODE_ISNUMERIC`([Py\_UNICODE](https://python-all.ru/3.0/c-api/unicode.html#Py_UNICODE) *ch*)**204205Возвращает 1 или 0 в зависимости от того, является ли206207*ch*208209числовым символом.210211**\[Py\_UNICODE\_ISALPHA\]int `Py_UNICODE_ISALPHA`([Py\_UNICODE](https://python-all.ru/3.0/c-api/unicode.html#Py_UNICODE) *ch*)**212213Возвращает 1 или 0 в зависимости от того, является ли214215*ch*216217буквенным символом.218219**\[Py\_UNICODE\_ISALNUM\]int `Py_UNICODE_ISALNUM`([Py\_UNICODE](https://python-all.ru/3.0/c-api/unicode.html#Py_UNICODE) *ch*)**220221Возвращает 1 или 0 в зависимости от того, является ли222223*ch*224225буквенно-цифровым символом.226227**\[Py\_UNICODE\_ISPRINTABLE\]int `Py_UNICODE_ISPRINTABLE`([Py\_UNICODE](https://python-all.ru/3.0/c-api/unicode.html#Py_UNICODE) *ch*)**228229Возвращает 1 или 0 в зависимости от того, является ли230231*ch*232233печатаемым символом. Непечатаемые символы – это символы, определённые в базе данных Unicode как «Other» или «Separator», за исключением пробела ASCII (0x20), который считается печатаемым. (Обратите внимание, что печатаемые символы в этом контексте – это те, которые не должны экранироваться при вызове234235[`repr()`](https://python-all.ru/3.0/library/functions.html#repr)236237для строки. Это не влияет на обработку строк, записываемых в238239[`sys.stdout`](https://python-all.ru/3.0/library/sys.html#sys.stdout)240241или242243[`sys.stderr`](https://python-all.ru/3.0/library/sys.html#sys.stderr)244245.)246247Эти API можно использовать для быстрых прямых преобразований символов:248249**\[Py\_UNICODE\_TOLOWER\][Py\_UNICODE](https://python-all.ru/3.0/c-api/unicode.html#Py_UNICODE) `Py_UNICODE_TOLOWER`([Py\_UNICODE](https://python-all.ru/3.0/c-api/unicode.html#Py_UNICODE) *ch*)**250251Возвращает символ252253*ch*254255, преобразованный в нижний регистр.256257**\[Py\_UNICODE\_TOUPPER\][Py\_UNICODE](https://python-all.ru/3.0/c-api/unicode.html#Py_UNICODE) `Py_UNICODE_TOUPPER`([Py\_UNICODE](https://python-all.ru/3.0/c-api/unicode.html#Py_UNICODE) *ch*)**258259Возвращает символ260261*ch*262263, преобразованный в верхний регистр.264265**\[Py\_UNICODE\_TOTITLE\][Py\_UNICODE](https://python-all.ru/3.0/c-api/unicode.html#Py_UNICODE) `Py_UNICODE_TOTITLE`([Py\_UNICODE](https://python-all.ru/3.0/c-api/unicode.html#Py_UNICODE) *ch*)**266267Возвращает символ268269*ch*270271, приведённый к регистру заголовка.272273**\[Py\_UNICODE\_TODECIMAL\]int `Py_UNICODE_TODECIMAL`([Py\_UNICODE](https://python-all.ru/3.0/c-api/unicode.html#Py_UNICODE) *ch*)**274275Возвращает символ276277*ch*278279, преобразованный в десятичное положительное целое. Возвращает280281`-1`282283, если это невозможно. Этот макрос не вызывает исключений.284285**\[Py\_UNICODE\_TODIGIT\]int `Py_UNICODE_TODIGIT`([Py\_UNICODE](https://python-all.ru/3.0/c-api/unicode.html#Py_UNICODE) *ch*)**286287Возвращает символ288289*ch*290291, преобразованный в целое однозначное число. Возвращает292293`-1`294295, если это невозможно. Этот макрос не вызывает исключений.296297**\[Py\_UNICODE\_TONUMERIC\]double `Py_UNICODE_TONUMERIC`([Py\_UNICODE](https://python-all.ru/3.0/c-api/unicode.html#Py_UNICODE) *ch*)**298299Возвращает символ300301*ch*302303, преобразованный в double. Возвращает304305`-1.0`306307, если это невозможно. Этот макрос не вызывает исключений.308309Для создания объектов Unicode и доступа к их базовым свойствам последовательности используйте следующие API:310311**\[PyUnicode\_FromUnicode\][PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject)\* `PyUnicode_FromUnicode`(const [Py\_UNICODE](https://python-all.ru/3.0/c-api/unicode.html#Py_UNICODE) *\*u*, Py\_ssize\_t *size*)**312313*Возвращаемое значение: новая ссылка.*314315Создаёт объект Unicode из буфера Py\_UNICODE *u* заданного размера. *u* может быть *NULL*, что делает содержимое неопределённым. Пользователь сам отвечает за заполнение нужных данных. Буфер копируется в новый объект. Если буфер не равен *NULL*, возвращаемое значение может быть общим объектом. Поэтому изменять полученный объект Unicode разрешается только когда *u* равен *NULL*.316317**\[PyUnicode\_FromStringAndSize\][PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject)\* `PyUnicode_FromStringAndSize`(const char *\*u*, Py\_ssize\_t *size*)**318319Create a Unicode Object from the char buffer320321*u*322323. The bytes will be interpreted as being UTF-8 encoded.324325*u*326327may also be328329*NULL*330331which causes the contents to be undefined. It is the user’s responsibility to fill in the needed data. The buffer is copied into the new object. If the buffer is not332333*NULL*334335, the return value might be a shared object. Therefore, modification of the resulting Unicode object is only allowed when336337*u*338339is340341*NULL*342343.344345**\[PyUnicode\_FromString\][PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject) \*`PyUnicode_FromString`(const char *\*u*)**346347Создаёт объект Unicode из UTF-8-кодированного символьного буфера с завершающим нулём348349*u*350351.352353**\[PyUnicode\_FromFormat\][PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject)\* `PyUnicode_FromFormat`(const char *\*format*, ...)**354355Принимает C-строку формата в стиле `printf` *format* и переменное число аргументов, вычисляет размер результирующей строки Python unicode и возвращает строку с подставленными значениями. Переменные аргументы должны быть C-типами и точно соответствовать форматным символам в строке *format*. Допускаются следующие форматные символы:356357| Символы формата | Тип | Описание |358| --- | --- | --- |359| `%%` | *н/д* | Буквальный символ %. |360| `%c` | int | Одиночный символ, представленный как C int. |361| `%d` | int | Полностью эквивалентно `printf("%d")`. |362| `%u` | беззнаковый int | Полностью эквивалентно `printf("%u")`. |363| `%ld` | long | Полностью эквивалентно `printf("%ld")`. |364| `%lu` | беззнаковый long | Полностью эквивалентно `printf("%lu")`. |365| `%zd` | Py\_ssize\_t | Полностью эквивалентно `printf("%zd")`. |366| `%zu` | size\_t | Полностью эквивалентно `printf("%zu")`. |367| `%i` | int | Полностью эквивалентно `printf("%i")`. |368| `%x` | int | Полностью эквивалентно `printf("%x")`. |369| `%s` | char\* | Нуль-терминированный массив символов C. |370| `%p` | void\* | Шестнадцатеричное представление указателя C. В основном эквивалентно `printf("%p")` за исключением того, что гарантированно начинается с литерала `0x` независимо от того, что выдает `printf` на данной платформе. |371| `%A` | PyObject\* | Результат вызова [`ascii()`](https://python-all.ru/3.0/library/functions.html#ascii). |372| `%U` | PyObject\* | Unicode-объект. |373| `%V` | PyObject\*, char \* | Unicode-объект (может быть *NULL*) и завершающийся нулевым символом C-массив символов в качестве второго параметра (используется, если первый параметр равен *NULL*). |374| `%S` | PyObject\* | Результат вызова `PyObject_Unicode()`. |375| `%R` | PyObject\* | Результат вызова [`PyObject_Repr()`](https://python-all.ru/3.0/c-api/object.html#PyObject_Repr). |376377Нераспознанный символ формата приводит к тому, что вся оставшаяся строка формата копируется как есть в результирующую строку, а все лишние аргументы отбрасываются.378379**\[PyUnicode\_FromFormatV\][PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject)\* `PyUnicode_FromFormatV`(const char *\*format*, va\_list *vargs*)**380381Идентична382383[`PyUnicode_FromFormat()`](https://python-all.ru/3.0/c-api/unicode.html#PyUnicode_FromFormat)384385, за исключением того, что принимает ровно два аргумента.386387**\[PyUnicode\_AsUnicode\][Py\_UNICODE](https://python-all.ru/3.0/c-api/unicode.html#Py_UNICODE)\* `PyUnicode_AsUnicode`([PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject) *\*unicode*)**388389Возвращает указатель только для чтения на внутренний буфер390391[`Py_UNICODE`](https://python-all.ru/3.0/c-api/unicode.html#Py_UNICODE)392393объекта Unicode;394395*NULL*396397, если398399*unicode*400401не является объектом Unicode.402403**\[PyUnicode\_GetSize\]Py\_ssize\_t `PyUnicode_GetSize`([PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject) *\*unicode*)**404405Возвращает длину объекта Unicode.406407**\[PyUnicode\_FromEncodedObject\][PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject)\* `PyUnicode_FromEncodedObject`([PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject) *\*obj*, const char *\*encoding*, const char *\*errors*)**408409*Возвращаемое значение: новая ссылка.*410411Преобразует закодированный объект *obj* в объект Unicode и возвращает ссылку с увеличенным счётчиком ссылок.412413Строки и другие объекты, совместимые с символьными буферами, декодируются в соответствии с заданной кодировкой и с использованием обработки ошибок, определённой параметром errors. Оба параметра могут быть *NULL*, чтобы интерфейс использовал значения по умолчанию (подробнее см. следующий раздел).414415Все остальные объекты, включая объекты Unicode, вызывают установку [`TypeError`](https://python-all.ru/3.0/library/exceptions.html#exceptions.TypeError).416417API возвращает *NULL* при ошибке. Вызывающий отвечает за уменьшение счётчика ссылок возвращённых объектов.418419**\[PyUnicode\_FromObject\][PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject)\* `PyUnicode_FromObject`([PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject) *\*obj*)**420421*Возвращаемое значение: новая ссылка.*422423Shortcut for `PyUnicode_FromEncodedObject(obj, NULL, "strict")` which is used throughout the interpreter whenever coercion to Unicode is needed.424425Если платформа поддерживает `wchar_t` и предоставляет заголовочный файл wchar.h, Python может напрямую взаимодействовать с этим типом с помощью следующих функций. Поддержка оптимизируется, если собственный тип [`Py_UNICODE`](https://python-all.ru/3.0/c-api/unicode.html#Py_UNICODE) Python идентичен системному `wchar_t`.426427**\[PyUnicode\_FromWideChar\][PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject)\* `PyUnicode_FromWideChar`(const wchar\_t *\*w*, Py\_ssize\_t *size*)**428429*Возвращаемое значение: новая ссылка.*430431Создаёт объект Unicode из буфера `wchar_t` *w* указанного размера. Если передать -1 в качестве размера, функция должна сама вычислить длину с помощью wcslen. Возвращает *NULL* в случае ошибки.432433**\[PyUnicode\_AsWideChar\]Py\_ssize\_t `PyUnicode_AsWideChar`([PyUnicodeObject](https://python-all.ru/3.0/c-api/unicode.html#PyUnicodeObject) *\*unicode*, wchar\_t *\*w*, Py\_ssize\_t *size*)**434435Копирует содержимое объекта Unicode в буфер436437`wchar_t`438439*w*440441. Копируется не более442443*size*444445символов446447`wchar_t`448449(возможный завершающий нулевой символ не учитывается). Возвращает количество скопированных символов450451`wchar_t`452453или -1 в случае ошибки. Обратите внимание: результирующая строка454455`wchar_t`456457может как содержать, так и не содержать завершающий нулевой символ. Вызывающий должен убедиться, что строка458459`wchar_t`460461заканчивается нулевым символом, если это требуется приложению.462463## Встроенные кодеки464465Python предоставляет набор встроенных кодеков, написанных на C для быстродействия. Все эти кодеки можно напрямую использовать через следующие функции.466467Многие из следующих API принимают два аргумента: encoding и errors. Эти параметры encoding и errors имеют ту же семантику, что и одноимённые параметры встроенного конструктора объектов Unicode unicode().468469Установка encoding в *NULL* приводит к использованию кодировки по умолчанию, которой является ASCII. Системные вызовы для работы с файлами должны использовать `Py_FileSystemDefaultEncoding` в качестве кодировки для имён файлов. Эту переменную следует считать доступной только для чтения: на одних системах это указатель на статическую строку, на других она может изменяться во время выполнения (например, когда приложение вызывает setlocale).470471Обработка ошибок задаётся параметром errors, который также может быть установлен в *NULL*, что означает использование обработки по умолчанию, определённой для кодека. Обработка ошибок по умолчанию для всех встроенных кодеков – «strict» (возбуждается [`ValueError`](https://python-all.ru/3.0/library/exceptions.html#exceptions.ValueError)).472473Все кодеки используют похожий интерфейс. Для простоты документированы только отклонения от следующего общего описания.474475Это общие API кодеков:476477**\[PyUnicode\_Decode\][PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject)\* `PyUnicode_Decode`(const char *\*s*, Py\_ssize\_t *size*, const char *\*encoding*, const char *\*errors*)**478479*Возвращаемое значение: новая ссылка.*480481Создаёт объект Unicode путём декодирования *size* байт из закодированной строки *s*. Параметры *encoding* и *errors* имеют тот же смысл, что и одноимённые параметры встроенной функции `unicode()`. Используемый кодек ищется в реестре кодеков Python. Возвращает *NULL*, если кодек возбудил исключение.482483**\[PyUnicode\_Encode\][PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject)\* `PyUnicode_Encode`(const [Py\_UNICODE](https://python-all.ru/3.0/c-api/unicode.html#Py_UNICODE) *\*s*, Py\_ssize\_t *size*, const char *\*encoding*, const char *\*errors*)**484485*Возвращаемое значение: новая ссылка.*486487Кодирует буфер [`Py_UNICODE`](https://python-all.ru/3.0/c-api/unicode.html#Py_UNICODE) указанного размера и возвращает объект строки Python. Параметры *encoding* и *errors* имеют тот же смысл, что и одноимённые параметры метода Unicode `encode()`. Используемый кодек ищется в реестре кодеков Python. Возвращает *NULL*, если кодек возбудил исключение.488489**\[PyUnicode\_AsEncodedString\][PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject)\* `PyUnicode_AsEncodedString`([PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject) *\*unicode*, const char *\*encoding*, const char *\*errors*)**490491*Возвращаемое значение: новая ссылка.*492493Кодирует объект Unicode и возвращает результат в виде строки Python. Параметры *encoding* и *errors* имеют тот же смысл, что и одноимённые параметры метода Unicode `encode()`. Используемый кодек ищется в реестре кодеков Python. Возвращает *NULL*, если кодек возбудил исключение.494495Это API кодеков UTF-8:496497**\[PyUnicode\_DecodeUTF8\][PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject)\* `PyUnicode_DecodeUTF8`(const char *\*s*, Py\_ssize\_t *size*, const char *\*errors*)**498499*Возвращаемое значение: новая ссылка.*500501Создаёт объект Unicode путём декодирования *size* байт строки, закодированной в UTF-8, *s*. Возвращает *NULL*, если кодек возбудил исключение.502503**\[PyUnicode\_DecodeUTF8Stateful\][PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject)\* `PyUnicode_DecodeUTF8Stateful`(const char *\*s*, Py\_ssize\_t *size*, const char *\*errors*, Py\_ssize\_t *\*consumed*)**504505*Возвращаемое значение: новая ссылка.*506507Если *consumed* равен *NULL*, ведёт себя как [`PyUnicode_DecodeUTF8`](https://python-all.ru/3.0/c-api/unicode.html#PyUnicode_DecodeUTF8). Если *consumed* не равен *NULL*, конечные неполные последовательности байт UTF-8 не считаются ошибкой. Эти байты не декодируются, а количество уже декодированных байт сохраняется в *consumed*.508509**\[PyUnicode\_EncodeUTF8\][PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject)\* `PyUnicode_EncodeUTF8`(const [Py\_UNICODE](https://python-all.ru/3.0/c-api/unicode.html#Py_UNICODE) *\*s*, Py\_ssize\_t *size*, const char *\*errors*)**510511*Возвращаемое значение: новая ссылка.*512513Кодирует буфер [`Py_UNICODE`](https://python-all.ru/3.0/c-api/unicode.html#Py_UNICODE) указанного размера с использованием UTF-8 и возвращает объект строки Python. Возвращает *NULL*, если кодек возбудил исключение.514515**\[PyUnicode\_AsUTF8String\][PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject)\* `PyUnicode_AsUTF8String`([PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject) *\*unicode*)**516517*Возвращаемое значение: новая ссылка.*518519Кодирует объект Unicode с использованием UTF-8 и возвращает результат в виде строки Python. Обработка ошибок – «strict». Возвращает *NULL*, если кодек возбудил исключение.520521Это API кодеков UTF-32:522523**\[PyUnicode\_DecodeUTF32\][PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject)\* `PyUnicode_DecodeUTF32`(const char *\*s*, Py\_ssize\_t *size*, const char *\*errors*, int *\*byteorder*)**524525Декодирует *length* байт из строки буфера, закодированной в UTF-32, и возвращает соответствующий объект Unicode. Параметр *errors* (если не *NULL*) определяет обработку ошибок. По умолчанию – «strict».526527Если *byteorder* не равен *NULL*, декодер начинает декодирование с использованием заданного порядка байтов:528529```c530*byteorder == -1: little endian531*byteorder == 0:  native order532*byteorder == 1:  big endian533```534535а затем переключается, если первые четыре байта входных данных являются маркером порядка байт (BOM) и заданный порядок байт является порядком хост-системы. Этот BOM не копируется в результирующую строку Unicode. После завершения в *\*byteorder* устанавливается текущий порядок байт на конец входных данных.536537В сборке с узким представлением кодовые точки за пределами BMP будут декодироваться как суррогатные пары.538539Если *byteorder* равен *NULL*, кодек запускается в режиме собственного порядка байтов.540541Возвращает *NULL*, если кодек сгенерировал исключение.542543**\[PyUnicode\_DecodeUTF32Stateful\][PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject)\* `PyUnicode_DecodeUTF32Stateful`(const char *\*s*, Py\_ssize\_t *size*, const char *\*errors*, int *\*byteorder*, Py\_ssize\_t *\*consumed*)**544545Если546547*consumed*548549равен550551*NULL*552553, поведение аналогично554555[`PyUnicode_DecodeUTF32`](https://python-all.ru/3.0/c-api/unicode.html#PyUnicode_DecodeUTF32)556557. Если558559*consumed*560561не равен562563*NULL*564565,566567[`PyUnicode_DecodeUTF32Stateful`](https://python-all.ru/3.0/c-api/unicode.html#PyUnicode_DecodeUTF32Stateful)568569не считает ошибкой остаточные неполные последовательности байтов UTF-32 (например, количество байтов, не кратное четырем). Такие байты не декодируются, а количество декодированных байтов сохраняется в570571*consumed*572573.574575**\[PyUnicode\_EncodeUTF32\][PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject)\* `PyUnicode_EncodeUTF32`(const [Py\_UNICODE](https://python-all.ru/3.0/c-api/unicode.html#Py_UNICODE) *\*s*, Py\_ssize\_t *size*, const char *\*errors*, int *byteorder*)**576577Возвращает объект Python bytes, содержащий значение Unicode-данных из *s*, закодированное в UTF-32. Если *byteorder* не равен `0`, вывод записывается в соответствии со следующим порядком байтов:578579```c580byteorder == -1: little endian581byteorder == 0:  native byte order (writes a BOM mark)582byteorder == 1:  big endian583```584585Если `0`, выходная строка всегда начинается с метки BOM Unicode (U+FEFF). В двух других режимах метка BOM не добавляется.586587Если *Py\_UNICODE\_WIDE* не определён, суррогатные пары будут выводиться как одна кодовая точка.588589Возвращает *NULL*, если кодек сгенерировал исключение.590591**\[PyUnicode\_AsUTF32String\][PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject)\* `PyUnicode_AsUTF32String`([PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject) *\*unicode*)**592593Возвращает строку Python, закодированную в UTF-32 с native порядком байтов. Строка всегда начинается с маркера BOM. Обработка ошибок – «strict». Возвращает594595*NULL*596597, если кодек вызвал исключение.598599Это API кодеков UTF-32:600601**\[PyUnicode\_DecodeUTF16\][PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject)\* `PyUnicode_DecodeUTF16`(const char *\*s*, Py\_ssize\_t *size*, const char *\*errors*, int *\*byteorder*)**602603*Возвращаемое значение: новая ссылка.*604605Декодирует *length* байт из строки буфера, закодированной в UTF-16, и возвращает соответствующий объект Unicode. *errors* (если не *NULL*) задаёт обработку ошибок. По умолчанию – «strict».606607Если *byteorder* не равен *NULL*, декодер начинает декодирование с использованием заданного порядка байтов:608609```c610*byteorder == -1: little endian611*byteorder == 0:  native order612*byteorder == 1:  big endian613```614615и затем переключается, если первые два байта входных данных являются маркером порядка байтов (BOM), а указанный порядок байтов является native. Этот BOM не копируется в результирующую строку Unicode. После завершения *\*byteorder* устанавливается в текущий порядок байтов в конце входных данных.616617Если *byteorder* равен *NULL*, кодек запускается в режиме собственного порядка байтов.618619Возвращает *NULL*, если кодек сгенерировал исключение.620621**\[PyUnicode\_DecodeUTF16Stateful\][PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject)\* `PyUnicode_DecodeUTF16Stateful`(const char *\*s*, Py\_ssize\_t *size*, const char *\*errors*, int *\*byteorder*, Py\_ssize\_t *\*consumed*)**622623*Возвращаемое значение: новая ссылка.*624625Если *consumed* равен *NULL*, поведение аналогично [`PyUnicode_DecodeUTF16`](https://python-all.ru/3.0/c-api/unicode.html#PyUnicode_DecodeUTF16). Если *consumed* не равен *NULL*, [`PyUnicode_DecodeUTF16Stateful`](https://python-all.ru/3.0/c-api/unicode.html#PyUnicode_DecodeUTF16Stateful) не считает ошибкой остаточные неполные последовательности байтов UTF-16 (например, нечётное количество байтов или разделённая суррогатная пара). Такие байты не декодируются, а количество декодированных байтов сохраняется в *consumed*.626627**\[PyUnicode\_EncodeUTF16\][PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject)\* `PyUnicode_EncodeUTF16`(const [Py\_UNICODE](https://python-all.ru/3.0/c-api/unicode.html#Py_UNICODE) *\*s*, Py\_ssize\_t *size*, const char *\*errors*, int *byteorder*)**628629*Возвращаемое значение: новая ссылка.*630631Возвращает строковый объект Python, содержащий значение Unicode-данных из *s*, закодированное в UTF-16. Если *byteorder* не равен `0`, вывод записывается в соответствии со следующим порядком байтов:632633```c634byteorder == -1: little endian635byteorder == 0:  native byte order (writes a BOM mark)636byteorder == 1:  big endian637```638639Если `0`, выходная строка всегда начинается с метки BOM Unicode (U+FEFF). В двух других режимах метка BOM не добавляется.640641Если *Py\_UNICODE\_WIDE* определён, одно значение [`Py_UNICODE`](https://python-all.ru/3.0/c-api/unicode.html#Py_UNICODE) может быть представлено как суррогатная пара. Если он не определён, каждое значение [`Py_UNICODE`](https://python-all.ru/3.0/c-api/unicode.html#Py_UNICODE) интерпретируется как символ UCS-2.642643Возвращает *NULL*, если кодек сгенерировал исключение.644645**\[PyUnicode\_AsUTF16String\][PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject)\* `PyUnicode_AsUTF16String`([PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject) *\*unicode*)**646647*Возвращаемое значение: новая ссылка.*648649Возвращает строку Python, закодированную в UTF-16 с native порядком байтов. Строка всегда начинается с маркера BOM. Обработка ошибок – «strict». Возвращает *NULL*, если кодек вызвал исключение.650651Это API кодеков «Unicode Escape»:652653**\[PyUnicode\_DecodeUnicodeEscape\][PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject)\* `PyUnicode_DecodeUnicodeEscape`(const char *\*s*, Py\_ssize\_t *size*, const char *\*errors*)**654655*Возвращаемое значение: новая ссылка.*656657Создаёт объект Unicode путём декодирования *size* байт строки в кодировке Unicode-Escape *s*. Возвращает *NULL*, если кодек сгенерировал исключение.658659**\[PyUnicode\_EncodeUnicodeEscape\][PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject)\* `PyUnicode_EncodeUnicodeEscape`(const [Py\_UNICODE](https://python-all.ru/3.0/c-api/unicode.html#Py_UNICODE) *\*s*, Py\_ssize\_t *size*)**660661*Возвращаемое значение: новая ссылка.*662663Кодирует буфер [`Py_UNICODE`](https://python-all.ru/3.0/c-api/unicode.html#Py_UNICODE) заданного размера с использованием Unicode-Escape и возвращает объект строки Python. Возвращает *NULL*, если кодек вызвал исключение.664665**\[PyUnicode\_AsUnicodeEscapeString\][PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject)\* `PyUnicode_AsUnicodeEscapeString`([PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject) *\*unicode*)**666667*Возвращаемое значение: новая ссылка.*668669Кодирует объект Unicode с использованием Unicode-Escape и возвращает результат в виде строкового объекта Python. Обработка ошибок – «strict». Возвращает *NULL*, если кодек вызвал исключение.670671Это API кодеков «Raw Unicode Escape»:672673**\[PyUnicode\_DecodeRawUnicodeEscape\][PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject)\* `PyUnicode_DecodeRawUnicodeEscape`(const char *\*s*, Py\_ssize\_t *size*, const char *\*errors*)**674675*Возвращаемое значение: новая ссылка.*676677Создаёт объект Unicode путём декодирования *size* байт строки *s*, закодированной в Raw-Unicode-Escape. Возвращает *NULL*, если кодек вызвал исключение.678679**\[PyUnicode\_EncodeRawUnicodeEscape\][PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject)\* `PyUnicode_EncodeRawUnicodeEscape`(const [Py\_UNICODE](https://python-all.ru/3.0/c-api/unicode.html#Py_UNICODE) *\*s*, Py\_ssize\_t *size*, const char *\*errors*)**680681*Возвращаемое значение: новая ссылка.*682683Кодирует буфер [`Py_UNICODE`](https://python-all.ru/3.0/c-api/unicode.html#Py_UNICODE) заданного размера с помощью Raw-Unicode-Escape и возвращает строковый объект Python. Возвращает *NULL*, если кодек вызвал исключение.684685**\[PyUnicode\_AsRawUnicodeEscapeString\][PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject)\* `PyUnicode_AsRawUnicodeEscapeString`([PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject) *\*unicode*)**686687*Возвращаемое значение: новая ссылка.*688689Кодирует объект Unicode с использованием Raw-Unicode-Escape и возвращает результат в виде строкового объекта Python. Обработка ошибок – «strict». Возвращает *NULL*, если кодек вызвал исключение.690691Это API кодеков Latin-1: Latin-1 соответствует первым 256 кодовым позициям Unicode, и только они принимаются кодеками при кодировании.692693**\[PyUnicode\_DecodeLatin1\][PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject)\* `PyUnicode_DecodeLatin1`(const char *\*s*, Py\_ssize\_t *size*, const char *\*errors*)**694695*Возвращаемое значение: новая ссылка.*696697Создаёт объект Unicode путём декодирования *size* байт строки *s*, закодированной в Latin-1. Возвращает *NULL*, если кодек вызвал исключение.698699**\[PyUnicode\_EncodeLatin1\][PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject)\* `PyUnicode_EncodeLatin1`(const [Py\_UNICODE](https://python-all.ru/3.0/c-api/unicode.html#Py_UNICODE) *\*s*, Py\_ssize\_t *size*, const char *\*errors*)**700701*Возвращаемое значение: новая ссылка.*702703Кодирует буфер [`Py_UNICODE`](https://python-all.ru/3.0/c-api/unicode.html#Py_UNICODE) заданного размера с помощью Latin-1 и возвращает строковый объект Python. Возвращает *NULL*, если кодек вызвал исключение.704705**\[PyUnicode\_AsLatin1String\][PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject)\* `PyUnicode_AsLatin1String`([PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject) *\*unicode*)**706707*Возвращаемое значение: новая ссылка.*708709Кодирует объект Unicode с помощью Latin-1 и возвращает результат в виде строкового объекта Python. Обработка ошибок – «strict». Возвращает *NULL*, если кодек вызвал исключение.710711Это API кодеков ASCII. Принимаются только 7-битные данные ASCII. Все остальные коды вызывают ошибки.712713**\[PyUnicode\_DecodeASCII\][PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject)\* `PyUnicode_DecodeASCII`(const char *\*s*, Py\_ssize\_t *size*, const char *\*errors*)**714715*Возвращаемое значение: новая ссылка.*716717Создаёт объект Unicode путём декодирования *size* байт строки *s*, закодированной в ASCII. Возвращает *NULL*, если кодек вызвал исключение.718719**\[PyUnicode\_EncodeASCII\][PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject)\* `PyUnicode_EncodeASCII`(const [Py\_UNICODE](https://python-all.ru/3.0/c-api/unicode.html#Py_UNICODE) *\*s*, Py\_ssize\_t *size*, const char *\*errors*)**720721*Возвращаемое значение: новая ссылка.*722723Кодирует буфер [`Py_UNICODE`](https://python-all.ru/3.0/c-api/unicode.html#Py_UNICODE) заданного размера с помощью ASCII и возвращает строковый объект Python. Возвращает *NULL*, если кодек вызвал исключение.724725**\[PyUnicode\_AsASCIIString\][PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject)\* `PyUnicode_AsASCIIString`([PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject) *\*unicode*)**726727*Возвращаемое значение: новая ссылка.*728729Кодирует объект Unicode с помощью ASCII и возвращает результат в виде строкового объекта Python. Обработка ошибок – «strict». Возвращает *NULL*, если кодек вызвал исключение.730731Это API кодеков отображения:732733Этот кодек особенный, так как его можно использовать для реализации множества разных кодеков (именно так и были получены большинство стандартных кодеков, входящих в пакет `encodings`). Кодек использует отображение для кодирования и декодирования символов.734735Отображения для декодирования должны сопоставлять отдельные строковые символы отдельным символам Unicode, целым числам (которые затем интерпретируются как кодовые точки Unicode) или None (что означает «неопределённое отображение» и вызывает ошибку).736737Отображения для кодирования должны сопоставлять отдельные символы Unicode отдельным строковым символам, целым числам (которые затем интерпретируются как кодовые точки Latin-1) или None (что означает «неопределённое отображение» и вызывает ошибку).738739Объекты отображения должны поддерживать только интерфейс отображения \_\_getitem\_\_.740741Если при поиске символа возникает LookupError, символ копируется как есть; это означает, что его порядковое значение будет интерпретироваться как кодовая точка Unicode или Latin-1 соответственно. Из-за этого отображения должны содержать только те соответствия, которые переводят символы в другие кодовые точки.742743**\[PyUnicode\_DecodeCharmap\][PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject)\* `PyUnicode_DecodeCharmap`(const char *\*s*, Py\_ssize\_t *size*, [PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject) *\*mapping*, const char *\*errors*)**744745*Возвращаемое значение: новая ссылка.*746747Создаёт объект Unicode, декодируя *size* байт закодированной строки *s* с помощью заданного объекта *mapping*. Возвращает *NULL*, если кодек вызвал исключение. Если *mapping* равен *NULL*, выполняется декодирование Latin-1. В противном случае это может быть словарь, отображающий байты, или строка Unicode, которая интерпретируется как таблица поиска. Значения байтов, превышающие длину строки, и «символ» U+FFFE считаются «неопределённым отображением».748749**\[PyUnicode\_EncodeCharmap\][PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject)\* `PyUnicode_EncodeCharmap`(const [Py\_UNICODE](https://python-all.ru/3.0/c-api/unicode.html#Py_UNICODE) *\*s*, Py\_ssize\_t *size*, [PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject) *\*mapping*, const char *\*errors*)**750751*Возвращаемое значение: новая ссылка.*752753Кодирует буфер [`Py_UNICODE`](https://python-all.ru/3.0/c-api/unicode.html#Py_UNICODE) заданного размера, используя заданный *mapping* объект, и возвращает объект строки Python. Возвращает *NULL*, если кодек вызвал исключение.754755**\[PyUnicode\_AsCharmapString\][PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject)\* `PyUnicode_AsCharmapString`([PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject) *\*unicode*, [PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject) *\*mapping*)**756757*Возвращаемое значение: новая ссылка.*758759Кодирует объект Unicode с помощью заданного объекта *mapping* и возвращает результат в виде строкового объекта Python. Обработка ошибок – «strict». Возвращает *NULL*, если кодек вызвал исключение.760761Следующее API кодека особенное тем, что отображает Unicode в Unicode.762763**\[PyUnicode\_TranslateCharmap\][PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject)\* `PyUnicode_TranslateCharmap`(const [Py\_UNICODE](https://python-all.ru/3.0/c-api/unicode.html#Py_UNICODE) *\*s*, Py\_ssize\_t *size*, [PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject) *\*table*, const char *\*errors*)**764765*Возвращаемое значение: новая ссылка.*766767Преобразует буфер [`Py_UNICODE`](https://python-all.ru/3.0/c-api/unicode.html#Py_UNICODE) заданной длины, применяя к нему таблицу символов *table*, и возвращает полученный объект Unicode. Возвращает *NULL*, когда кодек вызвал исключение.768769Таблица *mapping* должна сопоставлять целочисленные кодовые точки Unicode целочисленным кодовым точкам Unicode или None (что приводит к удалению символа).770771Таблицам отображения достаточно реализовать интерфейс [`__getitem__()`](https://python-all.ru/3.0/reference/datamodel.html#object.__getitem__); словари и последовательности подходят. Неотображённые коды символов (те, которые вызывают [`LookupError`](https://python-all.ru/3.0/library/exceptions.html#exceptions.LookupError)) остаются без изменений и копируются как есть.772773Это API кодеков MBCS. В настоящее время они доступны только в Windows и используют преобразователи Win32 MBCS для выполнения преобразований. Обратите внимание, что MBCS (или DBCS) – это класс кодировок, а не одна конкретная. Целевая кодировка определяется пользовательскими настройками на машине, где выполняется кодек.774775**\[PyUnicode\_DecodeMBCS\][PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject)\* `PyUnicode_DecodeMBCS`(const char *\*s*, Py\_ssize\_t *size*, const char *\*errors*)**776777*Возвращаемое значение: новая ссылка.*778779Создаёт объект Unicode, декодируя *size* байтов строки, закодированной в MBCS, из *s*. Возвращает *NULL*, если кодек вызвал исключение.780781**\[PyUnicode\_DecodeMBCSStateful\][PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject)\* `PyUnicode_DecodeMBCSStateful`(const char *\*s*, int *size*, const char *\*errors*, int *\*consumed*)**782783Если784785*consumed*786787равно788789*NULL*790791, ведёт себя как792793[`PyUnicode_DecodeMBCS`](https://python-all.ru/3.0/c-api/unicode.html#PyUnicode_DecodeMBCS)794795. Если796797*consumed*798799не равно800801*NULL*802803,804805[`PyUnicode_DecodeMBCSStateful`](https://python-all.ru/3.0/c-api/unicode.html#PyUnicode_DecodeMBCSStateful)806807не будет декодировать ведущий байт в конце, и количество декодированных байтов будет сохранено в808809*consumed*810811.812813**\[PyUnicode\_EncodeMBCS\][PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject)\* `PyUnicode_EncodeMBCS`(const [Py\_UNICODE](https://python-all.ru/3.0/c-api/unicode.html#Py_UNICODE) *\*s*, Py\_ssize\_t *size*, const char *\*errors*)**814815*Возвращаемое значение: новая ссылка.*816817Кодирует буфер [`Py_UNICODE`](https://python-all.ru/3.0/c-api/unicode.html#Py_UNICODE) заданного размера, используя MBCS, и возвращает объект строки Python. Возвращает *NULL*, если кодек вызвал исключение.818819**\[PyUnicode\_AsMBCSString\][PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject)\* `PyUnicode_AsMBCSString`([PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject) *\*unicode*)**820821*Возвращаемое значение: новая ссылка.*822823Кодирует объект Unicode, используя MBCS, и возвращает результат в виде объекта строки Python. Обработка ошибок – «strict». Возвращает *NULL*, если кодек вызвал исключение.824825## Методы и слот-функции826827Следующие API могут обрабатывать объекты Unicode и строки на входе (в описаниях мы называем их строками) и возвращают объекты Unicode или целые числа по необходимости.828829Все они возвращают *NULL* или `-1` в случае исключения.830831**\[PyUnicode\_Concat\][PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject)\* `PyUnicode_Concat`([PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject) *\*left*, [PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject) *\*right*)**832833*Возвращаемое значение: новая ссылка.*834835Объединяет две строки, возвращая новую строку Unicode.836837**\[PyUnicode\_Split\][PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject)\* `PyUnicode_Split`([PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject) *\*s*, [PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject) *\*sep*, Py\_ssize\_t *maxsplit*)**838839*Возвращаемое значение: новая ссылка.*840841Разделяет строку, возвращая список строк Unicode. Если sep равно *NULL*, разделение происходит по всем подстрокам пробельных символов. В противном случае разделение происходит по заданному разделителю. Будет выполнено не более *maxsplit* разделений. Если отрицательное, ограничение не устанавливается. Разделители не включаются в результирующий список.842843**\[PyUnicode\_Splitlines\][PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject)\* `PyUnicode_Splitlines`([PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject) *\*s*, int *keepend*)**844845*Возвращаемое значение: новая ссылка.*846847Разделяет строку Unicode по символам перевода строки и возвращает список строк Unicode. CRLF считается одним переносом строки. Если *keepend* равен 0, символы перевода строки не включаются в результирующие строки.848849**\[PyUnicode\_Translate\][PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject)\* `PyUnicode_Translate`([PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject) *\*str*, [PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject) *\*table*, const char *\*errors*)**850851*Возвращаемое значение: новая ссылка.*852853Переводит строку, применяя к ней таблицу отображения символов, и возвращает результирующий объект Unicode.854855Таблица отображения должна сопоставлять целочисленные коды Unicode другим целочисленным кодам Unicode или None (что приводит к удалению символа).856857Таблицам отображения достаточно реализовать интерфейс [`__getitem__()`](https://python-all.ru/3.0/reference/datamodel.html#object.__getitem__); словари и последовательности подходят. Неотображённые коды символов (те, которые вызывают [`LookupError`](https://python-all.ru/3.0/library/exceptions.html#exceptions.LookupError)) остаются без изменений и копируются как есть.858859*errors* имеет обычное для кодеков значение. Может быть *NULL*, что означает использование обработки ошибок по умолчанию.860861**\[PyUnicode\_Join\][PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject)\* `PyUnicode_Join`([PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject) *\*separator*, [PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject) *\*seq*)**862863*Возвращаемое значение: новая ссылка.*864865Объединяет последовательность строк, используя заданный разделитель, и возвращает полученную строку Unicode.866867**\[PyUnicode\_Tailmatch\]int `PyUnicode_Tailmatch`([PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject) *\*str*, [PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject) *\*substr*, Py\_ssize\_t *start*, Py\_ssize\_t *end*, int *direction*)**868869*Возвращаемое значение: новая ссылка.*870871Возвращает 1, если *substr* совпадает с *str\[\*start*:*end*\] на заданном конце (*direction* == -1 означает поиск префикса, *direction* == 1 – поиск суффикса), и 0 в противном случае. Возвращает `-1`, если произошла ошибка.872873**\[PyUnicode\_Find\]Py\_ssize\_t `PyUnicode_Find`([PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject) *\*str*, [PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject) *\*substr*, Py\_ssize\_t *start*, Py\_ssize\_t *end*, int *direction*)**874875Возвращает первую позицию876877*substr*878879в880881*str\[\*start*882883:884885*end*886887\], используя заданное888889*direction*890891(892893*direction*894895== 1 означает прямой поиск,896897*direction*898899== -1 – обратный поиск). Возвращаемое значение – индекс первого совпадения; значение900901`-1`902903указывает, что совпадение не найдено, а904905`-2`906907указывает, что произошла ошибка и было установлено исключение.908909**\[PyUnicode\_Count\]Py\_ssize\_t `PyUnicode_Count`([PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject) *\*str*, [PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject) *\*substr*, Py\_ssize\_t *start*, Py\_ssize\_t *end*)**910911Возвращает количество непересекающихся вхождений912913*substr*914915в916917`str[start:end]`918919. Возвращает920921`-1`922923, если произошла ошибка.924925**\[PyUnicode\_Replace\][PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject)\* `PyUnicode_Replace`([PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject) *\*str*, [PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject) *\*substr*, [PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject) *\*replstr*, Py\_ssize\_t *maxcount*)**926927*Возвращаемое значение: новая ссылка.*928929Заменяет не более *maxcount* вхождений *substr* в *str* на *replstr* и возвращает результирующий объект Unicode. *maxcount* == -1 означает замену всех вхождений.930931**\[PyUnicode\_Compare\]int `PyUnicode_Compare`([PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject) *\*left*, [PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject) *\*right*)**932933Сравнивает две строки и возвращает -1, 0, 1 для случаев «меньше», «равно» и «больше» соответственно.934935**\[PyUnicode\_CompareWithASCIIString\]int `PyUnicode_CompareWithASCIIString`([PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject) *\*uni*, char *\*string*)**936937Сравнивает объект Unicode938939*uni*940941со строкой942943*string*944945и возвращает -1, 0, 1 для меньше чем, равно и больше соответственно.946947**\[PyUnicode\_RichCompare\]int `PyUnicode_RichCompare`([PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject) *\*left*, [PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject) *\*right*, int *op*)**948949Выполняет расширенное сравнение двух строк unicode и возвращает одно из следующих значений:950951- `NULL` в случае возбуждения исключения952- [`Py_True`](https://python-all.ru/3.0/c-api/bool.html#Py_True) или [`Py_False`](https://python-all.ru/3.0/c-api/bool.html#Py_False) для успешных сравнений953- `Py_NotImplemented` в случае, если комбинация типов неизвестна954955Обратите внимание, что сравнения с `Py_EQ` и `Py_NE` могут вызвать [`UnicodeWarning`](https://python-all.ru/3.0/library/exceptions.html#exceptions.UnicodeWarning), если преобразование аргументов в Unicode завершится ошибкой с [`UnicodeDecodeError`](https://python-all.ru/3.0/library/exceptions.html#exceptions.UnicodeDecodeError).956957Возможные значения для *op*: `Py_GT`, `Py_GE`, `Py_EQ`, `Py_NE`, `Py_LT` и `Py_LE`.958959**\[PyUnicode\_Format\][PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject)\* `PyUnicode_Format`([PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject) *\*format*, [PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject) *\*args*)**960961*Возвращаемое значение: новая ссылка.*962963Возвращает новый строковый объект из *format* и *args*; это аналогично `format % args`. Аргумент *args* должен быть кортежем.964965**\[PyUnicode\_Contains\]int `PyUnicode_Contains`([PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject) *\*container*, [PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject) *\*element*)**966967Проверяет, содержится ли *element* в *container*, и возвращает true или false соответственно.968969*element* должен преобразовываться в односимвольную строку Unicode. Если произошла ошибка, возвращается `-1`.970971**\[PyUnicode\_InternInPlace\]void `PyUnicode_InternInPlace`([PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject) *\*\*string*)**972973Интернирует аргумент974975*\*string*976977на месте. Аргумент должен быть адресом переменной-указателя, указывающей на объект строки Unicode Python. Если уже существует интернированная строка, совпадающая с978979*\*string*980981, то она устанавливает982983*\*string*984985на эту строку (уменьшая счётчик ссылок старого строкового объекта и увеличивая счётчик интернированной строки); в противном случае она оставляет986987*\*string*988989без изменений и интернирует её (увеличивая её счётчик ссылок). (Уточнение: хотя много говорится о счётчиках ссылок, считайте эту функцию нейтральной к счётчикам ссылок – вы владеете объектом после вызова, только если владели им до вызова.)990991**\[PyUnicode\_InternFromString\][PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject)\* `PyUnicode_InternFromString`(const char *\*v*)**992993Комбинация994995[`PyUnicode_FromString`](https://python-all.ru/3.0/c-api/unicode.html#PyUnicode_FromString)996997и998999[`PyUnicode_InternInPlace`](https://python-all.ru/3.0/c-api/unicode.html#PyUnicode_InternInPlace)10001001, возвращающая либо новый объект строки юникода, который был интернирован, либо новую («собственную») ссылку на ранее интернированный строковый объект с тем же значением.1002