`unicode.md`

1202 строк · 98.1 КБ · обычная страница · сырой текст · скачать
1> **Источник:** https://python-all.ru/3.12/c-api/unicode.html2>3> «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor.45---67# Объекты Unicode и кодеки89## Объекты Unicode1011Начиная с реализации [**PEP 393**](https://python-all.ru/3.12/c-api/unicode.html) в Python 3.3, объекты Unicode внутри используют различные представления, чтобы обеспечить обработку полного диапазона символов Unicode, оставаясь при этом эффективными по памяти. Существуют особые случаи для строк, где все кодовые точки находятся ниже 128, 256 или 65536; в противном случае кодовые точки должны быть ниже 1114112 (то есть полного диапазона Unicode).1213Представление UTF-8 создаётся по требованию и кэшируется в объекте Unicode.1415> **Примечание**16>17> Представление [`Py_UNICODE`](https://python-all.ru/3.12/c-api/unicode.html#c.Py_UNICODE) было удалено начиная с Python 3.12 вместе с устаревшими API. См. [**PEP 623**](https://python-all.ru/3.12/c-api/unicode.html) для получения дополнительной информации.1819### Тип Unicode2021Это основные типы объектов Unicode, используемые в реализации Unicode в Python:2223#### `type Py_UCS4`2425#### `type Py_UCS2`2627#### `type Py_UCS1`2829*Часть [Stable ABI](https://python-all.ru/3.12/c-api/stable.html#stable).*3031Эти типы являются псевдонимами для беззнаковых целочисленных типов, достаточно широких для хранения символов размером 32, 16 и 8 бит соответственно. При работе с отдельными символами Unicode используйте [`Py_UCS4`](https://python-all.ru/3.12/c-api/unicode.html#c.Py_UCS4).3233Добавлено в версии 3.3.3435#### `type Py_UNICODE`3637Это typedef для `wchar_t`, 16-битный или 32-битный тип в зависимости от платформы.3839Изменено в версии 3.3: В предыдущих версиях это был 16-битный или 32-битный тип в зависимости от того, была ли выбрана «узкая» или «широкая» версия Unicode Python при сборке.4041#### `type PyASCIIObject`4243#### `type PyCompactUnicodeObject`4445#### `type PyUnicodeObject`4647Эти подтипы [`PyObject`](https://python-all.ru/3.12/c-api/structures.html#c.PyObject) представляют объект Unicode в Python. В почти всех случаях их не следует использовать напрямую, так как все функции API, работающие с объектами Unicode, принимают и возвращают указатели [`PyObject`](https://python-all.ru/3.12/c-api/structures.html#c.PyObject).4849Добавлено в версии 3.3.5051#### `PyTypeObject PyUnicode_Type`5253*Часть [Stable ABI](https://python-all.ru/3.12/c-api/stable.html#stable).*5455Этот экземпляр [`PyTypeObject`](https://python-all.ru/3.12/c-api/type.html#c.PyTypeObject) представляет тип Unicode в Python. Он доступен коду Python как `str`.5657Следующие API представляют собой макросы C и статические встроенные функции для быстрых проверок и доступа к внутренним данным только для чтения объектов Unicode:5859#### `int PyUnicode_Check(PyObject *obj)`6061Возвращает true, если объект *obj* является объектом Unicode или экземпляром подтипа Unicode. Эта функция всегда завершается успешно.6263#### `int PyUnicode_CheckExact(PyObject *obj)`6465Возвращает true, если объект *obj* является объектом Unicode, но не экземпляром подтипа. Эта функция всегда завершается успешно.6667#### `int PyUnicode_READY(PyObject *unicode)`6869Возвращает `0`. Этот API сохранён только для обратной совместимости.7071Добавлено в версии 3.3.7273Устарело с версии 3.10: Этот API ничего не делает, начиная с Python 3.12.7475#### `Py_ssize_t PyUnicode_GET_LENGTH(PyObject *unicode)`7677Возвращает длину строки Unicode в кодовых точках. *unicode* должен быть объектом Unicode в «каноническом» представлении (не проверяется).7879Добавлено в версии 3.3.8081#### `Py_UCS1 *PyUnicode_1BYTE_DATA(PyObject *unicode)`8283#### `Py_UCS2 *PyUnicode_2BYTE_DATA(PyObject *unicode)`8485#### `Py_UCS4 *PyUnicode_4BYTE_DATA(PyObject *unicode)`8687Возвращает указатель на каноническое представление, приведённый к целочисленным типам UCS1, UCS2 или UCS4 для прямого доступа к символам. Не выполняется проверок, имеет ли каноническое представление правильный размер символа; используйте [`PyUnicode_KIND()`](https://python-all.ru/3.12/c-api/unicode.html#c.PyUnicode_KIND), чтобы выбрать подходящую функцию.8889Добавлено в версии 3.3.9091#### `PyUnicode_1BYTE_KIND`9293#### `PyUnicode_2BYTE_KIND`9495#### `PyUnicode_4BYTE_KIND`9697Возвращает значения макроса [`PyUnicode_KIND()`](https://python-all.ru/3.12/c-api/unicode.html#c.PyUnicode_KIND).9899Добавлено в версии 3.3.100101Изменено в версии 3.12: `PyUnicode_WCHAR_KIND` был удалён.102103#### `int PyUnicode_KIND(PyObject *unicode)`104105Возвращает одну из констант вида PyUnicode (см. выше), которые указывают, сколько байт на символ использует данный объект Unicode для хранения своих данных. *unicode* должен быть объектом Unicode в «каноническом» представлении (не проверяется).106107Добавлено в версии 3.3.108109#### `void *PyUnicode_DATA(PyObject *unicode)`110111Возвращает указатель void на сырой буфер Unicode. *unicode* должен быть объектом Unicode в «каноническом» представлении (не проверяется).112113Добавлено в версии 3.3.114115#### `void PyUnicode_WRITE(int kind, void *data, Py_ssize_t index, Py_UCS4 value)`116117Записывает в каноническое представление *data* (полученное с помощью [`PyUnicode_DATA()`](https://python-all.ru/3.12/c-api/unicode.html#c.PyUnicode_DATA)). Эта функция не выполняет проверок корректности и предназначена для использования в циклах. Вызывающий код должен кэшировать значение *kind* и указатель *data*, полученные из других вызовов. *index* – это индекс в строке (начинается с 0), а *value* – это новое значение кодовой точки, которое должно быть записано в эту позицию.118119Добавлено в версии 3.3.120121#### `Py_UCS4 PyUnicode_READ(int kind, void *data, Py_ssize_t index)`122123Читает кодовую точку из канонического представления *data* (полученного с помощью [`PyUnicode_DATA()`](https://python-all.ru/3.12/c-api/unicode.html#c.PyUnicode_DATA)). Никаких проверок или вызовов готовности не выполняется.124125Добавлено в версии 3.3.126127#### `Py_UCS4 PyUnicode_READ_CHAR(PyObject *unicode, Py_ssize_t index)`128129Читает символ из объекта Unicode *unicode*, который должен быть в «каноническом» представлении. Это менее эффективно, чем [`PyUnicode_READ()`](https://python-all.ru/3.12/c-api/unicode.html#c.PyUnicode_READ), если выполняется несколько последовательных чтений.130131Добавлено в версии 3.3.132133#### `Py_UCS4 PyUnicode_MAX_CHAR_VALUE(PyObject *unicode)`134135Возвращает максимальную кодовую точку, подходящую для создания другой строки на основе *unicode*, который должен быть в «каноническом» представлении. Это всегда приближение, но более эффективное, чем перебор строки.136137Добавлено в версии 3.3.138139#### `int PyUnicode_IsIdentifier(PyObject *unicode)`140141*Часть [Stable ABI](https://python-all.ru/3.12/c-api/stable.html#stable).*142143Возвращает `1`, если строка является допустимым идентификатором в соответствии с определением языка, раздел [Идентификаторы и ключевые слова](https://python-all.ru/3.12/reference/lexical_analysis.html#identifiers). В противном случае возвращает `0`.144145Изменено в версии 3.9: Функция больше не вызывает [`Py_FatalError()`](https://python-all.ru/3.12/c-api/sys.html#c.Py_FatalError), если строка не готова.146147### Свойства символов Unicode148149Unicode предоставляет множество различных свойств символов. Наиболее востребованные из них доступны через следующие макросы, которые сопоставляются с функциями на C в зависимости от конфигурации Python.150151#### `int Py_UNICODE_ISSPACE(Py_UCS4 ch)`152153Возвращает `1` или `0` в зависимости от того, является ли *ch* пробельным символом.154155#### `int Py_UNICODE_ISLOWER(Py_UCS4 ch)`156157Возвращает `1` или `0` в зависимости от того, является ли *ch* символом в нижнем регистре.158159#### `int Py_UNICODE_ISUPPER(Py_UCS4 ch)`160161Возвращает `1` или `0` в зависимости от того, является ли *ch* символом в верхнем регистре.162163#### `int Py_UNICODE_ISTITLE(Py_UCS4 ch)`164165Возвращает `1` или `0` в зависимости от того, является ли *ch* символом в регистре заголовка (titlecase).166167#### `int Py_UNICODE_ISLINEBREAK(Py_UCS4 ch)`168169Возвращает `1` или `0` в зависимости от того, является ли *ch* символом разрыва строки.170171#### `int Py_UNICODE_ISDECIMAL(Py_UCS4 ch)`172173Возвращает `1` или `0` в зависимости от того, является ли *ch* десятичным символом.174175#### `int Py_UNICODE_ISDIGIT(Py_UCS4 ch)`176177Возвращает `1` или `0` в зависимости от того, является ли *ch* цифровым символом.178179#### `int Py_UNICODE_ISNUMERIC(Py_UCS4 ch)`180181Возвращает `1` или `0` в зависимости от того, является ли *ch* числовым символом.182183#### `int Py_UNICODE_ISALPHA(Py_UCS4 ch)`184185Возвращает `1` или `0` в зависимости от того, является ли *ch* буквенным символом.186187#### `int Py_UNICODE_ISALNUM(Py_UCS4 ch)`188189Возвращает `1` или `0` в зависимости от того, является ли *ch* буквенно-цифровым символом.190191#### `int Py_UNICODE_ISPRINTABLE(Py_UCS4 ch)`192193Возвращает `1` или `0` в зависимости от того, является ли *ch* печатным символом в смысле [`str.isprintable()`](https://python-all.ru/3.12/library/stdtypes.html#str.isprintable).194195Эти API можно использовать для быстрых прямых преобразований символов:196197#### `Py_UCS4 Py_UNICODE_TOLOWER(Py_UCS4 ch)`198199Возвращает символ *ch*, преобразованный в нижний регистр.200201Устарело с версии 3.3: Эта функция использует простые отображения регистра.202203#### `Py_UCS4 Py_UNICODE_TOUPPER(Py_UCS4 ch)`204205Возвращает символ *ch*, преобразованный в верхний регистр.206207Устарело с версии 3.3: Эта функция использует простые отображения регистра.208209#### `Py_UCS4 Py_UNICODE_TOTITLE(Py_UCS4 ch)`210211Возвращает символ *ch*, приведённый к регистру заголовка.212213Устарело с версии 3.3: Эта функция использует простые отображения регистра.214215#### `int Py_UNICODE_TODECIMAL(Py_UCS4 ch)`216217Возвращает символ *ch*, преобразованный в положительное десятичное целое. Возвращает `-1`, если это невозможно. Эта функция не вызывает исключений.218219#### `int Py_UNICODE_TODIGIT(Py_UCS4 ch)`220221Возвращает символ *ch*, преобразованный в целое число из одной цифры. Возвращает `-1`, если это невозможно. Эта функция не вызывает исключений.222223#### `double Py_UNICODE_TONUMERIC(Py_UCS4 ch)`224225Возвращает символ *ch*, преобразованный в число двойной точности (double). Возвращает `-1.0`, если это невозможно. Эта функция не вызывает исключений.226227Эти API можно использовать для работы с суррогатами:228229#### `int Py_UNICODE_IS_SURROGATE(Py_UCS4 ch)`230231Проверяет, является ли *ch* суррогатом (`0xD800 <= ch <= 0xDFFF`).232233#### `int Py_UNICODE_IS_HIGH_SURROGATE(Py_UCS4 ch)`234235Проверяет, является ли *ch* старшим суррогатом (`0xD800 <= ch <= 0xDBFF`).236237#### `int Py_UNICODE_IS_LOW_SURROGATE(Py_UCS4 ch)`238239Проверяет, является ли *ch* младшим суррогатом (`0xDC00 <= ch <= 0xDFFF`).240241#### `Py_UCS4 Py_UNICODE_JOIN_SURROGATES(Py_UCS4 high, Py_UCS4 low)`242243Объединяет два суррогатных символа и возвращает одно [`Py_UCS4`](https://python-all.ru/3.12/c-api/unicode.html#c.Py_UCS4) значение. *high* и *low* – это соответственно старший и младший суррогаты в суррогатной паре. *high* должен находиться в диапазоне \[0xD800; 0xDBFF\], а *low* – в диапазоне \[0xDC00; 0xDFFF\].244245### Создание строк Unicode и доступ к ним246247Для создания объектов Unicode и доступа к их базовым свойствам последовательности используйте следующие API:248249#### `PyObject *PyUnicode_New(Py_ssize_t size, Py_UCS4 maxchar)`250251*Возвращаемое значение: новая ссылка.*252253Создаёт новый объект Unicode. *maxchar* должен быть истинным максимальным кодом, который будет помещён в строку. В качестве приближения его можно округлить до ближайшего значения из последовательности 127, 255, 65535, 1114111.254255Это рекомендуемый способ выделения нового объекта Unicode. Объекты, созданные с помощью этой функции, не подлежат изменению размера.256257При ошибке устанавливает исключение и возвращает `NULL`.258259Добавлено в версии 3.3.260261#### `PyObject *PyUnicode_FromKindAndData(int kind, const void *buffer, Py_ssize_t size)`262263*Возвращаемое значение: новая ссылка.*264265Создаёт новый объект Unicode с заданным *видом* (возможные значения: [`PyUnicode_1BYTE_KIND`](https://python-all.ru/3.12/c-api/unicode.html#c.PyUnicode_1BYTE_KIND) и т.д., возвращаемые [`PyUnicode_KIND()`](https://python-all.ru/3.12/c-api/unicode.html#c.PyUnicode_KIND)). *Буфер* должен указывать на массив из *size* единиц по 1, 2 или 4 байта на символ, в зависимости от вида.266267При необходимости входной *буфер* копируется и преобразуется в каноническое представление. Например, если *buffer* – это строка UCS4 ([`PyUnicode_4BYTE_KIND`](https://python-all.ru/3.12/c-api/unicode.html#c.PyUnicode_4BYTE_KIND)) и состоит только из кодовых точек в диапазоне UCS1, она будет преобразована в UCS1 ([`PyUnicode_1BYTE_KIND`](https://python-all.ru/3.12/c-api/unicode.html#c.PyUnicode_1BYTE_KIND)).268269Добавлено в версии 3.3.270271#### `PyObject *PyUnicode_FromStringAndSize(const char *str, Py_ssize_t size)`272273*Возвращаемое значение: новая ссылка.*274275*Часть [Stable ABI](https://python-all.ru/3.12/c-api/stable.html#stable).*276277Создаёт объект Unicode из символьного буфера *str*. Байты интерпретируются как закодированные в UTF-8. Буфер копируется в новый объект. Возвращаемое значение может быть разделяемым объектом, т.е. изменение данных не допускается.278279Эта функция вызывает [`SystemError`](https://python-all.ru/3.12/library/exceptions.html#SystemError) в следующих случаях:280281- *size* \< 0282- *str* равен `NULL` и *size* \> 0283284Изменено в версии 3.12: *str* == `NULL` при *size* \> 0 больше не допускается.285286#### `PyObject *PyUnicode_FromString(const char *str)`287288*Возвращаемое значение: новая ссылка.*289290*Часть [Stable ABI](https://python-all.ru/3.12/c-api/stable.html#stable).*291292Создаёт объект Unicode из UTF-8-кодированного нуль-терминированного символьного буфера *str*.293294#### `PyObject *PyUnicode_FromFormat(const char *format, ...)`295296*Возвращаемое значение: новая ссылка.*297298*Часть [Stable ABI](https://python-all.ru/3.12/c-api/stable.html#stable).*299300Принимает строку формата в стиле C `printf()` *format* и переменное число аргументов, вычисляет размер результирующей строки Python Unicode и возвращает строку с отформатированными значениями. Переменные аргументы должны быть типами C и строго соответствовать символам формата в *format* ASCII-кодированной строке.301302Спецификатор преобразования содержит два или более символа и состоит из следующих компонентов, которые должны располагаться в указанном порядке:3033041. Символ `'%'`, обозначающий начало спецификатора.3052. Флаги преобразования (необязательно), влияющие на результат для некоторых типов преобразования.3063. Минимальная ширина поля (необязательно). Если задана как `'*'` (звёздочка), фактическая ширина передаётся в следующем аргументе, который должен иметь тип int, а преобразуемый объект следует после минимальной ширины поля и необязательной точности.3074. Точность (необязательно), задаётся как `'.'` (точка), за которой следует точность. Если указана как `'*'` (звёздочка), фактическая точность передаётся в следующем аргументе, который должен иметь тип int, а преобразуемое значение следует после точности.3085. Модификатор длины (необязательно).3096. Тип преобразования.310311Символы флагов преобразования:312313| Флаг | Значение |314| --- | --- |315| `0` | Для числовых значений преобразование будет дополняться нулями. |316| `-` | Преобразованное значение выравнивается по левому краю (отменяет флаг `0` , если указаны оба). |317318Модификаторы длины для следующих целочисленных преобразований (`d`, `i`, `o`, `u`, `x` или `X`) определяют тип аргумента (по умолчанию int):319320| Модификатор | Типы |321| --- | --- |322| `l` | long или unsigned long |323| `ll` | long long или unsigned long long |324| `j` | `intmax_t` или `uintmax_t` |325| `z` | `size_t` или `ssize_t` |326| `t` | `ptrdiff_t` |327328Модификатор длины `l` для следующих преобразований `s` или `V` указывает, что тип аргумента – const wchar\_t\*.329330Спецификаторы преобразования:331332| Спецификатор преобразования | Тип | Описание |333| --- | --- | --- |334| `%` | *н/д* | Литеральный символ `%`. |335| `d`, `i` | Указывается модификатором длины | Десятичное представление знакового целого C. |336| `u` | Указывается модификатором длины | Десятичное представление беззнакового целого C. |337| `o` | Указывается модификатором длины | Восьмеричное представление беззнакового целого C. |338| `x` | Указывается модификатором длины | Шестнадцатеричное представление беззнакового целого C (строчные буквы). |339| `X` | Указывается модификатором длины | Шестнадцатеричное представление беззнакового целого C (прописные буквы). |340| `c` | int | Один символ. |341| `s` | const char\* или const wchar\_t\* | Символьный массив C с нулевым завершителем. |342| `p` | const void\* | Шестнадцатеричное представление указателя C. В основном эквивалентно `printf("%p")`, за исключением того, что гарантированно начинается с литерала `0x` независимо от того, что возвращает `printf` на платформе. |343| `A` | [PyObject](https://python-all.ru/3.12/c-api/structures.html#c.PyObject)\* | Результат вызова [`ascii()`](https://python-all.ru/3.12/library/functions.html#ascii). |344| `U` | [PyObject](https://python-all.ru/3.12/c-api/structures.html#c.PyObject)\* | Объект Unicode. |345| `V` | [PyObject](https://python-all.ru/3.12/c-api/structures.html#c.PyObject)\*, const char\* или const wchar\_t\* | Объект Unicode (который может быть `NULL`) и завершающийся нулевым байтом символьный массив C в качестве второго параметра (который будет использован, если первый параметр равен `NULL`). |346| `S` | [PyObject](https://python-all.ru/3.12/c-api/structures.html#c.PyObject)\* | Результат вызова [`PyObject_Str()`](https://python-all.ru/3.12/c-api/object.html#c.PyObject_Str). |347| `R` | [PyObject](https://python-all.ru/3.12/c-api/structures.html#c.PyObject)\* | Результат вызова [`PyObject_Repr()`](https://python-all.ru/3.12/c-api/object.html#c.PyObject_Repr). |348349> **Примечание**350>351> Единицей форматтера ширины является количество символов, а не байтов. Единицей форматтера точности является количество байтов или `wchar_t` элементов (если используется модификатор длины `l`) для `"%s"` и `"%V"` (если аргумент `PyObject*` равен `NULL`), а также количество символов для `"%A"`, `"%U"`, `"%S"`, `"%R"` и `"%V"` (если аргумент `PyObject*` не равен `NULL`).352353> **Примечание**354>355> В отличие от C `printf()` флаг `0` действует, даже если для целочисленных преобразований задана точность (`d`, `i`, `u`, `o`, `x` или `X`).356357Изменено в версии 3.2: Добавлена поддержка `"%lld"` и `"%llu"`.358359Изменено в версии 3.3: Добавлена поддержка `"%li"`, `"%lli"` и `"%zi"`.360361Изменено в версии 3.4: Добавлена поддержка форматтеров ширины и точности для `"%s"`, `"%A"`, `"%U"`, `"%V"`, `"%S"`, `"%R"`.362363Изменено в версии 3.12: Добавлена поддержка спецификаторов преобразования `o` и `X`. Добавлена поддержка модификаторов длины `j` и `t`. Модификаторы длины теперь применяются ко всем целочисленным преобразованиям. Модификатор длины `l` теперь применяется к спецификаторам преобразования `s` и `V`. Добавлена поддержка переменной ширины и точности `*`. Добавлена поддержка флага `-`.364365Неопознанный символ формата теперь вызывает [`SystemError`](https://python-all.ru/3.12/library/exceptions.html#SystemError). В предыдущих версиях он приводил к тому, что оставшаяся часть строки формата копировалась в результирующую строку как есть, а все лишние аргументы отбрасывались.366367#### `PyObject *PyUnicode_FromFormatV(const char *format, va_list vargs)`368369*Возвращаемое значение: новая ссылка.*370371*Часть [Stable ABI](https://python-all.ru/3.12/c-api/stable.html#stable).*372373Идентично [`PyUnicode_FromFormat()`](https://python-all.ru/3.12/c-api/unicode.html#c.PyUnicode_FromFormat), за исключением того, что принимает ровно два аргумента.374375#### `PyObject *PyUnicode_FromObject(PyObject *obj)`376377*Возвращаемое значение: новая ссылка.*378379*Часть [Stable ABI](https://python-all.ru/3.12/c-api/stable.html#stable).*380381Копирует экземпляр подтипа Unicode в новый настоящий объект Unicode, если это необходимо. Если *obj* уже является настоящим объектом Unicode (не подтипом), возвращает новую [сильную ссылку](https://python-all.ru/3.12/glossary.html#term-strong-reference) на этот объект.382383Объекты, отличные от Unicode или его подтипов, вызывают [`TypeError`](https://python-all.ru/3.12/library/exceptions.html#TypeError).384385#### `PyObject *PyUnicode_FromEncodedObject(PyObject *obj, const char *encoding, const char *errors)`386387*Возвращаемое значение: новая ссылка.*388389*Часть [Stable ABI](https://python-all.ru/3.12/c-api/stable.html#stable).*390391Декодирует закодированный объект *obj* в объект Unicode.392393[`bytes`](https://python-all.ru/3.12/library/stdtypes.html#bytes), [`bytearray`](https://python-all.ru/3.12/library/stdtypes.html#bytearray) и другие [объекты, подобные байтовым строкам](https://python-all.ru/3.12/glossary.html#term-bytes-like-object) декодируются в соответствии с заданной *encoding* и с использованием обработки ошибок, определённой *errors*. Оба параметра могут быть `NULL`, чтобы интерфейс использовал значения по умолчанию (см. [Встроенные кодеки](https://python-all.ru/3.12/c-api/unicode.html#builtincodecs) для подробностей).394395Все остальные объекты, включая объекты Unicode, приводят к установке [`TypeError`](https://python-all.ru/3.12/library/exceptions.html#TypeError).396397API возвращает `NULL` в случае ошибки. Вызывающий отвечает за уменьшение счётчика ссылок (decref) возвращённых объектов.398399#### `const char *PyUnicode_GetDefaultEncoding(void)`400401*Часть [Stable ABI](https://python-all.ru/3.12/c-api/stable.html#stable).*402403Возвращает имя кодировки строк по умолчанию, `"utf-8"`. См. [`sys.getdefaultencoding()`](https://python-all.ru/3.12/library/sys.html#sys.getdefaultencoding).404405Возвращаемую строку не нужно освобождать, она действует до завершения интерпретатора.406407#### `Py_ssize_t PyUnicode_GetLength(PyObject *unicode)`408409*Часть [Stable ABI](https://python-all.ru/3.12/c-api/stable.html#stable) начиная с версии 3.7.*410411Возвращает длину объекта Unicode в кодовых точках.412413При ошибке устанавливает исключение и возвращает `-1`.414415Добавлено в версии 3.3.416417#### `Py_ssize_t PyUnicode_CopyCharacters(PyObject *to, Py_ssize_t to_start, PyObject *from, Py_ssize_t from_start, Py_ssize_t how_many)`418419Копирует символы из одного объекта Unicode в другой. При необходимости выполняет преобразование символов и, если возможно, использует `memcpy()`. Возвращает `-1` и устанавливает исключение при ошибке, в противном случае возвращает количество скопированных символов.420421Добавлено в версии 3.3.422423#### `Py_ssize_t PyUnicode_Fill(PyObject *unicode, Py_ssize_t start, Py_ssize_t length, Py_UCS4 fill_char)`424425Заполняет строку символом: записывает *fill\_char* в `unicode[start:start+length]`.426427Завершается ошибкой, если *fill\_char* больше максимального символа строки или если у строки больше одной ссылки.428429Возвращает количество записанных символов или `-1` и возбуждает исключение при ошибке.430431Добавлено в версии 3.3.432433#### `int PyUnicode_WriteChar(PyObject *unicode, Py_ssize_t index, Py_UCS4 character)`434435*Часть [Stable ABI](https://python-all.ru/3.12/c-api/stable.html#stable) начиная с версии 3.7.*436437Записывает символ в строку. Строка должна быть создана с помощью [`PyUnicode_New()`](https://python-all.ru/3.12/c-api/unicode.html#c.PyUnicode_New). Поскольку строки Unicode считаются неизменяемыми, строка не должна быть общей или уже хэшированной.438439Эта функция проверяет, что *unicode* является объектом Unicode, индекс не выходит за границы, и объект можно безопасно изменять (т.е. его счётчик ссылок равен единице).440441Возвращает `0` при успехе, `-1` при ошибке с установленным исключением.442443Добавлено в версии 3.3.444445#### `Py_UCS4 PyUnicode_ReadChar(PyObject *unicode, Py_ssize_t index)`446447*Часть [Stable ABI](https://python-all.ru/3.12/c-api/stable.html#stable) начиная с версии 3.7.*448449Читает символ из строки. Эта функция проверяет, что *unicode* является объектом Unicode и индекс не выходит за границы, в отличие от [`PyUnicode_READ_CHAR()`](https://python-all.ru/3.12/c-api/unicode.html#c.PyUnicode_READ_CHAR), которая не выполняет проверку ошибок.450451Возвращает символ при успехе, `-1` при ошибке с установленным исключением.452453Добавлено в версии 3.3.454455#### `PyObject *PyUnicode_Substring(PyObject *unicode, Py_ssize_t start, Py_ssize_t end)`456457*Возвращаемое значение: новая ссылка.*458459*Часть [Stable ABI](https://python-all.ru/3.12/c-api/stable.html#stable) начиная с версии 3.7.*460461Возвращает подстроку *unicode* от индекса символа *start* (включительно) до индекса *end* (исключительно). Отрицательные индексы не поддерживаются. При ошибке устанавливает исключение и возвращает `NULL`.462463Добавлено в версии 3.3.464465#### `Py_UCS4 *PyUnicode_AsUCS4(PyObject *unicode, Py_UCS4 *buffer, Py_ssize_t buflen, int copy_null)`466467*Часть [Stable ABI](https://python-all.ru/3.12/c-api/stable.html#stable) начиная с версии 3.7.*468469Копирует строку *unicode* в буфер UCS4, включая нулевой символ, если *copy\_null* установлен. Возвращает `NULL` и устанавливает исключение при ошибке (в частности, [`SystemError`](https://python-all.ru/3.12/library/exceptions.html#SystemError), если *buflen* меньше длины *unicode*). При успехе возвращается *buffer*.470471Добавлено в версии 3.3.472473#### `Py_UCS4 *PyUnicode_AsUCS4Copy(PyObject *unicode)`474475*Часть [Stable ABI](https://python-all.ru/3.12/c-api/stable.html#stable) начиная с версии 3.7.*476477Копирует строку *unicode* в новый буфер UCS4, выделенный с помощью [`PyMem_Malloc()`](https://python-all.ru/3.12/c-api/memory.html#c.PyMem_Malloc). В случае неудачи возвращается `NULL` с установленным [`MemoryError`](https://python-all.ru/3.12/library/exceptions.html#MemoryError). Возвращаемый буфер всегда содержит дополнительный нулевой код в конце.478479Добавлено в версии 3.3.480481### Кодировка локали482483Текущую кодировку локали можно использовать для декодирования текста из операционной системы.484485#### `PyObject *PyUnicode_DecodeLocaleAndSize(const char *str, Py_ssize_t length, const char *errors)`486487*Возвращаемое значение: новая ссылка.*488489*Часть [Stable ABI](https://python-all.ru/3.12/c-api/stable.html#stable) начиная с версии 3.7.*490491Decode a string from UTF-8 on Android and VxWorks, or from the current locale encoding on other platforms. The supported error handlers are `"strict"` and `"surrogateescape"` ([**PEP 383**](https://python-all.ru/3.12/c-api/unicode.html)). The decoder uses `"strict"` error handler if *errors* is `NULL`. *str* must end with a null character but cannot contain embedded null characters.492493Используйте [`PyUnicode_DecodeFSDefaultAndSize()`](https://python-all.ru/3.12/c-api/unicode.html#c.PyUnicode_DecodeFSDefaultAndSize) для декодирования строки из [кодировки файловой системы и обработчика ошибок](https://python-all.ru/3.12/glossary.html#term-filesystem-encoding-and-error-handler).494495Эта функция игнорирует [режим UTF-8 Python](https://python-all.ru/3.12/library/os.html#utf8-mode).496497> **См. также**498>499> Функция [`Py_DecodeLocale()`](https://python-all.ru/3.12/c-api/sys.html#c.Py_DecodeLocale).500501Добавлено в версии 3.3.502503Изменено в версии 3.7: Теперь функция также использует текущую кодировку локали для обработчика ошибок `surrogateescape`, за исключением Android. Ранее для `surrogateescape` использовался [`Py_DecodeLocale()`](https://python-all.ru/3.12/c-api/sys.html#c.Py_DecodeLocale), а для `strict` использовалась текущая кодировка локали.504505#### `PyObject *PyUnicode_DecodeLocale(const char *str, const char *errors)`506507*Возвращаемое значение: новая ссылка.*508509*Часть [Stable ABI](https://python-all.ru/3.12/c-api/stable.html#stable) начиная с версии 3.7.*510511Аналогично [`PyUnicode_DecodeLocaleAndSize()`](https://python-all.ru/3.12/c-api/unicode.html#c.PyUnicode_DecodeLocaleAndSize), но длина строки вычисляется с помощью `strlen()`.512513Добавлено в версии 3.3.514515#### `PyObject *PyUnicode_EncodeLocale(PyObject *unicode, const char *errors)`516517*Возвращаемое значение: новая ссылка.*518519*Часть [Stable ABI](https://python-all.ru/3.12/c-api/stable.html#stable) начиная с версии 3.7.*520521Encode a Unicode object to UTF-8 on Android and VxWorks, or to the current locale encoding on other platforms. The supported error handlers are `"strict"` and `"surrogateescape"` ([**PEP 383**](https://python-all.ru/3.12/c-api/unicode.html)). The encoder uses `"strict"` error handler if *errors* is `NULL`. Return a [`bytes`](https://python-all.ru/3.12/library/stdtypes.html#bytes) object. *unicode* cannot contain embedded null characters.522523Используйте [`PyUnicode_EncodeFSDefault()`](https://python-all.ru/3.12/c-api/unicode.html#c.PyUnicode_EncodeFSDefault) для кодирования строки в [кодировку файловой системы и обработчик ошибок](https://python-all.ru/3.12/glossary.html#term-filesystem-encoding-and-error-handler).524525Эта функция игнорирует [режим UTF-8 Python](https://python-all.ru/3.12/library/os.html#utf8-mode).526527> **См. также**528>529> Функция [`Py_EncodeLocale()`](https://python-all.ru/3.12/c-api/sys.html#c.Py_EncodeLocale).530531Добавлено в версии 3.3.532533Изменено в версии 3.7: Теперь функция также использует текущую кодировку локали для обработчика ошибок `surrogateescape`, за исключением Android. Ранее для `surrogateescape` использовался [`Py_EncodeLocale()`](https://python-all.ru/3.12/c-api/sys.html#c.Py_EncodeLocale), а для `strict` использовалась текущая кодировка локали.534535### Кодировка файловой системы536537Functions encoding to and decoding from the [filesystem encoding and error handler](https://python-all.ru/3.12/glossary.html#term-filesystem-encoding-and-error-handler) ([**PEP 383**](https://python-all.ru/3.12/c-api/unicode.html) and [**PEP 529**](https://python-all.ru/3.12/c-api/unicode.html)).538539Для кодирования имен файлов в [`bytes`](https://python-all.ru/3.12/library/stdtypes.html#bytes) во время разбора аргументов следует использовать конвертер `"O&"`, передавая `PyUnicode_FSConverter()` в качестве функции преобразования:540541#### `int PyUnicode_FSConverter(PyObject *obj, void *result)`542543*Часть [Stable ABI](https://python-all.ru/3.12/c-api/stable.html#stable).*544545[PyArg\_Parse\* converter](https://python-all.ru/3.12/c-api/arg.html#arg-parsing): encode [`str`](https://python-all.ru/3.12/library/stdtypes.html#str) objects – obtained directly or through the [`os.PathLike`](https://python-all.ru/3.12/library/os.html#os.PathLike) interface – to [`bytes`](https://python-all.ru/3.12/library/stdtypes.html#bytes) using [`PyUnicode_EncodeFSDefault()`](https://python-all.ru/3.12/c-api/unicode.html#c.PyUnicode_EncodeFSDefault); [`bytes`](https://python-all.ru/3.12/library/stdtypes.html#bytes) objects are output as-is. *result* must be an address of a C variable of type [PyObject](https://python-all.ru/3.12/c-api/structures.html#c.PyObject)\* (or [PyBytesObject](https://python-all.ru/3.12/c-api/bytes.html#c.PyBytesObject)\*). On success, set the variable to a new [strong reference](https://python-all.ru/3.12/glossary.html#term-strong-reference) to a [bytes object](https://python-all.ru/3.12/c-api/bytes.html#bytesobjects) which must be released when it is no longer used and return a non-zero value ([`Py_CLEANUP_SUPPORTED`](https://python-all.ru/3.12/c-api/arg.html#c.Py_CLEANUP_SUPPORTED)). Embedded null bytes are not allowed in the result. On failure, return `0` with an exception set.546547Если *obj* равно `NULL`, функция освобождает сильную ссылку, сохраненную в переменной, на которую указывает *result*, и возвращает `1`.548549Добавлено в версии 3.1.550551Изменено в версии 3.6: Принимает [объект, подобный пути](https://python-all.ru/3.12/glossary.html#term-path-like-object).552553Для декодирования имен файлов в [`str`](https://python-all.ru/3.12/library/stdtypes.html#str) во время разбора аргументов следует использовать конвертер `"O&"`, передавая `PyUnicode_FSDecoder()` в качестве функции преобразования:554555#### `int PyUnicode_FSDecoder(PyObject *obj, void *result)`556557*Часть [Stable ABI](https://python-all.ru/3.12/c-api/stable.html#stable).*558559[PyArg\_Parse\* converter](https://python-all.ru/3.12/c-api/arg.html#arg-parsing): decode [`bytes`](https://python-all.ru/3.12/library/stdtypes.html#bytes) objects – obtained either directly or indirectly through the [`os.PathLike`](https://python-all.ru/3.12/library/os.html#os.PathLike) interface – to [`str`](https://python-all.ru/3.12/library/stdtypes.html#str) using [`PyUnicode_DecodeFSDefaultAndSize()`](https://python-all.ru/3.12/c-api/unicode.html#c.PyUnicode_DecodeFSDefaultAndSize); [`str`](https://python-all.ru/3.12/library/stdtypes.html#str) objects are output as-is. *result* must be an address of a C variable of type [PyObject](https://python-all.ru/3.12/c-api/structures.html#c.PyObject)\* (or [PyUnicodeObject](https://python-all.ru/3.12/c-api/unicode.html#c.PyUnicodeObject)\*). On success, set the variable to a new [strong reference](https://python-all.ru/3.12/glossary.html#term-strong-reference) to a [Unicode object](https://python-all.ru/3.12/c-api/unicode.html#unicodeobjects) which must be released when it is no longer used and return a non-zero value ([`Py_CLEANUP_SUPPORTED`](https://python-all.ru/3.12/c-api/arg.html#c.Py_CLEANUP_SUPPORTED)). Embedded null characters are not allowed in the result. On failure, return `0` with an exception set.560561Если *obj* равно `NULL`, освободите сильную ссылку на объект, на который указывает *result*, и верните `1`.562563Добавлено в версии 3.2.564565Изменено в версии 3.6: Принимает [объект, подобный пути](https://python-all.ru/3.12/glossary.html#term-path-like-object).566567#### `PyObject *PyUnicode_DecodeFSDefaultAndSize(const char *str, Py_ssize_t size)`568569*Возвращаемое значение: новая ссылка.*570571*Часть [Stable ABI](https://python-all.ru/3.12/c-api/stable.html#stable).*572573Декодирует строку из [кодировки файловой системы и обработчика ошибок](https://python-all.ru/3.12/glossary.html#term-filesystem-encoding-and-error-handler).574575Если требуется декодировать строку из текущей кодировки локали, используйте [`PyUnicode_DecodeLocaleAndSize()`](https://python-all.ru/3.12/c-api/unicode.html#c.PyUnicode_DecodeLocaleAndSize).576577> **См. также**578>579> Функция [`Py_DecodeLocale()`](https://python-all.ru/3.12/c-api/sys.html#c.Py_DecodeLocale).580581Изменено в версии 3.6: Теперь используется [обработчик ошибок файловой системы](https://python-all.ru/3.12/glossary.html#term-filesystem-encoding-and-error-handler).582583#### `PyObject *PyUnicode_DecodeFSDefault(const char *str)`584585*Возвращаемое значение: новая ссылка.*586587*Часть [Stable ABI](https://python-all.ru/3.12/c-api/stable.html#stable).*588589Декодирует строку, завершающуюся нулевым символом, из [кодировки файловой системы и обработчика ошибок](https://python-all.ru/3.12/glossary.html#term-filesystem-encoding-and-error-handler).590591Если длина строки известна, используйте [`PyUnicode_DecodeFSDefaultAndSize()`](https://python-all.ru/3.12/c-api/unicode.html#c.PyUnicode_DecodeFSDefaultAndSize).592593Изменено в версии 3.6: Теперь используется [обработчик ошибок файловой системы](https://python-all.ru/3.12/glossary.html#term-filesystem-encoding-and-error-handler).594595#### `PyObject *PyUnicode_EncodeFSDefault(PyObject *unicode)`596597*Возвращаемое значение: новая ссылка.*598599*Часть [Stable ABI](https://python-all.ru/3.12/c-api/stable.html#stable).*600601Кодирует объект Unicode в [кодировку и обработчик ошибок файловой системы](https://python-all.ru/3.12/glossary.html#term-filesystem-encoding-and-error-handler) и возвращает [`bytes`](https://python-all.ru/3.12/library/stdtypes.html#bytes). Обратите внимание, что результирующий объект [`bytes`](https://python-all.ru/3.12/library/stdtypes.html#bytes) может содержать нулевые байты.602603Если требуется закодировать строку в текущую кодировку локали, используйте [`PyUnicode_EncodeLocale()`](https://python-all.ru/3.12/c-api/unicode.html#c.PyUnicode_EncodeLocale).604605> **См. также**606>607> Функция [`Py_EncodeLocale()`](https://python-all.ru/3.12/c-api/sys.html#c.Py_EncodeLocale).608609Добавлено в версии 3.2.610611Изменено в версии 3.6: Теперь используется [обработчик ошибок файловой системы](https://python-all.ru/3.12/glossary.html#term-filesystem-encoding-and-error-handler).612613### Поддержка wchar\_t614615`wchar_t` поддержка на платформах, которые её поддерживают:616617#### `PyObject *PyUnicode_FromWideChar(const wchar_t *wstr, Py_ssize_t size)`618619*Возвращаемое значение: новая ссылка.*620621*Часть [Stable ABI](https://python-all.ru/3.12/c-api/stable.html#stable).*622623Создаёт объект Unicode из буфера `wchar_t` *wstr* заданного *размера*. Передача `-1` в качестве *размера* указывает, что функция должна сама вычислить длину с помощью `wcslen()`. В случае ошибки возвращает `NULL`.624625#### `Py_ssize_t PyUnicode_AsWideChar(PyObject *unicode, wchar_t *wstr, Py_ssize_t size)`626627*Часть [Stable ABI](https://python-all.ru/3.12/c-api/stable.html#stable).*628629Копирует содержимое объекта Unicode в буфер `wchar_t` *wstr*. Копируется не более *size* `wchar_t` символов (исключая возможно завершающий нулевой символ). Возвращает количество скопированных `wchar_t` символов или `-1` в случае ошибки.630631Если *wstr* равно `NULL`, вместо этого возвращает *размер*, который потребуется для хранения всего *unicode*, включая завершающий нуль.632633Обратите внимание, что результирующая строка wchar\_t\* может быть как завершена нулевым символом, так и нет. Вызывающий код должен гарантировать, что строка wchar\_t\* завершается нулевым символом, если это требуется приложением. Кроме того, строка wchar\_t\* может содержать нулевые символы, что приведёт к усечению строки при использовании с большинством функций C.634635#### `wchar_t *PyUnicode_AsWideCharString(PyObject *unicode, Py_ssize_t *size)`636637*Часть [Stable ABI](https://python-all.ru/3.12/c-api/stable.html#stable) начиная с версии 3.7.*638639Преобразует объект Unicode в широкую строку. Результирующая строка всегда завершается нулевым символом. Если *size* не равно `NULL`, записывает количество широких символов (исключая завершающий нулевой символ) в *\*size*. Обратите внимание, что результирующая строка `wchar_t` может содержать нулевые символы, что приведёт к усечению строки при использовании с большинством функций C. Если *size* равно `NULL` и строка wchar\_t\* содержит нулевые символы, возбуждается [`ValueError`](https://python-all.ru/3.12/library/exceptions.html#ValueError).640641В случае успеха возвращает буфер, выделенный функцией [`PyMem_New`](https://python-all.ru/3.12/c-api/memory.html#c.PyMem_New) (для освобождения используйте [`PyMem_Free()`](https://python-all.ru/3.12/c-api/memory.html#c.PyMem_Free)). При ошибке возвращает `NULL`, а *\*size* не определён. Возбуждает [`MemoryError`](https://python-all.ru/3.12/library/exceptions.html#MemoryError), если выделение памяти не удалось.642643Добавлено в версии 3.2.644645Изменено в версии 3.7: Возбуждает [`ValueError`](https://python-all.ru/3.12/library/exceptions.html#ValueError), если *size* равно `NULL` и строка wchar\_t\* содержит нулевые символы.646647## Встроенные кодеки648649Python предоставляет набор встроенных кодеков, написанных на C для скорости. Все эти кодеки могут использоваться напрямую через следующие функции.650651Многие из следующих API принимают два аргумента: encoding и errors, и их семантика совпадает с семантикой соответствующих аргументов встроенного конструктора строк [`str()`](https://python-all.ru/3.12/library/stdtypes.html#str).652653Установка encoding в `NULL` приводит к использованию кодировки по умолчанию, которой является UTF-8. Файловые системные вызовы должны использовать [`PyUnicode_FSConverter()`](https://python-all.ru/3.12/c-api/unicode.html#c.PyUnicode_FSConverter) для кодирования имён файлов. Внутри используется [кодировка и обработчик ошибок файловой системы](https://python-all.ru/3.12/glossary.html#term-filesystem-encoding-and-error-handler).654655Обработка ошибок задаётся параметром errors, который также может быть установлен в `NULL`, что означает использование обработки по умолчанию, определённой для кодека. По умолчанию для всех встроенных кодеков используется строгий режим (возбуждается [`ValueError`](https://python-all.ru/3.12/library/exceptions.html#ValueError)).656657Все кодеки используют схожий интерфейс. Для простоты документированы только отличия от приведённого ниже общего описания.658659### Общие кодеки660661Это общие API кодеков:662663#### `PyObject *PyUnicode_Decode(const char *str, Py_ssize_t size, const char *encoding, const char *errors)`664665*Возвращаемое значение: новая ссылка.*666667*Часть [Stable ABI](https://python-all.ru/3.12/c-api/stable.html#stable).*668669Создаёт объект Unicode путём декодирования *size* байт закодированной строки *str*. Параметры *encoding* и *errors* имеют тот же смысл, что и одноимённые параметры встроенной функции [`str()`](https://python-all.ru/3.12/library/stdtypes.html#str). Используемый кодек ищется с помощью реестра кодеков Python. Возвращает `NULL`, если кодек возбудил исключение.670671#### `PyObject *PyUnicode_AsEncodedString(PyObject *unicode, const char *encoding, const char *errors)`672673*Возвращаемое значение: новая ссылка.*674675*Часть [Stable ABI](https://python-all.ru/3.12/c-api/stable.html#stable).*676677Кодирует объект Unicode и возвращает результат в виде объекта bytes. Параметры *encoding* и *errors* имеют тот же смысл, что и одноимённые параметры метода [`encode()`](https://python-all.ru/3.12/library/stdtypes.html#str.encode) объекта Unicode. Используемый кодек ищется с помощью реестра кодеков Python. Возвращает `NULL`, если кодек возбудил исключение.678679### Кодеки UTF-8680681Это API кодеков UTF-8:682683#### `PyObject *PyUnicode_DecodeUTF8(const char *str, Py_ssize_t size, const char *errors)`684685*Возвращаемое значение: новая ссылка.*686687*Часть [Stable ABI](https://python-all.ru/3.12/c-api/stable.html#stable).*688689Создаёт объект Unicode, декодируя *size* байтов UTF-8-закодированной строки *str*. Возвращает `NULL`, если кодек вызвал исключение.690691#### `PyObject *PyUnicode_DecodeUTF8Stateful(const char *str, Py_ssize_t size, const char *errors, Py_ssize_t *consumed)`692693*Возвращаемое значение: новая ссылка.*694695*Часть [Stable ABI](https://python-all.ru/3.12/c-api/stable.html#stable).*696697Если *consumed* равно `NULL`, ведёт себя как [`PyUnicode_DecodeUTF8()`](https://python-all.ru/3.12/c-api/unicode.html#c.PyUnicode_DecodeUTF8). Если *consumed* не равно `NULL`, неполные конечные последовательности байтов UTF-8 не будут считаться ошибкой. Эти байты не будут декодированы, а количество декодированных байтов будет сохранено в *consumed*.698699#### `PyObject *PyUnicode_AsUTF8String(PyObject *unicode)`700701*Возвращаемое значение: новая ссылка.*702703*Часть [Stable ABI](https://python-all.ru/3.12/c-api/stable.html#stable).*704705Кодирует объект Unicode в UTF-8 и возвращает результат в виде объекта bytes Python. Обработка ошибок – «strict». Возвращает `NULL`, если кодек вызвал исключение.706707#### `const char *PyUnicode_AsUTF8AndSize(PyObject *unicode, Py_ssize_t *size)`708709*Часть [Stable ABI](https://python-all.ru/3.12/c-api/stable.html#stable) начиная с версии 3.10.*710711Возвращает указатель на UTF-8-кодировку объекта Unicode и сохраняет размер закодированного представления (в байтах) в *size*. Аргумент *size* может быть `NULL`; в этом случае размер не сохраняется. Возвращаемый буфер всегда содержит дополнительный нулевой байт в конце (не включён в *size*), независимо от наличия других нулевых кодовых точек.712713В случае ошибки возвращается `NULL` с установленным исключением, а *size* не сохраняется.714715Это кеширует UTF-8-представление строки в объекте Unicode, и последующие вызовы будут возвращать указатель на тот же буфер. Вызывающий не отвечает за освобождение буфера. Буфер освобождается, а указатели на него становятся недействительными, когда объект Unicode удаляется сборщиком мусора.716717Добавлено в версии 3.3.718719Изменено в версии 3.7: Тип возвращаемого значения теперь `const char *` вместо `char *`.720721Изменено в версии 3.10: Эта функция является частью [ограниченного API](https://python-all.ru/3.12/c-api/stable.html#limited-c-api).722723#### `const char *PyUnicode_AsUTF8(PyObject *unicode)`724725Как [`PyUnicode_AsUTF8AndSize()`](https://python-all.ru/3.12/c-api/unicode.html#c.PyUnicode_AsUTF8AndSize), но не сохраняет размер.726727> **Предупреждение**728>729> Эта функция не имеет специального поведения для [нулевых символов](https://python-all.ru/3.12/c-api/unicode.html), встроенных в *unicode*. В результате строки, содержащие нулевые символы, останутся в возвращаемой строке, что некоторые функции C могут интерпретировать как конец строки, приводя к усечению. Если усечение является проблемой, рекомендуется использовать [`PyUnicode_AsUTF8AndSize()`](https://python-all.ru/3.12/c-api/unicode.html#c.PyUnicode_AsUTF8AndSize) вместо этого.730731Добавлено в версии 3.3.732733Изменено в версии 3.7: Тип возвращаемого значения теперь `const char *` вместо `char *`.734735### Кодеки UTF-32736737Это API кодеков UTF-32:738739#### `PyObject *PyUnicode_DecodeUTF32(const char *str, Py_ssize_t size, const char *errors, int *byteorder)`740741*Возвращаемое значение: новая ссылка.*742743*Часть [Stable ABI](https://python-all.ru/3.12/c-api/stable.html#stable).*744745Декодирует *size* байтов из буферной строки, закодированной в UTF-32, и возвращает соответствующий объект Unicode. *errors* (если не `NULL`) определяет обработку ошибок. По умолчанию – «strict».746747Если *byteorder* не равно `NULL`, декодер начинает декодирование с указанным порядком байтов:748749```c750*byteorder == -1: little endian751*byteorder == 0:  native order752*byteorder == 1:  big endian753```754755Если `*byteorder` равен нулю и первые четыре байта входных данных являются маркером порядка байтов (BOM), декодер переключается на этот порядок байтов, и BOM не копируется в результирующую строку Unicode. Если `*byteorder` равно `-1` или `1`, любой маркер порядка байтов копируется в выходные данные.756757После завершения *\*byteorder* устанавливается в текущий порядок байтов в конце входных данных.758759Если *byteorder* равен `NULL`, кодек запускается в режиме собственного порядка байтов.760761Возвращает `NULL`, если кодек вызвал исключение.762763#### `PyObject *PyUnicode_DecodeUTF32Stateful(const char *str, Py_ssize_t size, const char *errors, int *byteorder, Py_ssize_t *consumed)`764765*Возвращаемое значение: новая ссылка.*766767*Часть [Stable ABI](https://python-all.ru/3.12/c-api/stable.html#stable).*768769Если *consumed* равно `NULL`, ведёт себя как [`PyUnicode_DecodeUTF32()`](https://python-all.ru/3.12/c-api/unicode.html#c.PyUnicode_DecodeUTF32). Если *consumed* не равно `NULL`, [`PyUnicode_DecodeUTF32Stateful()`](https://python-all.ru/3.12/c-api/unicode.html#c.PyUnicode_DecodeUTF32Stateful) не будет считать неполные конечные последовательности байтов UTF-32 (например, количество байтов, не делящееся на четыре) ошибкой. Эти байты не будут декодированы, а количество декодированных байтов будет сохранено в *consumed*.770771#### `PyObject *PyUnicode_AsUTF32String(PyObject *unicode)`772773*Возвращаемое значение: новая ссылка.*774775*Часть [Stable ABI](https://python-all.ru/3.12/c-api/stable.html#stable).*776777Возвращает байтовую строку Python в кодировке UTF-32 в собственном порядке байтов. Строка всегда начинается с метки BOM. Обработка ошибок – «strict». Возвращает `NULL`, если кодек вызвал исключение.778779### Кодеки UTF-32780781Это API кодеков UTF-32:782783#### `PyObject *PyUnicode_DecodeUTF32(const char *str, Py_ssize_t size, const char *errors, int *byteorder)`784785*Возвращаемое значение: новая ссылка.*786787*Часть [Stable ABI](https://python-all.ru/3.12/c-api/stable.html#stable).*788789Декодирует *size* байтов из строки буфера, закодированной в UTF-16, и возвращает соответствующий объект Unicode. *errors* (если не `NULL`) определяет обработку ошибок. По умолчанию используется «strict».790791Если *byteorder* не равно `NULL`, декодер начинает декодирование с указанным порядком байтов:792793```c794*byteorder == -1: little endian795*byteorder == 0:  native order796*byteorder == 1:  big endian797```798799Если `*byteorder` равен нулю и первые два байта входных данных являются меткой порядка байтов (BOM), декодер переключается на этот порядок байтов, а BOM не копируется в результирующую строку Unicode. Если `*byteorder` равен `-1` или `1`, любая метка порядка байтов копируется в выходные данные (что приведёт к символу `\ufeff` или `\ufffe`).800801После завершения `*byteorder` устанавливается в текущий порядок байтов в конце входных данных.802803Если *byteorder* равен `NULL`, кодек запускается в режиме собственного порядка байтов.804805Возвращает `NULL`, если кодек вызвал исключение.806807#### `PyObject *PyUnicode_DecodeUTF16Stateful(const char *str, Py_ssize_t size, const char *errors, int *byteorder, Py_ssize_t *consumed)`808809*Возвращаемое значение: новая ссылка.*810811*Часть [Stable ABI](https://python-all.ru/3.12/c-api/stable.html#stable).*812813Если *consumed* равен `NULL`, ведёт себя как [`PyUnicode_DecodeUTF16()`](https://python-all.ru/3.12/c-api/unicode.html#c.PyUnicode_DecodeUTF16). Если *consumed* не равен `NULL`, [`PyUnicode_DecodeUTF16Stateful()`](https://python-all.ru/3.12/c-api/unicode.html#c.PyUnicode_DecodeUTF16Stateful) не будет рассматривать хвостовые неполные последовательности байтов UTF-16 (например, нечётное количество байтов или разбитую суррогатную пару) как ошибку. Эти байты не будут декодированы, а количество декодированных байтов будет сохранено в *consumed*.814815#### `PyObject *PyUnicode_AsUTF16String(PyObject *unicode)`816817*Возвращаемое значение: новая ссылка.*818819*Часть [Stable ABI](https://python-all.ru/3.12/c-api/stable.html#stable).*820821Возвращает байтовую строку Python в кодировке UTF-16 в собственном порядке байтов. Строка всегда начинается с метки BOM. Обработка ошибок – «strict». Возвращает `NULL`, если кодек вызвал исключение.822823### Кодеки UTF-7824825Это API кодеков UTF-7:826827#### `PyObject *PyUnicode_DecodeUTF7(const char *str, Py_ssize_t size, const char *errors)`828829*Возвращаемое значение: новая ссылка.*830831*Часть [Stable ABI](https://python-all.ru/3.12/c-api/stable.html#stable).*832833Создаёт объект Unicode путём декодирования *size* байтов строки, закодированной в UTF-7, *str*. Возвращает `NULL`, если кодек вызвал исключение.834835#### `PyObject *PyUnicode_DecodeUTF7Stateful(const char *str, Py_ssize_t size, const char *errors, Py_ssize_t *consumed)`836837*Возвращаемое значение: новая ссылка.*838839*Часть [Stable ABI](https://python-all.ru/3.12/c-api/stable.html#stable).*840841Если *consumed* равен `NULL`, ведёт себя как [`PyUnicode_DecodeUTF7()`](https://python-all.ru/3.12/c-api/unicode.html#c.PyUnicode_DecodeUTF7). Если *consumed* не равен `NULL`, хвостовые неполные секции base-64 UTF-7 не будут рассматриваться как ошибка. Эти байты не будут декодированы, а количество декодированных байтов будет сохранено в *consumed*.842843### Кодеки Unicode-Escape844845Это API кодеков «Unicode Escape»:846847#### `PyObject *PyUnicode_DecodeUnicodeEscape(const char *str, Py_ssize_t size, const char *errors)`848849*Возвращаемое значение: новая ссылка.*850851*Часть [Stable ABI](https://python-all.ru/3.12/c-api/stable.html#stable).*852853Создаёт объект Unicode путём декодирования *size* байтов строки, закодированной в Unicode-Escape, *str*. Возвращает `NULL`, если кодек вызвал исключение.854855#### `PyObject *PyUnicode_AsUnicodeEscapeString(PyObject *unicode)`856857*Возвращаемое значение: новая ссылка.*858859*Часть [Stable ABI](https://python-all.ru/3.12/c-api/stable.html#stable).*860861Кодирует объект Unicode с помощью Unicode-Escape и возвращает результат в виде объекта bytes. Обработка ошибок – «strict». Возвращает `NULL`, если кодек вызвал исключение.862863### Кодеки Raw-Unicode-Escape864865Это API кодеков «Raw Unicode Escape»:866867#### `PyObject *PyUnicode_DecodeRawUnicodeEscape(const char *str, Py_ssize_t size, const char *errors)`868869*Возвращаемое значение: новая ссылка.*870871*Часть [Stable ABI](https://python-all.ru/3.12/c-api/stable.html#stable).*872873Создаёт объект Unicode путём декодирования *size* байтов строки, закодированной в Raw-Unicode-Escape, *str*. Возвращает `NULL`, если кодек вызвал исключение.874875#### `PyObject *PyUnicode_AsRawUnicodeEscapeString(PyObject *unicode)`876877*Возвращаемое значение: новая ссылка.*878879*Часть [Stable ABI](https://python-all.ru/3.12/c-api/stable.html#stable).*880881Кодирует объект Unicode с помощью Raw-Unicode-Escape и возвращает результат в виде объекта bytes. Обработка ошибок – «strict». Возвращает `NULL`, если кодек вызвал исключение.882883### Кодеки Latin-1884885Это API кодеков Latin-1: Latin-1 соответствует первым 256 кодовым позициям Unicode, и только они принимаются кодеками при кодировании.886887#### `PyObject *PyUnicode_DecodeLatin1(const char *str, Py_ssize_t size, const char *errors)`888889*Возвращаемое значение: новая ссылка.*890891*Часть [Stable ABI](https://python-all.ru/3.12/c-api/stable.html#stable).*892893Создаёт объект Unicode путём декодирования *size* байтов строки *str*, закодированной в Latin-1. Возвращает `NULL`, если кодек выбросил исключение.894895#### `PyObject *PyUnicode_AsLatin1String(PyObject *unicode)`896897*Возвращаемое значение: новая ссылка.*898899*Часть [Stable ABI](https://python-all.ru/3.12/c-api/stable.html#stable).*900901Кодирует объект Unicode с помощью Latin-1 и возвращает результат в виде объекта bytes Python. Обработка ошибок – «strict». Возвращает `NULL`, если кодек выбросил исключение.902903### Кодеки ASCII904905Это API кодеков ASCII. Принимаются только 7-битные данные ASCII. Все остальные коды вызывают ошибки.906907#### `PyObject *PyUnicode_DecodeASCII(const char *str, Py_ssize_t size, const char *errors)`908909*Возвращаемое значение: новая ссылка.*910911*Часть [Stable ABI](https://python-all.ru/3.12/c-api/stable.html#stable).*912913Создаёт объект Unicode путём декодирования *size* байтов строки *str*, закодированной в ASCII. Возвращает `NULL`, если кодек выбросил исключение.914915#### `PyObject *PyUnicode_AsASCIIString(PyObject *unicode)`916917*Возвращаемое значение: новая ссылка.*918919*Часть [Stable ABI](https://python-all.ru/3.12/c-api/stable.html#stable).*920921Кодирует объект Unicode с помощью ASCII и возвращает результат в виде объекта bytes Python. Обработка ошибок – «strict». Возвращает `NULL`, если кодек выбросил исключение.922923### Кодеки с таблицей символов924925Этот кодек особенный тем, что его можно использовать для реализации множества различных кодеков (именно так и были получены большинство стандартных кодеков, входящих в пакет `encodings`). Кодек использует отображения для кодирования и декодирования символов. Предоставляемые объекты отображения должны поддерживать интерфейс отображения [`__getitem__()`](https://python-all.ru/3.12/reference/datamodel.html#object.__getitem__); словари и последовательности прекрасно работают.926927Это API кодеков отображения:928929#### `PyObject *PyUnicode_DecodeCharmap(const char *str, Py_ssize_t length, PyObject *mapping, const char *errors)`930931*Возвращаемое значение: новая ссылка.*932933*Часть [Stable ABI](https://python-all.ru/3.12/c-api/stable.html#stable).*934935Создаёт объект Unicode путём декодирования *size* байтов закодированной строки *str* с использованием заданного объекта *mapping*. Возвращает `NULL`, если кодек выбросил исключение.936937Если *mapping* равен `NULL`, будет применяться декодирование Latin-1. В противном случае *mapping* должен отображать порядковые номера байтов (целые числа в диапазоне от 0 до 255) в строки Unicode, целые числа (которые затем интерпретируются как кодовые позиции Unicode) или `None`. Неотображённые байты данных – те, которые вызывают [`LookupError`](https://python-all.ru/3.12/library/exceptions.html#LookupError), а также те, которые отображаются в `None`, `0xFFFE` или `'\ufffe'`, считаются неопределёнными отображениями и вызывают ошибку.938939#### `PyObject *PyUnicode_AsCharmapString(PyObject *unicode, PyObject *mapping)`940941*Возвращаемое значение: новая ссылка.*942943*Часть [Stable ABI](https://python-all.ru/3.12/c-api/stable.html#stable).*944945Кодирует объект Unicode с использованием заданного объекта *mapping* и возвращает результат в виде объекта bytes. Обработка ошибок – «strict». Возвращает `NULL`, если кодек выбросил исключение.946947Объект *mapping* должен отображать целые числа – кодовые позиции Unicode – в объекты bytes, целые числа в диапазоне от 0 до 255 или `None`. Неотображённые кодовые позиции символов (те, которые вызывают [`LookupError`](https://python-all.ru/3.12/library/exceptions.html#LookupError)), а также отображённые в `None` считаются «неопределённым отображением» и вызывают ошибку.948949Следующее API кодека особенное тем, что отображает Unicode в Unicode.950951#### `PyObject *PyUnicode_Translate(PyObject *unicode, PyObject *table, const char *errors)`952953*Возвращаемое значение: новая ссылка.*954955*Часть [Stable ABI](https://python-all.ru/3.12/c-api/stable.html#stable).*956957Преобразует строку, применяя к ней таблицу отображения символов, и возвращает результирующий объект Unicode. Возвращает `NULL`, если кодек выбросил исключение.958959Таблица отображения должна отображать целые числа – кодовые позиции Unicode – в целые числа – кодовые позиции Unicode – или в `None` (вызывает удаление символа).960961Таблицы отображения должны лишь предоставлять интерфейс [`__getitem__()`](https://python-all.ru/3.12/reference/datamodel.html#object.__getitem__); словари и последовательности работают хорошо. Неотображённые кодовые позиции символов (те, которые вызывают [`LookupError`](https://python-all.ru/3.12/library/exceptions.html#LookupError)) остаются нетронутыми и копируются как есть.962963*errors* имеет обычное для кодеков значение. Он может быть `NULL`, что означает использование обработки ошибок по умолчанию.964965### Кодеки MBCS для Windows966967Это API кодеков MBCS. В настоящее время они доступны только в Windows и используют преобразователи Win32 MBCS для выполнения преобразований. Обратите внимание, что MBCS (или DBCS) – это класс кодировок, а не одна конкретная. Целевая кодировка определяется пользовательскими настройками на машине, где выполняется кодек.968969#### `PyObject *PyUnicode_DecodeMBCS(const char *str, Py_ssize_t size, const char *errors)`970971*Возвращаемое значение: новая ссылка.*972973*Часть [стабильного ABI](https://python-all.ru/3.12/c-api/stable.html#stable) на Windows с версии 3.7.*974975Создаёт объект Unicode путём декодирования *size* байтов строки *str*, закодированной в MBCS. Возвращает `NULL`, если кодек выбросил исключение.976977#### `PyObject *PyUnicode_DecodeMBCSStateful(const char *str, Py_ssize_t size, const char *errors, Py_ssize_t *consumed)`978979*Возвращаемое значение: новая ссылка.*980981*Часть [стабильного ABI](https://python-all.ru/3.12/c-api/stable.html#stable) на Windows с версии 3.7.*982983Если *consumed* равно `NULL`, поведение аналогично [`PyUnicode_DecodeMBCS()`](https://python-all.ru/3.12/c-api/unicode.html#c.PyUnicode_DecodeMBCS). Если *consumed* не равно `NULL`, [`PyUnicode_DecodeMBCSStateful()`](https://python-all.ru/3.12/c-api/unicode.html#c.PyUnicode_DecodeMBCSStateful) не будет декодировать конечный ведущий байт, а количество декодированных байт будет сохранено в *consumed*.984985#### `PyObject *PyUnicode_DecodeCodePageStateful(int code_page, const char *str, Py_ssize_t size, const char *errors, Py_ssize_t *consumed)`986987*Возвращаемое значение: новая ссылка.*988989*Часть [стабильного ABI](https://python-all.ru/3.12/c-api/stable.html#stable) на Windows с версии 3.7.*990991Аналогично [`PyUnicode_DecodeMBCSStateful()`](https://python-all.ru/3.12/c-api/unicode.html#c.PyUnicode_DecodeMBCSStateful), но использует кодовую страницу, указанную в *code\_page*.992993#### `PyObject *PyUnicode_AsMBCSString(PyObject *unicode)`994995*Возвращаемое значение: новая ссылка.*996997*Часть [стабильного ABI](https://python-all.ru/3.12/c-api/stable.html#stable) на Windows с версии 3.7.*998999Кодирует объект Unicode с помощью MBCS и возвращает результат в виде объекта bytes. Обработка ошибок – «strict». Возвращает `NULL`, если кодек вызвал исключение.10001001#### `PyObject *PyUnicode_EncodeCodePage(int code_page, PyObject *unicode, const char *errors)`10021003*Возвращаемое значение: новая ссылка.*10041005*Часть [стабильного ABI](https://python-all.ru/3.12/c-api/stable.html#stable) на Windows с версии 3.7.*10061007Кодирует объект Unicode с помощью указанной кодовой страницы и возвращает объект bytes. Возвращает `NULL`, если кодек вызвал исключение. Используйте кодовую страницу `CP_ACP` для получения кодировщика MBCS.10081009Добавлено в версии 3.3.10101011### Методы и слоты10121013## Методы и слот-функции10141015Следующие API могут обрабатывать объекты Unicode и строки на входе (в описаниях мы называем их строками) и возвращают объекты Unicode или целые числа по необходимости.10161017Все они возвращают `NULL` или `-1` в случае возникновения исключения.10181019#### `PyObject *PyUnicode_Concat(PyObject *left, PyObject *right)`10201021*Возвращаемое значение: новая ссылка.*10221023*Часть [Stable ABI](https://python-all.ru/3.12/c-api/stable.html#stable).*10241025Объединяет две строки, возвращая новую строку Unicode.10261027#### `PyObject *PyUnicode_Split(PyObject *unicode, PyObject *sep, Py_ssize_t maxsplit)`10281029*Возвращаемое значение: новая ссылка.*10301031*Часть [Stable ABI](https://python-all.ru/3.12/c-api/stable.html#stable).*10321033Разделяет строку, возвращая список строк Unicode. Если *sep* равно `NULL`, разделение происходит по всем пробельным подстрокам. В противном случае разделение происходит по указанному разделителю. Будет выполнено не более *maxsplit* разбиений. Если значение отрицательное, ограничение не задано. Разделители не включаются в результирующий список.10341035При ошибке возвращает `NULL` с установленным исключением.10361037Эквивалентно [`str.split()`](https://python-all.ru/3.12/library/stdtypes.html#str.split).10381039#### `PyObject *PyUnicode_RSplit(PyObject *unicode, PyObject *sep, Py_ssize_t maxsplit)`10401041*Возвращаемое значение: новая ссылка.*10421043*Часть [Stable ABI](https://python-all.ru/3.12/c-api/stable.html#stable).*10441045Аналогично [`PyUnicode_Split()`](https://python-all.ru/3.12/c-api/unicode.html#c.PyUnicode_Split), но разделение начинается с конца строки.10461047При ошибке возвращает `NULL` с установленным исключением.10481049Эквивалентно [`str.rsplit()`](https://python-all.ru/3.12/library/stdtypes.html#str.rsplit).10501051#### `PyObject *PyUnicode_Splitlines(PyObject *unicode, int keepends)`10521053*Возвращаемое значение: новая ссылка.*10541055*Часть [Stable ABI](https://python-all.ru/3.12/c-api/stable.html#stable).*10561057Разделяет строку Unicode по символам конца строки, возвращая список строк Unicode. CRLF считается одним разрывом строки. Если *keepends* равно `0`, символы конца строки не включаются в результирующие строки.10581059#### `PyObject *PyUnicode_Partition(PyObject *unicode, PyObject *sep)`10601061*Возвращаемое значение: новая ссылка.*10621063*Часть [Stable ABI](https://python-all.ru/3.12/c-api/stable.html#stable).*10641065Разделяет строку Unicode по первому вхождению *sep* и возвращает кортеж из трёх элементов: часть до разделителя, сам разделитель и часть после разделителя. Если разделитель не найден, возвращает кортеж из трёх элементов: саму строку, а затем две пустые строки.10661067*sep* не должен быть пустым.10681069При ошибке возвращает `NULL` с установленным исключением.10701071Эквивалентно [`str.partition()`](https://python-all.ru/3.12/library/stdtypes.html#str.partition).10721073#### `PyObject *PyUnicode_RPartition(PyObject *unicode, PyObject *sep)`10741075*Возвращаемое значение: новая ссылка.*10761077*Часть [Stable ABI](https://python-all.ru/3.12/c-api/stable.html#stable).*10781079Аналогично [`PyUnicode_Partition()`](https://python-all.ru/3.12/c-api/unicode.html#c.PyUnicode_Partition), но разделяет строку Unicode по последнему вхождению *sep*. Если разделитель не найден, возвращает кортеж из трёх элементов: две пустые строки, а затем сама строка.10801081*sep* не должен быть пустым.10821083При ошибке возвращает `NULL` с установленным исключением.10841085Эквивалентно [`str.rpartition()`](https://python-all.ru/3.12/library/stdtypes.html#str.rpartition).10861087#### `PyObject *PyUnicode_Join(PyObject *separator, PyObject *seq)`10881089*Возвращаемое значение: новая ссылка.*10901091*Часть [Stable ABI](https://python-all.ru/3.12/c-api/stable.html#stable).*10921093Объединяет последовательность строк, используя заданный *разделитель*, и возвращает полученную Unicode-строку.10941095#### `Py_ssize_t PyUnicode_Tailmatch(PyObject *unicode, PyObject *substr, Py_ssize_t start, Py_ssize_t end, int direction)`10961097*Часть [Stable ABI](https://python-all.ru/3.12/c-api/stable.html#stable).*10981099Возвращает `1`, если *substr* совпадает с `unicode[start:end]` на заданном хвосте (*direction* == `-1` означает проверку на совпадение с началом, *direction* == `1` – с концом), иначе `0`. Возвращает `-1`, если произошла ошибка.11001101#### `Py_ssize_t PyUnicode_Find(PyObject *unicode, PyObject *substr, Py_ssize_t start, Py_ssize_t end, int direction)`11021103*Часть [Stable ABI](https://python-all.ru/3.12/c-api/stable.html#stable).*11041105Возвращает первую позицию *substr* в `unicode[start:end]`, используя заданное *direction* (*direction* == `1` означает прямой поиск, *direction* == `-1` – обратный). Возвращаемое значение – индекс первого совпадения; значение `-1` означает, что совпадений не найдено, а `-2` – что произошла ошибка и было установлено исключение.11061107#### `Py_ssize_t PyUnicode_FindChar(PyObject *unicode, Py_UCS4 ch, Py_ssize_t start, Py_ssize_t end, int direction)`11081109*Часть [Stable ABI](https://python-all.ru/3.12/c-api/stable.html#stable) начиная с версии 3.7.*11101111Возвращает первую позицию символа *ch* в `unicode[start:end]`, используя заданное *direction* (*direction* == `1` означает прямой поиск, *direction* == `-1` – обратный). Возвращаемое значение – индекс первого совпадения; значение `-1` означает, что совпадений не найдено, а `-2` – что произошла ошибка и было установлено исключение.11121113Добавлено в версии 3.3.11141115Изменено в версии 3.7: *start* и *end* теперь скорректированы, чтобы вести себя как `unicode[start:end]`.11161117#### `Py_ssize_t PyUnicode_Count(PyObject *unicode, PyObject *substr, Py_ssize_t start, Py_ssize_t end)`11181119*Часть [Stable ABI](https://python-all.ru/3.12/c-api/stable.html#stable).*11201121Возвращает количество неперекрывающихся вхождений *substr* в `unicode[start:end]`. Возвращает `-1`, если произошла ошибка.11221123#### `PyObject *PyUnicode_Replace(PyObject *unicode, PyObject *substr, PyObject *replstr, Py_ssize_t maxcount)`11241125*Возвращаемое значение: новая ссылка.*11261127*Часть [Stable ABI](https://python-all.ru/3.12/c-api/stable.html#stable).*11281129Заменяет не более *maxcount* вхождений *substr* в *unicode* на *replstr* и возвращает полученный Unicode-объект. *maxcount* == `-1` означает заменить все вхождения.11301131#### `int PyUnicode_Compare(PyObject *left, PyObject *right)`11321133*Часть [Stable ABI](https://python-all.ru/3.12/c-api/stable.html#stable).*11341135Сравнивает две строки и возвращает `-1`, `0`, `1` для случаев меньше, равно и больше соответственно.11361137Эта функция возвращает `-1` при ошибке, поэтому для проверки на ошибки следует вызывать [`PyErr_Occurred()`](https://python-all.ru/3.12/c-api/exceptions.html#c.PyErr_Occurred).11381139#### `int PyUnicode_CompareWithASCIIString(PyObject *unicode, const char *string)`11401141*Часть [Stable ABI](https://python-all.ru/3.12/c-api/stable.html#stable).*11421143Сравнивает Unicode-объект *unicode* со строкой *string* и возвращает `-1`, `0`, `1` для случаев меньше, равно и больше соответственно. Рекомендуется передавать только ASCII-строки, но функция интерпретирует входную строку как ISO-8859-1, если она содержит не-ASCII символы.11441145Эта функция не вызывает исключений.11461147#### `PyObject *PyUnicode_RichCompare(PyObject *left, PyObject *right, int op)`11481149*Возвращаемое значение: новая ссылка.*11501151*Часть [Stable ABI](https://python-all.ru/3.12/c-api/stable.html#stable).*11521153Сравнивает две строки Unicode и возвращает одно из следующих значений:11541155- `NULL` в случае, если возникло исключение1156- [`Py_True`](https://python-all.ru/3.12/c-api/bool.html#c.Py_True) или [`Py_False`](https://python-all.ru/3.12/c-api/bool.html#c.Py_False) для успешных сравнений1157- [`Py_NotImplemented`](https://python-all.ru/3.12/c-api/object.html#c.Py_NotImplemented) в случае, если комбинация типов неизвестна11581159Возможные значения для *op*: [`Py_GT`](https://python-all.ru/3.12/c-api/typeobj.html#c.Py_GT), [`Py_GE`](https://python-all.ru/3.12/c-api/typeobj.html#c.Py_GE), [`Py_EQ`](https://python-all.ru/3.12/c-api/typeobj.html#c.Py_EQ), [`Py_NE`](https://python-all.ru/3.12/c-api/typeobj.html#c.Py_NE), [`Py_LT`](https://python-all.ru/3.12/c-api/typeobj.html#c.Py_LT) и [`Py_LE`](https://python-all.ru/3.12/c-api/typeobj.html#c.Py_LE).11601161#### `PyObject *PyUnicode_Format(PyObject *format, PyObject *args)`11621163*Возвращаемое значение: новая ссылка.*11641165*Часть [Stable ABI](https://python-all.ru/3.12/c-api/stable.html#stable).*11661167Возвращает новый строковый объект из *format* и *args*; это аналог `format % args`.11681169#### `int PyUnicode_Contains(PyObject *unicode, PyObject *substr)`11701171*Часть [Stable ABI](https://python-all.ru/3.12/c-api/stable.html#stable).*11721173Проверяет, содержится ли *substr* в *unicode*, и возвращает true или false соответственно.11741175*substr* должен приводиться к строке Unicode из одного элемента. `-1` возвращается в случае ошибки.11761177#### `void PyUnicode_InternInPlace(PyObject **p_unicode)`11781179*Часть [Stable ABI](https://python-all.ru/3.12/c-api/stable.html#stable).*11801181Интернирует аргумент \*[p\_unicode](https://python-all.ru/3.12/c-api/unicode.html#c.PyUnicode_InternInPlace) на месте. Аргумент должен быть адресом переменной-указателя, указывающей на объект строки Python Unicode. Если уже существует интернированная строка, совпадающая с \*[p\_unicode](https://python-all.ru/3.12/c-api/unicode.html#c.PyUnicode_InternInPlace), она устанавливает \*[p\_unicode](https://python-all.ru/3.12/c-api/unicode.html#c.PyUnicode_InternInPlace) на неё (освобождая ссылку на старый строковый объект и создавая новую [сильную ссылку](https://python-all.ru/3.12/glossary.html#term-strong-reference) на интернированный строковый объект); в противном случае она оставляет \*[p\_unicode](https://python-all.ru/3.12/c-api/unicode.html#c.PyUnicode_InternInPlace) без изменений и интернирует его.11821183(Пояснение: хотя здесь много говорится о ссылках, считайте эту функцию нейтральной по отношению к ссылкам. Вы должны владеть объектом, который передаёте; после вызова вы больше не владеете переданной ссылкой, но приобретаете новую ссылку на результат.)11841185Эта функция никогда не вызывает исключение. При ошибке она оставляет свой аргумент без изменений, не интернируя его.11861187Экземпляры подклассов [`str`](https://python-all.ru/3.12/library/stdtypes.html#str) не могут быть интернированы, то есть [PyUnicode\_CheckExact](https://python-all.ru/3.12/c-api/unicode.html#c.PyUnicode_CheckExact)(\*[p\_unicode](https://python-all.ru/3.12/c-api/unicode.html#c.PyUnicode_InternInPlace)) должно быть истинно. Если это не так, то – как и при любой другой ошибке – аргумент остаётся без изменений.11881189Обратите внимание, что интернированные строки не являются «бессмертными». Вы должны сохранять ссылку на результат, чтобы получить выгоду от интернирования.11901191#### `PyObject *PyUnicode_InternFromString(const char *str)`11921193*Возвращаемое значение: новая ссылка.*11941195*Часть [Stable ABI](https://python-all.ru/3.12/c-api/stable.html#stable).*11961197Комбинация [`PyUnicode_FromString()`](https://python-all.ru/3.12/c-api/unicode.html#c.PyUnicode_FromString) и [`PyUnicode_InternInPlace()`](https://python-all.ru/3.12/c-api/unicode.html#c.PyUnicode_InternInPlace), предназначенная для статически выделенных строк.11981199Возвращает новую («владение») ссылку либо на новый интернированный объект строки Unicode, либо на ранее интернированный строковый объект с тем же значением.12001201Python может сохранять ссылку на результат или препятствовать его быстрой сборке мусора. Для интернирования неограниченного количества различных строк, например, поступающих от пользователя, предпочтительнее напрямую вызывать [`PyUnicode_FromString()`](https://python-all.ru/3.12/c-api/unicode.html#c.PyUnicode_FromString) и [`PyUnicode_InternInPlace()`](https://python-all.ru/3.12/c-api/unicode.html#c.PyUnicode_InternInPlace).1202