`unicode.md`

1078 строк · 95.5 КБ · обычная страница · сырой текст · скачать
1> **Источник:** https://python-all.ru/3.4/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.4/c-api/unicode.html) в Python 3.3, объекты Unicode внутри используют различные представления, чтобы обеспечить обработку полного диапазона символов Unicode, оставаясь при этом эффективными по памяти. Существуют особые случаи для строк, где все кодовые точки находятся ниже 128, 256 или 65536; в противном случае кодовые точки должны быть ниже 1114112 (то есть полного диапазона Unicode).1213Представления [`Py_UNICODE*`](https://python-all.ru/3.4/c-api/unicode.html#c.Py_UNICODE) и UTF-8 создаются по требованию и кэшируются в объекте Unicode. Представление [`Py_UNICODE*`](https://python-all.ru/3.4/c-api/unicode.html#c.Py_UNICODE) устарело и неэффективно; его следует избегать в ситуациях, чувствительных к производительности или памяти.1415Из-за перехода от старых API к новым unicode-объекты внутренне могут находиться в двух состояниях в зависимости от того, как они были созданы:1617- «канонические» unicode-объекты – это все объекты, созданные с помощью не устаревшего unicode API. Они используют наиболее эффективное представление, допускаемое реализацией.18- «Устаревшие» объекты Unicode были созданы через один из устаревших API (обычно [`PyUnicode_FromUnicode()`](https://python-all.ru/3.4/c-api/unicode.html#c.PyUnicode_FromUnicode)) и содержат только представление [`Py_UNICODE*`](https://python-all.ru/3.4/c-api/unicode.html#c.Py_UNICODE); перед вызовом любого другого API необходимо вызвать [`PyUnicode_READY()`](https://python-all.ru/3.4/c-api/unicode.html#c.PyUnicode_READY) для таких объектов.1920### Тип Unicode2122Это основные типы объектов Unicode, используемые в реализации Unicode в Python:2324**`Py_UCS4`**2526**`Py_UCS2`**2728**`Py_UCS1`**2930Эти типы являются псевдонимами беззнаковых целочисленных типов, достаточно широкими, чтобы содержать символы размером 32, 16 и 8 бит соответственно. При работе с отдельными символами Unicode используйте [`Py_UCS4`](https://python-all.ru/3.4/c-api/unicode.html#c.Py_UCS4).3132Новое в версии 3.3.3334**`Py_UNICODE`**3536Это typedef для `wchar_t`, который является 16-битным или 32-битным типом в зависимости от платформы.3738Изменено в версии 3.3: В предыдущих версиях это был 16-битный или 32-битный тип в зависимости от того, была ли выбрана «узкая» или «широкая» версия Unicode Python при сборке.3940**`PyASCIIObject`**4142**`PyCompactUnicodeObject`**4344**`PyUnicodeObject`**4546Эти подтипы [`PyObject`](https://python-all.ru/3.4/c-api/structures.html#c.PyObject) представляют объект Unicode в Python. В подавляющем большинстве случаев их не следует использовать напрямую, поскольку все функции API, работающие с объектами Unicode, принимают и возвращают указатели на [`PyObject`](https://python-all.ru/3.4/c-api/structures.html#c.PyObject).4748Новое в версии 3.3.4950**[PyTypeObject](https://python-all.ru/3.4/c-api/type.html#c.PyTypeObject) `PyUnicode_Type`**5152Этот экземпляр [`PyTypeObject`](https://python-all.ru/3.4/c-api/type.html#c.PyTypeObject) представляет тип Unicode в Python. Он доступен в коде Python как `str`.5354Следующие API на самом деле являются макросами C и могут использоваться для быстрых проверок и доступа к внутренним данным Unicode объектов только для чтения:5556#### `int PyUnicode_Check(PyObject *o)`5758Возвращает true, если объект *o* является объектом Unicode или экземпляром подтипа Unicode.5960#### `int PyUnicode_CheckExact(PyObject *o)`6162Возвращает true, если объект *o* является объектом Unicode, но не экземпляром подтипа.6364#### `int PyUnicode_READY(PyObject *o)`6566Убедитесь, что строковый объект *o* находится в «каноническом» представлении. Это необходимо перед использованием любых макросов доступа, описанных ниже.6768Возвращает 0 в случае успеха и -1 с установленным исключением в случае неудачи, что, в частности, происходит при сбое выделения памяти.6970Новое в версии 3.3.7172#### `Py_ssize_t PyUnicode_GET_LENGTH(PyObject *o)`7374Возвращает длину строки Unicode в кодовых точках. *o* должен быть объектом Unicode в «каноническом» представлении (не проверяется).7576Новое в версии 3.3.7778#### `Py_UCS1* PyUnicode_1BYTE_DATA(PyObject *o)`7980#### `Py_UCS2* PyUnicode_2BYTE_DATA(PyObject *o)`8182#### `Py_UCS4* PyUnicode_4BYTE_DATA(PyObject *o)`8384Возвращает указатель на каноническое представление, приведённое к целочисленным типам UCS1, UCS2 или UCS4 для прямого доступа к символам. Не проверяется, имеет ли каноническое представление правильный размер символа; используйте [`PyUnicode_KIND()`](https://python-all.ru/3.4/c-api/unicode.html#c.PyUnicode_KIND) для выбора правильного макроса. Убедитесь, что [`PyUnicode_READY()`](https://python-all.ru/3.4/c-api/unicode.html#c.PyUnicode_READY) был вызван перед доступом к этому.8586Новое в версии 3.3.8788**`PyUnicode_WCHAR_KIND`**8990**`PyUnicode_1BYTE_KIND`**9192**`PyUnicode_2BYTE_KIND`**9394**`PyUnicode_4BYTE_KIND`**9596Возвращаемые значения макроса [`PyUnicode_KIND()`](https://python-all.ru/3.4/c-api/unicode.html#c.PyUnicode_KIND).9798Новое в версии 3.3.99100#### `int PyUnicode_KIND(PyObject *o)`101102Возвращает одну из констант PyUnicode kind (см. выше), которые показывают, сколько байт на символ использует этот объект Unicode для хранения данных. *o* должен быть объектом Unicode в «каноническом» представлении (не проверяется).103104Новое в версии 3.3.105106#### `void* PyUnicode_DATA(PyObject *o)`107108Возвращает указатель void на необработанный буфер unicode. *o* должен быть объектом Unicode в «каноническом» представлении (не проверяется).109110Новое в версии 3.3.111112#### `void PyUnicode_WRITE(int kind, void *data, Py_ssize_t index, Py_UCS4 value)`113114Записывает в каноническое представление *data* (полученное с помощью [`PyUnicode_DATA()`](https://python-all.ru/3.4/c-api/unicode.html#c.PyUnicode_DATA)). Этот макрос не выполняет никаких проверок корректности и предназначен для использования в циклах. Вызывающий код должен кешировать значение *kind* и указатель *data*, полученные из других макросов. *index* – это индекс в строке (начиная с 0), а *value* – новое значение кодовой точки, которое должно быть записано в эту позицию.115116Новое в версии 3.3.117118#### `Py_UCS4 PyUnicode_READ(int kind, void *data, Py_ssize_t index)`119120Читает кодовую точку из канонического представления *data* (полученного с помощью [`PyUnicode_DATA()`](https://python-all.ru/3.4/c-api/unicode.html#c.PyUnicode_DATA)). Никаких проверок или вызовов готовности не выполняется.121122Новое в версии 3.3.123124#### `Py_UCS4 PyUnicode_READ_CHAR(PyObject *o, Py_ssize_t index)`125126Читает символ из объекта Unicode *o*, который должен находиться в «каноническом» представлении. Это менее эффективно, чем [`PyUnicode_READ()`](https://python-all.ru/3.4/c-api/unicode.html#c.PyUnicode_READ), если выполняется несколько последовательных чтений.127128Новое в версии 3.3.129130#### `PyUnicode_MAX_CHAR_VALUE(PyObject *o)`131132Возвращает максимальную кодовую точку, подходящую для создания другой строки на основе *o*, который должен быть в «каноническом» представлении. Это всегда приблизительное значение, но более эффективно, чем итерация по строке.133134Новое в версии 3.3.135136#### `int PyUnicode_ClearFreeList()`137138Очищает список свободных элементов. Возвращает общее количество освобождённых элементов.139140#### `Py_ssize_t PyUnicode_GET_SIZE(PyObject *o)`141142Возвращает размер устаревшего представления [`Py_UNICODE`](https://python-all.ru/3.4/c-api/unicode.html#c.Py_UNICODE) в кодовых единицах (суррогатные пары считаются за 2 единицы). *o* должен быть объектом Unicode (проверка не выполняется).143144Устарело с версии 3.3, будет удалено в версии 4.0: Часть старого API Unicode, переходите на использование [`PyUnicode_GET_LENGTH()`](https://python-all.ru/3.4/c-api/unicode.html#c.PyUnicode_GET_LENGTH).145146#### `Py_ssize_t PyUnicode_GET_DATA_SIZE(PyObject *o)`147148Возвращает размер устаревшего представления [`Py_UNICODE`](https://python-all.ru/3.4/c-api/unicode.html#c.Py_UNICODE) в байтах. *o* должен быть объектом Unicode (проверка не выполняется).149150Устарело с версии 3.3, будет удалено в версии 4.0: Часть старого API Unicode, переходите на использование [`PyUnicode_GET_LENGTH()`](https://python-all.ru/3.4/c-api/unicode.html#c.PyUnicode_GET_LENGTH).151152#### `Py_UNICODE* PyUnicode_AS_UNICODE(PyObject *o)`153154#### `const char* PyUnicode_AS_DATA(PyObject *o)`155156Возвращает указатель на представление [`Py_UNICODE`](https://python-all.ru/3.4/c-api/unicode.html#c.Py_UNICODE) объекта. Возвращаемый буфер всегда завершается дополнительным нулевым кодовым символом. Он также может содержать встроенные нулевые кодовые символы, что приведёт к усечению строки при использовании в большинстве функций C. Форма `AS_DATA` приводит указатель к типу `const char *`. Аргумент *o* должен быть объектом Unicode (проверка не выполняется).157158Изменено в версии 3.3: Этот макрос теперь неэффективен – поскольку во многих случаях представление [`Py_UNICODE`](https://python-all.ru/3.4/c-api/unicode.html#c.Py_UNICODE) не существует и его нужно создавать – и может завершиться ошибкой (возвращает *NULL* с установленным исключением). Перенесите код на использование новых макросов `PyUnicode_nBYTE_DATA()` или используйте [`PyUnicode_WRITE()`](https://python-all.ru/3.4/c-api/unicode.html#c.PyUnicode_WRITE) или [`PyUnicode_READ()`](https://python-all.ru/3.4/c-api/unicode.html#c.PyUnicode_READ).159160Устарело с версии 3.3, будет удалено в версии 4.0: Часть старого API Unicode, переходите на использование семейства макросов `PyUnicode_nBYTE_DATA()`.161162### Свойства символов Unicode163164Unicode предоставляет множество различных свойств символов. Наиболее востребованные из них доступны через следующие макросы, которые сопоставляются с функциями на C в зависимости от конфигурации Python.165166#### `int Py_UNICODE_ISSPACE(Py_UNICODE ch)`167168Возвращает 1 или 0 в зависимости от того, является ли *ch* пробельным символом.169170#### `int Py_UNICODE_ISLOWER(Py_UNICODE ch)`171172Возвращает 1 или 0 в зависимости от того, является ли *ch* символом нижнего регистра.173174#### `int Py_UNICODE_ISUPPER(Py_UNICODE ch)`175176Возвращает 1 или 0 в зависимости от того, является ли *ch* символом верхнего регистра.177178#### `int Py_UNICODE_ISTITLE(Py_UNICODE ch)`179180Возвращает 1 или 0 в зависимости от того, является ли *ch* символом в регистре заголовка.181182#### `int Py_UNICODE_ISLINEBREAK(Py_UNICODE ch)`183184Возвращает 1 или 0 в зависимости от того, является ли *ch* символом разрыва строки.185186#### `int Py_UNICODE_ISDECIMAL(Py_UNICODE ch)`187188Возвращает 1 или 0 в зависимости от того, является ли *ch* десятичной цифрой.189190#### `int Py_UNICODE_ISDIGIT(Py_UNICODE ch)`191192Возвращает 1 или 0 в зависимости от того, является ли *ch* цифровым символом.193194#### `int Py_UNICODE_ISNUMERIC(Py_UNICODE ch)`195196Возвращает 1 или 0 в зависимости от того, является ли *ch* числовым символом.197198#### `int Py_UNICODE_ISALPHA(Py_UNICODE ch)`199200Возвращает 1 или 0 в зависимости от того, является ли *ch* буквенным символом.201202#### `int Py_UNICODE_ISALNUM(Py_UNICODE ch)`203204Возвращает 1 или 0 в зависимости от того, является ли *ch* буквенно-цифровым символом.205206#### `int Py_UNICODE_ISPRINTABLE(Py_UNICODE ch)`207208Возвращает 1 или 0 в зависимости от того, является ли *ch* печатаемым символом. Непечатаемые символы – это символы, определённые в базе данных Unicode как «Other» или «Separator», за исключением пробела ASCII (0x20), который считается печатаемым. (Обратите внимание, что печатаемые символы в этом контексте – это те, которые не должны экранироваться при вызове [`repr()`](https://python-all.ru/3.4/library/functions.html#repr) для строки. Это не влияет на обработку строк, записываемых в [`sys.stdout`](https://python-all.ru/3.4/library/sys.html#sys.stdout) или [`sys.stderr`](https://python-all.ru/3.4/library/sys.html#sys.stderr).)209210Эти API можно использовать для быстрых прямых преобразований символов:211212#### `Py_UNICODE Py_UNICODE_TOLOWER(Py_UNICODE ch)`213214Возвращает символ *ch*, преобразованный в нижний регистр.215216Устарело с версии 3.3: Эта функция использует простые отображения регистра.217218#### `Py_UNICODE Py_UNICODE_TOUPPER(Py_UNICODE ch)`219220Возвращает символ *ch*, преобразованный в верхний регистр.221222Устарело с версии 3.3: Эта функция использует простые отображения регистра.223224#### `Py_UNICODE Py_UNICODE_TOTITLE(Py_UNICODE ch)`225226Возвращает символ *ch*, приведённый к регистру заголовка.227228Устарело с версии 3.3: Эта функция использует простые отображения регистра.229230#### `int Py_UNICODE_TODECIMAL(Py_UNICODE ch)`231232Возвращает символ *ch*, преобразованный в десятичное положительное целое. Возвращает `-1`, если это невозможно. Этот макрос не вызывает исключений.233234#### `int Py_UNICODE_TODIGIT(Py_UNICODE ch)`235236Возвращает символ *ch*, преобразованный в целое однозначное число. Возвращает `-1`, если это невозможно. Этот макрос не вызывает исключений.237238#### `double Py_UNICODE_TONUMERIC(Py_UNICODE ch)`239240Возвращает символ *ch*, преобразованный в double. Возвращает `-1.0`, если это невозможно. Этот макрос не вызывает исключений.241242Эти API можно использовать для работы с суррогатами:243244**`Py_UNICODE_IS_SURROGATE`(ch)**245246Проверяет, является ли *ch* суррогатом (`0xD800 <= ch <= 0xDFFF`).247248**`Py_UNICODE_IS_HIGH_SURROGATE`(ch)**249250Проверяет, является ли *ch* старшим суррогатом (`0xD800 <= ch <= 0xDBFF`).251252**`Py_UNICODE_IS_LOW_SURROGATE`(ch)**253254Проверяет, является ли *ch* младшим суррогатом (`0xDC00 <= ch <= 0xDFFF`).255256**`Py_UNICODE_JOIN_SURROGATES`(high, low)**257258Объединяет два суррогатных символа и возвращает одно значение Py\_UCS4. *high* и *low* – это соответственно старший и младший суррогаты в суррогатной паре.259260### Создание строк Unicode и доступ к ним261262Для создания объектов Unicode и доступа к их базовым свойствам последовательности используйте следующие API:263264#### `PyObject* PyUnicode_New(Py_ssize_t size, Py_UCS4 maxchar)`265266Создаёт новый объект Unicode. *maxchar* должен быть истинным максимальным кодом, который будет помещён в строку. В качестве приближения его можно округлить до ближайшего значения из последовательности 127, 255, 65535, 1114111.267268Это рекомендуемый способ выделения нового объекта Unicode. Объекты, созданные с помощью этой функции, не подлежат изменению размера.269270Новое в версии 3.3.271272#### `PyObject* PyUnicode_FromKindAndData(int kind, const void *buffer, Py_ssize_t size)`273274Создаёт новый объект Unicode с заданным *kind* (возможные значения: [`PyUnicode_1BYTE_KIND`](https://python-all.ru/3.4/c-api/unicode.html#c.PyUnicode_1BYTE_KIND) и т. д., возвращаемые [`PyUnicode_KIND()`](https://python-all.ru/3.4/c-api/unicode.html#c.PyUnicode_KIND)). *buffer* должен указывать на массив из *size* единиц по 1, 2 или 4 байта на символ, в соответствии с kind.275276Новое в версии 3.3.277278#### `PyObject* PyUnicode_FromStringAndSize(const char *u, Py_ssize_t size)`279280Создает объект Unicode из буфера символов *u*. Байты интерпретируются как закодированные в UTF-8. Буфер копируется в новый объект. Если буфер не является *NULL*, возвращаемое значение может быть разделяемым объектом, т.е. изменение данных не допускается.281282Если *u* равен *NULL*, эта функция ведёт себя как [`PyUnicode_FromUnicode()`](https://python-all.ru/3.4/c-api/unicode.html#c.PyUnicode_FromUnicode) с буфером, равным *NULL*. Такое использование устарело в пользу [`PyUnicode_New()`](https://python-all.ru/3.4/c-api/unicode.html#c.PyUnicode_New).283284#### `PyObject *PyUnicode_FromString(const char *u)`285286Создаёт объект Unicode из UTF-8-кодированного символьного буфера с завершающим нулём *u*.287288#### `PyObject* PyUnicode_FromFormat(const char *format, ...)`289290Принимает строку *format* в стиле C `printf()` и переменное количество аргументов, вычисляет размер результирующей Python-строки Unicode и возвращает строку с отформатированными значениями. Переменные аргументы должны быть типами C и должны точно соответствовать символам формата в строке *format*, закодированной в ASCII. Допускаются следующие символы формата:291292| Символы формата | Тип | Описание |293| --- | --- | --- |294| `%%` | *н/д* | Буквальный символ %. |295| `%c` | int | Одиночный символ, представленный как C int. |296| `%d` | int | Полностью эквивалентно `printf("%d")`. |297| `%u` | unsigned int | Полностью эквивалентно `printf("%u")`. |298| `%ld` | long | Полностью эквивалентно `printf("%ld")`. |299| `%li` | long | Полностью эквивалентно `printf("%li")`. |300| `%lu` | unsigned long | Полностью эквивалентно `printf("%lu")`. |301| `%lld` | long long | Полностью эквивалентно `printf("%lld")`. |302| `%lli` | long long | Полностью эквивалентно `printf("%lli")`. |303| `%llu` | unsigned long long | Полностью эквивалентно `printf("%llu")`. |304| `%zd` | Py\_ssize\_t | Полностью эквивалентно `printf("%zd")`. |305| `%zi` | Py\_ssize\_t | Полностью эквивалентно `printf("%zi")`. |306| `%zu` | size\_t | Полностью эквивалентно `printf("%zu")`. |307| `%i` | int | Полностью эквивалентно `printf("%i")`. |308| `%x` | int | Полностью эквивалентно `printf("%x")`. |309| `%s` | char\* | Нуль-терминированный массив символов C. |310| `%p` | void\* | Шестнадцатеричное представление указателя C. В основном эквивалентно `printf("%p")` за исключением того, что гарантированно начинается с литерала `0x` независимо от того, что выдает `printf` на данной платформе. |311| `%A` | PyObject\* | Результат вызова [`ascii()`](https://python-all.ru/3.4/library/functions.html#ascii). |312| `%U` | PyObject\* | Unicode-объект. |313| `%V` | PyObject\*, char \* | Unicode-объект (может быть *NULL*) и завершающийся нулевым символом C-массив символов в качестве второго параметра (используется, если первый параметр равен *NULL*). |314| `%S` | PyObject\* | Результат вызова [`PyObject_Str()`](https://python-all.ru/3.4/c-api/object.html#c.PyObject_Str). |315| `%R` | PyObject\* | Результат вызова [`PyObject_Repr()`](https://python-all.ru/3.4/c-api/object.html#c.PyObject_Repr). |316317Нераспознанный символ формата приводит к тому, что вся оставшаяся строка формата копируется как есть в результирующую строку, а все лишние аргументы отбрасываются.318319> **Примечание**320>321> Спецификаторы формата *"%lld"* и *"%llu"* доступны только при определённом `HAVE_LONG_LONG`.322323> **Примечание**324>325> Единицей форматирования ширины является количество символов, а не байтов. Единицей форматирования точности является количество байтов для `"%s"` и `"%V"` (если аргумент `PyObject*` равен NULL) и количество символов для `"%A"`, `"%U"`, `"%S"`, `"%R"` и `"%V"` (если аргумент `PyObject*` не равен NULL).326327Изменено в версии 3.2: Добавлена поддержка `"%lld"` и `"%llu"`.328329Изменено в версии 3.3: Добавлена поддержка `"%li"`, `"%lli"` и `"%zi"`.330331Изменено в версии 3.4: Добавлена поддержка форматирования ширины и точности для `"%s"`, `"%A"`, `"%U"`, `"%V"`, `"%S"`, `"%R"`.332333#### `PyObject* PyUnicode_FromFormatV(const char *format, va_list vargs)`334335Идентична [`PyUnicode_FromFormat()`](https://python-all.ru/3.4/c-api/unicode.html#c.PyUnicode_FromFormat), за исключением того, что принимает ровно два аргумента.336337#### `PyObject* PyUnicode_FromEncodedObject(PyObject *obj, const char *encoding, const char *errors)`338339*Возвращаемое значение: новая ссылка.*340341Преобразует закодированный объект *obj* в объект Unicode и возвращает ссылку с увеличенным счётчиком ссылок.342343[`bytes`](https://python-all.ru/3.4/library/functions.html#bytes), [`bytearray`](https://python-all.ru/3.4/library/functions.html#bytearray) и другие [*bytes-подобные объекты*](https://python-all.ru/3.4/glossary.html#term-bytes-like-object) декодируются в соответствии с заданной *encoding* и с использованием обработки ошибок, определяемой *errors*. Оба могут быть равны *NULL*, чтобы интерфейс использовал значения по умолчанию (подробнее см. в следующем разделе).344345Все остальные объекты, включая объекты Unicode, вызывают установку [`TypeError`](https://python-all.ru/3.4/library/exceptions.html#TypeError).346347API возвращает *NULL* при ошибке. Вызывающий отвечает за уменьшение счётчика ссылок возвращённых объектов.348349#### `Py_ssize_t PyUnicode_GetLength(PyObject *unicode)`350351Возвращает длину объекта Unicode в кодовых точках.352353Новое в версии 3.3.354355#### `int PyUnicode_CopyCharacters(PyObject *to, Py_ssize_t to_start, PyObject *from, Py_ssize_t from_start, Py_ssize_t how_many)`356357Копирует символы из одного объекта Unicode в другой. Эта функция выполняет преобразование символов при необходимости и использует `memcpy()`, если возможно. Возвращает `-1` и устанавливает исключение при ошибке, в противном случае возвращает `0`.358359Новое в версии 3.3.360361#### `Py_ssize_t PyUnicode_Fill(PyObject *unicode, Py_ssize_t start, Py_ssize_t length, Py_UCS4 fill_char)`362363Fill a string with a character: write *fill\_char* into `unicode[start:start+length]`.364365Завершается ошибкой, если *fill\_char* больше максимального символа строки или если у строки больше одной ссылки.366367Возвращает количество записанных символов или `-1` и возбуждает исключение при ошибке.368369Новое в версии 3.3.370371#### `int PyUnicode_WriteChar(PyObject *unicode, Py_ssize_t index, Py_UCS4 character)`372373Write a character to a string. The string must have been created through [`PyUnicode_New()`](https://python-all.ru/3.4/c-api/unicode.html#c.PyUnicode_New). Since Unicode strings are supposed to be immutable, the string must not be shared, or have been hashed yet.374375This function checks that *unicode* is a Unicode object, that the index is not out of bounds, and that the object can be modified safely (i.e. that it its reference count is one), in contrast to the macro version `PyUnicode_WRITE_CHAR()`.376377Новое в версии 3.3.378379#### `Py_UCS4 PyUnicode_ReadChar(PyObject *unicode, Py_ssize_t index)`380381Read a character from a string. This function checks that *unicode* is a Unicode object and the index is not out of bounds, in contrast to the macro version [`PyUnicode_READ_CHAR()`](https://python-all.ru/3.4/c-api/unicode.html#c.PyUnicode_READ_CHAR).382383Новое в версии 3.3.384385#### `PyObject* PyUnicode_Substring(PyObject *str, Py_ssize_t start, Py_ssize_t end)`386387Возвращает подстроку *str* от индекса символа *start* (включительно) до индекса символа *end* (исключительно). Отрицательные индексы не поддерживаются.388389Новое в версии 3.3.390391#### `Py_UCS4* PyUnicode_AsUCS4(PyObject *u, Py_UCS4 *buffer, Py_ssize_t buflen, int copy_null)`392393Copy the string *u* into a UCS4 buffer, including a null character, if *copy\_null* is set. Returns *NULL* and sets an exception on error (in particular, a [`ValueError`](https://python-all.ru/3.4/library/exceptions.html#ValueError) if *buflen* is smaller than the length of *u*). *buffer* is returned on success.394395Новое в версии 3.3.396397#### `Py_UCS4* PyUnicode_AsUCS4Copy(PyObject *u)`398399Copy the string *u* into a new UCS4 buffer that is allocated using [`PyMem_Malloc()`](https://python-all.ru/3.4/c-api/memory.html#c.PyMem_Malloc). If this fails, *NULL* is returned with a [`MemoryError`](https://python-all.ru/3.4/library/exceptions.html#MemoryError) set. The returned buffer always has an extra null code point appended.400401Новое в версии 3.3.402403### Устаревшие API Py\_UNICODE404405Устарело с версии 3.3, будет удалено в версии 4.0.406407Эти функции API устарели с реализацией [**PEP 393**](https://python-all.ru/3.4/c-api/unicode.html). Модули-расширения могут продолжать их использовать, поскольку они не будут удалены в Python 3.x, но следует учитывать, что их использование теперь может приводить к снижению производительности и увеличению потребления памяти.408409#### `PyObject* PyUnicode_FromUnicode(const Py_UNICODE *u, Py_ssize_t size)`410411*Возвращаемое значение: новая ссылка.*412413Создаёт объект Unicode из буфера *u* типа Py\_UNICODE заданного размера. *u* может быть *NULL*, что приводит к неопределённости содержимого. Пользователь должен заполнить необходимые данные. Буфер копируется в новый объект.414415Если буфер не равен *NULL*, возвращаемое значение может быть разделяемым объектом. Поэтому изменение результирующего объекта Unicode допускается только когда *u* равен *NULL*.416417If the buffer is *NULL*, [`PyUnicode_READY()`](https://python-all.ru/3.4/c-api/unicode.html#c.PyUnicode_READY) must be called once the string content has been filled before using any of the access macros such as [`PyUnicode_KIND()`](https://python-all.ru/3.4/c-api/unicode.html#c.PyUnicode_KIND).418419Please migrate to using [`PyUnicode_FromKindAndData()`](https://python-all.ru/3.4/c-api/unicode.html#c.PyUnicode_FromKindAndData) or [`PyUnicode_New()`](https://python-all.ru/3.4/c-api/unicode.html#c.PyUnicode_New).420421#### `Py_UNICODE* PyUnicode_AsUnicode(PyObject *unicode)`422423Return a read-only pointer to the Unicode object’s internal [`Py_UNICODE`](https://python-all.ru/3.4/c-api/unicode.html#c.Py_UNICODE) buffer, or *NULL* on error. This will create the [`Py_UNICODE*`](https://python-all.ru/3.4/c-api/unicode.html#c.Py_UNICODE) representation of the object if it is not yet available. The buffer is always terminated with an extra null code point. Note that the resulting [`Py_UNICODE`](https://python-all.ru/3.4/c-api/unicode.html#c.Py_UNICODE) string may also contain embedded null code points, which would cause the string to be truncated when used in most C functions.424425Please migrate to using [`PyUnicode_AsUCS4()`](https://python-all.ru/3.4/c-api/unicode.html#c.PyUnicode_AsUCS4), [`PyUnicode_Substring()`](https://python-all.ru/3.4/c-api/unicode.html#c.PyUnicode_Substring), [`PyUnicode_ReadChar()`](https://python-all.ru/3.4/c-api/unicode.html#c.PyUnicode_ReadChar) or similar new APIs.426427#### `PyObject* PyUnicode_TransformDecimalToASCII(Py_UNICODE *s, Py_ssize_t size)`428429Create a Unicode object by replacing all decimal digits in [`Py_UNICODE`](https://python-all.ru/3.4/c-api/unicode.html#c.Py_UNICODE) buffer of the given *size* by ASCII digits 0–9 according to their decimal value. Return *NULL* if an exception occurs.430431#### `Py_UNICODE* PyUnicode_AsUnicodeAndSize(PyObject *unicode, Py_ssize_t *size)`432433Like [`PyUnicode_AsUnicode()`](https://python-all.ru/3.4/c-api/unicode.html#c.PyUnicode_AsUnicode), but also saves the [`Py_UNICODE()`](https://python-all.ru/3.4/c-api/unicode.html#c.Py_UNICODE) array length (excluding the extra null terminator) in *size*. Note that the resulting [`Py_UNICODE*`](https://python-all.ru/3.4/c-api/unicode.html#c.Py_UNICODE) string may contain embedded null code points, which would cause the string to be truncated when used in most C functions.434435Новое в версии 3.3.436437#### `Py_UNICODE* PyUnicode_AsUnicodeCopy(PyObject *unicode)`438439Create a copy of a Unicode string ending with a null code point. Return *NULL* and raise a [`MemoryError`](https://python-all.ru/3.4/library/exceptions.html#MemoryError) exception on memory allocation failure, otherwise return a new allocated buffer (use [`PyMem_Free()`](https://python-all.ru/3.4/c-api/memory.html#c.PyMem_Free) to free the buffer). Note that the resulting [`Py_UNICODE*`](https://python-all.ru/3.4/c-api/unicode.html#c.Py_UNICODE) string may contain embedded null code points, which would cause the string to be truncated when used in most C functions.440441Новое в версии 3.2.442443Please migrate to using [`PyUnicode_AsUCS4Copy()`](https://python-all.ru/3.4/c-api/unicode.html#c.PyUnicode_AsUCS4Copy) or similar new APIs.444445#### `Py_ssize_t PyUnicode_GetSize(PyObject *unicode)`446447Return the size of the deprecated [`Py_UNICODE`](https://python-all.ru/3.4/c-api/unicode.html#c.Py_UNICODE) representation, in code units (this includes surrogate pairs as 2 units).448449Please migrate to using [`PyUnicode_GetLength()`](https://python-all.ru/3.4/c-api/unicode.html#c.PyUnicode_GetLength).450451#### `PyObject* PyUnicode_FromObject(PyObject *obj)`452453*Возвращаемое значение: новая ссылка.*454455Shortcut for `PyUnicode_FromEncodedObject(obj, NULL, "strict")` which is used throughout the interpreter whenever coercion to Unicode is needed.456457### Кодировка локали458459Текущую кодировку локали можно использовать для декодирования текста из операционной системы.460461#### `PyObject* PyUnicode_DecodeLocaleAndSize(const char *str, Py_ssize_t len, const char *errors)`462463Decode a string from the current locale encoding. The supported error handlers are `"strict"` and `"surrogateescape"` ([**PEP 383**](https://python-all.ru/3.4/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.464465> **См. также**466>467> Use [`PyUnicode_DecodeFSDefaultAndSize()`](https://python-all.ru/3.4/c-api/unicode.html#c.PyUnicode_DecodeFSDefaultAndSize) to decode a string from `Py_FileSystemDefaultEncoding` (the locale encoding read at Python startup).468469Новое в версии 3.3.470471#### `PyObject* PyUnicode_DecodeLocale(const char *str, const char *errors)`472473Аналог [`PyUnicode_DecodeLocaleAndSize()`](https://python-all.ru/3.4/c-api/unicode.html#c.PyUnicode_DecodeLocaleAndSize), но длина строки вычисляется с помощью `strlen()`.474475Новое в версии 3.3.476477#### `PyObject* PyUnicode_EncodeLocale(PyObject *unicode, const char *errors)`478479Кодирует объект Unicode в текущую кодировку локали. Поддерживаемые обработчики ошибок: `"strict"` и `"surrogateescape"` ([**PEP 383**](https://python-all.ru/3.4/c-api/unicode.html)). Если *errors* равен `NULL`, кодировщик использует обработчик ошибок `"strict"`. Возвращает объект [`bytes`](https://python-all.ru/3.4/library/functions.html#bytes). *str* не может содержать встроенные нулевые символы.480481> **См. также**482>483> Используйте [`PyUnicode_EncodeFSDefault()`](https://python-all.ru/3.4/c-api/unicode.html#c.PyUnicode_EncodeFSDefault) для кодирования строки в `Py_FileSystemDefaultEncoding` (кодировка локали, считанная при запуске Python).484485Новое в версии 3.3.486487### Кодировка файловой системы488489Для кодирования и декодирования имён файлов и других строк окружения в качестве кодировки следует использовать `Py_FileSystemEncoding`, а в качестве обработчика ошибок – `"surrogateescape"` ([**PEP 383**](https://python-all.ru/3.4/c-api/unicode.html)). Для кодирования имён файлов при разборе аргументов следует использовать преобразователь `"O&"`, передавая [`PyUnicode_FSConverter()`](https://python-all.ru/3.4/c-api/unicode.html#c.PyUnicode_FSConverter) в качестве функции преобразования:490491#### `int PyUnicode_FSConverter(PyObject* obj, void* result)`492493Преобразователь ParseTuple: кодирует объекты [`str`](https://python-all.ru/3.4/library/stdtypes.html#str) в [`bytes`](https://python-all.ru/3.4/library/functions.html#bytes) с помощью [`PyUnicode_EncodeFSDefault()`](https://python-all.ru/3.4/c-api/unicode.html#c.PyUnicode_EncodeFSDefault); объекты [`bytes`](https://python-all.ru/3.4/library/functions.html#bytes) передаются как есть. *result* должен быть [`PyBytesObject*`](https://python-all.ru/3.4/c-api/bytes.html#c.PyBytesObject), который нужно освободить, когда он больше не нужен.494495Новое в версии 3.1.496497Для декодирования имён файлов при разборе аргументов следует использовать преобразователь `"O&"`, передавая [`PyUnicode_FSDecoder()`](https://python-all.ru/3.4/c-api/unicode.html#c.PyUnicode_FSDecoder) в качестве функции преобразования:498499#### `int PyUnicode_FSDecoder(PyObject* obj, void* result)`500501Преобразователь ParseTuple: декодирует объекты [`bytes`](https://python-all.ru/3.4/library/functions.html#bytes) в [`str`](https://python-all.ru/3.4/library/stdtypes.html#str) с помощью [`PyUnicode_DecodeFSDefaultAndSize()`](https://python-all.ru/3.4/c-api/unicode.html#c.PyUnicode_DecodeFSDefaultAndSize); объекты [`str`](https://python-all.ru/3.4/library/stdtypes.html#str) передаются как есть. *result* должен быть [`PyUnicodeObject*`](https://python-all.ru/3.4/c-api/unicode.html#c.PyUnicodeObject), который нужно освободить, когда он больше не нужен.502503Новое в версии 3.2.504505#### `PyObject* PyUnicode_DecodeFSDefaultAndSize(const char *s, Py_ssize_t size)`506507Декодирует строку, используя `Py_FileSystemDefaultEncoding` и обработчик ошибок `"surrogateescape"`, или `"strict"` в Windows.508509Если `Py_FileSystemDefaultEncoding` не установлена, используется кодировка локали.510511> **См. также**512>513> `Py_FileSystemDefaultEncoding` инициализируется при запуске из кодировки локали и не может быть изменена впоследствии. Если нужно декодировать строку из текущей кодировки локали, используйте [`PyUnicode_DecodeLocaleAndSize()`](https://python-all.ru/3.4/c-api/unicode.html#c.PyUnicode_DecodeLocaleAndSize).514515Изменено в версии 3.2: Используйте обработчик ошибок `"strict"` в Windows.516517#### `PyObject* PyUnicode_DecodeFSDefault(const char *s)`518519Декодирует строку, завершающуюся нулевым символом, используя `Py_FileSystemDefaultEncoding` и обработчик ошибок `"surrogateescape"`, или `"strict"` в Windows.520521Если `Py_FileSystemDefaultEncoding` не установлена, используется кодировка локали.522523Используйте [`PyUnicode_DecodeFSDefaultAndSize()`](https://python-all.ru/3.4/c-api/unicode.html#c.PyUnicode_DecodeFSDefaultAndSize), если известна длина строки.524525Изменено в версии 3.2: Используйте обработчик ошибок `"strict"` в Windows.526527#### `PyObject* PyUnicode_EncodeFSDefault(PyObject *unicode)`528529Кодирует объект Unicode в `Py_FileSystemDefaultEncoding` с обработчиком ошибок `"surrogateescape"` или `"strict"` в Windows и возвращает [`bytes`](https://python-all.ru/3.4/library/functions.html#bytes). Обратите внимание, что результирующий объект [`bytes`](https://python-all.ru/3.4/library/functions.html#bytes) может содержать нулевые байты.530531Если `Py_FileSystemDefaultEncoding` не установлена, используется кодировка локали.532533> **См. также**534>535> `Py_FileSystemDefaultEncoding` инициализируется при запуске из кодировки локали и не может быть изменена впоследствии. Если нужно закодировать строку в текущую кодировку локали, используйте [`PyUnicode_EncodeLocale()`](https://python-all.ru/3.4/c-api/unicode.html#c.PyUnicode_EncodeLocale).536537Новое в версии 3.2.538539### Поддержка wchar\_t540541Поддержка `wchar_t` на платформах, которые её поддерживают:542543#### `PyObject* PyUnicode_FromWideChar(const wchar_t *w, Py_ssize_t size)`544545*Возвращаемое значение: новая ссылка.*546547Создаёт объект Unicode из буфера `wchar_t` *w* заданного размера *size*. Передача -1 в качестве *size* означает, что функция должна сама вычислить длину, используя wcslen. В случае ошибки возвращает *NULL*.548549#### `Py_ssize_t PyUnicode_AsWideChar(PyUnicodeObject *unicode, wchar_t *w, Py_ssize_t size)`550551Копирует содержимое объекта Unicode в буфер `wchar_t` *w*. Копируется не более *size* символов `wchar_t` (исключая возможный завершающий нулевой символ). Возвращает количество скопированных символов `wchar_t` или -1 в случае ошибки. Обратите внимание, что результирующая строка `wchar_t*` может как иметь, так и не иметь завершающего нуля. Ответственность вызывающего – убедиться, что строка `wchar_t*` завершается нулевым символом, если это требуется приложением. Также обратите внимание, что строка `wchar_t*` может содержать нулевые символы, что приведёт к её усечению при использовании с большинством функций C.552553#### `wchar_t* PyUnicode_AsWideCharString(PyObject *unicode, Py_ssize_t *size)`554555Преобразует объект Unicode в строку широких символов. Выходная строка всегда завершается нулевым символом. Если *size* не равно *NULL*, записывает количество широких символов (исключая завершающий нулевой символ) в *\*size*.556557В случае успеха возвращает буфер, выделенный с помощью `PyMem_Alloc()` (освобождать через [`PyMem_Free()`](https://python-all.ru/3.4/c-api/memory.html#c.PyMem_Free)). При ошибке возвращает *NULL*, *\*size* не определено и возбуждается [`MemoryError`](https://python-all.ru/3.4/library/exceptions.html#MemoryError). Обратите внимание, что результирующая строка `wchar_t` может содержать нулевые символы, что приведёт к её усечению при использовании с большинством функций C.558559Новое в версии 3.2.560561### Поддержка UCS4562563Новое в версии 3.3.564565#### `size_t Py_UCS4_strlen(const Py_UCS4 *u)`566567#### `Py_UCS4* Py_UCS4_strcpy(Py_UCS4 *s1, const Py_UCS4 *s2)`568569#### `Py_UCS4* Py_UCS4_strncpy(Py_UCS4 *s1, const Py_UCS4 *s2, size_t n)`570571#### `Py_UCS4* Py_UCS4_strcat(Py_UCS4 *s1, const Py_UCS4 *s2)`572573#### `int Py_UCS4_strcmp(const Py_UCS4 *s1, const Py_UCS4 *s2)`574575#### `int Py_UCS4_strncmp(const Py_UCS4 *s1, const Py_UCS4 *s2, size_t n)`576577#### `Py_UCS4* Py_UCS4_strchr(const Py_UCS4 *s, Py_UCS4 c)`578579#### `Py_UCS4* Py_UCS4_strrchr(const Py_UCS4 *s, Py_UCS4 c)`580581Эти служебные функции работают со строками символов [`Py_UCS4`](https://python-all.ru/3.4/c-api/unicode.html#c.Py_UCS4) и в остальном ведут себя как функции стандартной библиотеки C с теми же именами.582583## Встроенные кодеки584585Python предоставляет набор встроенных кодеков, написанных на C для скорости. Все эти кодеки могут использоваться напрямую через следующие функции.586587Многие из следующих API принимают два аргумента encoding и errors и имеют ту же семантику, что и одноимённые параметры конструктора встроенного строкового объекта [`str()`](https://python-all.ru/3.4/library/stdtypes.html#str).588589Установка encoding в *NULL* приводит к использованию кодировки по умолчанию, которой является ASCII. Для кодирования имён файлов вызовы файловой системы должны использовать [`PyUnicode_FSConverter()`](https://python-all.ru/3.4/c-api/unicode.html#c.PyUnicode_FSConverter). Внутри используется переменная `Py_FileSystemDefaultEncoding`. Эту переменную следует считать доступной только для чтения: в одних системах это будет указатель на статическую строку, в других – она изменяется во время выполнения (например, когда приложение вызывает setlocale).590591Обработка ошибок задаётся параметром errors, который также может быть установлен в *NULL*, что означает использование обработки по умолчанию, определённой для кодера. Обработка ошибок по умолчанию для всех встроенных кодеров – «strict» (возбуждается [`ValueError`](https://python-all.ru/3.4/library/exceptions.html#ValueError)).592593Все кодеки используют похожий интерфейс. Для простоты документированы только отклонения от следующего общего описания.594595### Общие кодеки596597Это общие API кодеков:598599#### `PyObject* PyUnicode_Decode(const char *s, Py_ssize_t size, const char *encoding, const char *errors)`600601*Возвращаемое значение: новая ссылка.*602603Создаёт объект Unicode путём декодирования *size* байт закодированной строки *s*. Параметры *encoding* и *errors* имеют тот же смысл, что и одноимённые параметры встроенной функции [`str()`](https://python-all.ru/3.4/library/stdtypes.html#str). Используемый кодек ищется через реестр кодеков Python. Возвращает *NULL*, если кодек возбудил исключение.604605#### `PyObject* PyUnicode_AsEncodedString(PyObject *unicode, const char *encoding, const char *errors)`606607*Возвращаемое значение: новая ссылка.*608609Кодирует объект Unicode и возвращает результат в виде объекта bytes Python. Параметры *encoding* и *errors* имеют тот же смысл, что и одноимённые параметры метода Unicode [`encode()`](https://python-all.ru/3.4/library/stdtypes.html#str.encode). Кодек ищется через реестр кодеков Python. Возвращает *NULL*, если кодек возбудил исключение.610611#### `PyObject* PyUnicode_Encode(const Py_UNICODE *s, Py_ssize_t size, const char *encoding, const char *errors)`612613*Возвращаемое значение: новая ссылка.*614615Кодирует буфер [`Py_UNICODE`](https://python-all.ru/3.4/c-api/unicode.html#c.Py_UNICODE) *s* заданного размера *size* и возвращает объект bytes Python. Параметры *encoding* и *errors* имеют тот же смысл, что и одноимённые параметры метода Unicode [`encode()`](https://python-all.ru/3.4/library/stdtypes.html#str.encode). Кодек ищется через реестр кодеков Python. Возвращает *NULL*, если кодек возбудил исключение.616617Устарело с версии 3.3, будет удалено в версии 4.0: Часть старого стиля API [`Py_UNICODE`](https://python-all.ru/3.4/c-api/unicode.html#c.Py_UNICODE); пожалуйста, переходите на использование [`PyUnicode_AsEncodedString()`](https://python-all.ru/3.4/c-api/unicode.html#c.PyUnicode_AsEncodedString).618619### Кодеки UTF-8620621Это API кодеков UTF-8:622623#### `PyObject* PyUnicode_DecodeUTF8(const char *s, Py_ssize_t size, const char *errors)`624625*Возвращаемое значение: новая ссылка.*626627Создаёт объект Unicode путём декодирования *size* байт строки, закодированной в UTF-8, *s*. Возвращает *NULL*, если кодек возбудил исключение.628629#### `PyObject* PyUnicode_DecodeUTF8Stateful(const char *s, Py_ssize_t size, const char *errors, Py_ssize_t *consumed)`630631*Возвращаемое значение: новая ссылка.*632633Если *consumed* равно *NULL*, ведёт себя как [`PyUnicode_DecodeUTF8()`](https://python-all.ru/3.4/c-api/unicode.html#c.PyUnicode_DecodeUTF8). Если *consumed* не равно *NULL*, завершающие неполные последовательности байт UTF-8 не будут считаться ошибкой. Эти байты не будут декодированы, а количество декодированных байт будет сохранено в *consumed*.634635#### `PyObject* PyUnicode_AsUTF8String(PyObject *unicode)`636637*Возвращаемое значение: новая ссылка.*638639Кодирует объект Unicode с использованием UTF-8 и возвращает результат в виде объекта bytes Python. Обработка ошибок – «strict». Возвращает *NULL*, если кодек возбудил исключение.640641#### `char* PyUnicode_AsUTF8AndSize(PyObject *unicode, Py_ssize_t *size)`642643Возвращает указатель на UTF-8 кодировку объекта Unicode и сохраняет размер закодированного представления (в байтах) в *size*. Аргумент *size* может быть *NULL*; в этом случае размер не сохраняется. Возвращаемый буфер всегда имеет добавленный дополнительный нулевой байт (не включённый в *size*), независимо от наличия других нулевых кодовых точек.644645В случае ошибки возвращается *NULL* с установленным исключением, и *size* не сохраняется.646647Это кэширует UTF-8 представление строки в объекте Unicode, и последующие вызовы будут возвращать указатель на тот же буфер. Вызывающая сторона не отвечает за освобождение буфера.648649Новое в версии 3.3.650651#### `char* PyUnicode_AsUTF8(PyObject *unicode)`652653Как [`PyUnicode_AsUTF8AndSize()`](https://python-all.ru/3.4/c-api/unicode.html#c.PyUnicode_AsUTF8AndSize), но не сохраняет размер.654655Новое в версии 3.3.656657#### `PyObject* PyUnicode_EncodeUTF8(const Py_UNICODE *s, Py_ssize_t size, const char *errors)`658659*Возвращаемое значение: новая ссылка.*660661Кодирует буфер [`Py_UNICODE`](https://python-all.ru/3.4/c-api/unicode.html#c.Py_UNICODE) *s* заданного размера *size* с использованием UTF-8 и возвращает объект bytes Python. Возвращает *NULL*, если кодек возбудил исключение.662663Устарело с версии 3.3, будет удалено в версии 4.0: Часть старого стиля API [`Py_UNICODE`](https://python-all.ru/3.4/c-api/unicode.html#c.Py_UNICODE); пожалуйста, переходите на использование [`PyUnicode_AsUTF8String()`](https://python-all.ru/3.4/c-api/unicode.html#c.PyUnicode_AsUTF8String) или [`PyUnicode_AsUTF8AndSize()`](https://python-all.ru/3.4/c-api/unicode.html#c.PyUnicode_AsUTF8AndSize).664665### Кодеки UTF-32666667Это API кодеков UTF-32:668669#### `PyObject* PyUnicode_DecodeUTF32(const char *s, Py_ssize_t size, const char *errors, int *byteorder)`670671Декодирует *size* байт из строки буфера в кодировке UTF-32 и возвращает соответствующий объект Unicode. *errors* (если не *NULL*) определяет обработку ошибок. По умолчанию используется «strict».672673Если *byteorder* не равен *NULL*, декодер начинает декодирование с использованием заданного порядка байтов:674675```c676*byteorder == -1: little endian677*byteorder == 0:  native order678*byteorder == 1:  big endian679```680681Если `*byteorder` равен нулю, и первые четыре байта входных данных являются маркером порядка байт (BOM), декодер переключается на этот порядок байт, и BOM не копируется в результирующую строку Unicode. Если `*byteorder` равен `-1` или `1`, любой маркер порядка байт копируется в выходные данные.682683После завершения *\*byteorder* устанавливается в текущий порядок байтов в конце входных данных.684685Если *byteorder* равен *NULL*, кодек запускается в режиме собственного порядка байтов.686687Возвращает *NULL*, если кодек сгенерировал исключение.688689#### `PyObject* PyUnicode_DecodeUTF32Stateful(const char *s, Py_ssize_t size, const char *errors, int *byteorder, Py_ssize_t *consumed)`690691Если *consumed* равен *NULL*, ведёт себя как [`PyUnicode_DecodeUTF32()`](https://python-all.ru/3.4/c-api/unicode.html#c.PyUnicode_DecodeUTF32). Если *consumed* не равен *NULL*, [`PyUnicode_DecodeUTF32Stateful()`](https://python-all.ru/3.4/c-api/unicode.html#c.PyUnicode_DecodeUTF32Stateful) не будет считать неполные конечные последовательности байтов UTF-32 (например, количество байтов, не кратное четырём) ошибкой. Эти байты не будут декодированы, а количество декодированных байтов будет сохранено в *consumed*.692693#### `PyObject* PyUnicode_AsUTF32String(PyObject *unicode)`694695Возвращает Python-строку байт в кодировке UTF-32 с собственным порядком байтов. Строка всегда начинается с маркера BOM. Обработка ошибок – «strict». Возвращает *NULL*, если кодек сгенерировал исключение.696697#### `PyObject* PyUnicode_EncodeUTF32(const Py_UNICODE *s, Py_ssize_t size, const char *errors, int byteorder)`698699Возвращает объект Python bytes, содержащий значение Unicode-данных из *s*, закодированное в UTF-32. Вывод записывается в соответствии со следующим порядком байтов:700701```c702byteorder == -1: little endian703byteorder == 0:  native byte order (writes a BOM mark)704byteorder == 1:  big endian705```706707Если `0`, выходная строка всегда начинается с метки BOM Unicode (U+FEFF). В двух других режимах метка BOM не добавляется.708709Если *Py\_UNICODE\_WIDE* не определён, суррогатные пары будут выводиться как одна кодовая точка.710711Возвращает *NULL*, если кодек сгенерировал исключение.712713Устарело с версии 3.3, будет удалено в версии 4.0: Часть старого API [`Py_UNICODE`](https://python-all.ru/3.4/c-api/unicode.html#c.Py_UNICODE); переходите на использование [`PyUnicode_AsUTF32String()`](https://python-all.ru/3.4/c-api/unicode.html#c.PyUnicode_AsUTF32String).714715### Кодеки UTF-32716717Это API кодеков UTF-32:718719#### `PyObject* PyUnicode_DecodeUTF16(const char *s, Py_ssize_t size, const char *errors, int *byteorder)`720721*Возвращаемое значение: новая ссылка.*722723Декодирует *size* байт из строки буфера в кодировке UTF-16 и возвращает соответствующий объект Unicode. *errors* (если не *NULL*) определяет обработку ошибок. По умолчанию используется «strict».724725Если *byteorder* не равен *NULL*, декодер начинает декодирование с использованием заданного порядка байтов:726727```c728*byteorder == -1: little endian729*byteorder == 0:  native order730*byteorder == 1:  big endian731```732733Если `*byteorder` равен нулю и первые два байта входных данных являются меткой порядка байтов (BOM), декодер переключается на этот порядок байтов, и BOM не копируется в результирующую строку Unicode. Если `*byteorder` равен `-1` или `1`, любая метка порядка байтов копируется в выходные данные (в результате чего появится символ `\ufeff` или `\ufffe`).734735После завершения *\*byteorder* устанавливается в текущий порядок байтов в конце входных данных.736737Если *byteorder* равен *NULL*, кодек запускается в режиме собственного порядка байтов.738739Возвращает *NULL*, если кодек сгенерировал исключение.740741#### `PyObject* PyUnicode_DecodeUTF16Stateful(const char *s, Py_ssize_t size, const char *errors, int *byteorder, Py_ssize_t *consumed)`742743*Возвращаемое значение: новая ссылка.*744745Если *consumed* равен *NULL*, ведёт себя как [`PyUnicode_DecodeUTF16()`](https://python-all.ru/3.4/c-api/unicode.html#c.PyUnicode_DecodeUTF16). Если *consumed* не равен *NULL*, [`PyUnicode_DecodeUTF16Stateful()`](https://python-all.ru/3.4/c-api/unicode.html#c.PyUnicode_DecodeUTF16Stateful) не будет считать неполные конечные последовательности байтов UTF-16 (например, нечётное количество байтов или разбитая суррогатная пара) ошибкой. Эти байты не будут декодированы, а количество декодированных байтов будет сохранено в *consumed*.746747#### `PyObject* PyUnicode_AsUTF16String(PyObject *unicode)`748749*Возвращаемое значение: новая ссылка.*750751Возвращает Python-строку байт в кодировке UTF-16 с собственным порядком байтов. Строка всегда начинается с маркера BOM. Обработка ошибок – «strict». Возвращает *NULL*, если кодек сгенерировал исключение.752753#### `PyObject* PyUnicode_EncodeUTF16(const Py_UNICODE *s, Py_ssize_t size, const char *errors, int byteorder)`754755*Возвращаемое значение: новая ссылка.*756757Возвращает объект Python bytes, содержащий значение Unicode-данных из *s*, закодированное в UTF-16. Вывод записывается в соответствии со следующим порядком байтов:758759```c760byteorder == -1: little endian761byteorder == 0:  native byte order (writes a BOM mark)762byteorder == 1:  big endian763```764765Если `0`, выходная строка всегда начинается с метки BOM Unicode (U+FEFF). В двух других режимах метка BOM не добавляется.766767Если *Py\_UNICODE\_WIDE* определён, одно значение [`Py_UNICODE`](https://python-all.ru/3.4/c-api/unicode.html#c.Py_UNICODE) может быть представлено как суррогатная пара. Если он не определён, каждое значение [`Py_UNICODE`](https://python-all.ru/3.4/c-api/unicode.html#c.Py_UNICODE) интерпретируется как символ UCS-2.768769Возвращает *NULL*, если кодек сгенерировал исключение.770771Устарело с версии 3.3, будет удалено в версии 4.0: Часть старого API [`Py_UNICODE`](https://python-all.ru/3.4/c-api/unicode.html#c.Py_UNICODE); переходите на использование [`PyUnicode_AsUTF16String()`](https://python-all.ru/3.4/c-api/unicode.html#c.PyUnicode_AsUTF16String).772773### Кодеки UTF-7774775Это API кодеков UTF-7:776777#### `PyObject* PyUnicode_DecodeUTF7(const char *s, Py_ssize_t size, const char *errors)`778779Создаёт объект Unicode путём декодирования *size* байт строки в кодировке UTF-7 *s*. Возвращает *NULL*, если кодек сгенерировал исключение.780781#### `PyObject* PyUnicode_DecodeUTF7Stateful(const char *s, Py_ssize_t size, const char *errors, Py_ssize_t *consumed)`782783Если *consumed* равен *NULL*, ведёт себя как [`PyUnicode_DecodeUTF7()`](https://python-all.ru/3.4/c-api/unicode.html#c.PyUnicode_DecodeUTF7). Если *consumed* не равен *NULL*, конечные неполные секции base-64 UTF-7 не будут считаться ошибкой. Эти байты не будут декодированы, а количество декодированных байтов будет сохранено в *consumed*.784785#### `PyObject* PyUnicode_EncodeUTF7(const Py_UNICODE *s, Py_ssize_t size, int base64SetO, int base64WhiteSpace, const char *errors)`786787Кодирует буфер [`Py_UNICODE`](https://python-all.ru/3.4/c-api/unicode.html#c.Py_UNICODE) заданного размера с использованием UTF-7 и возвращает объект Python bytes. Возвращает *NULL*, если кодек вызвал исключение.788789Если *base64SetO* не равно нулю, «Set O» (знаки препинания, не имеющие иного особого значения) будут закодированы в base-64. Если *base64WhiteSpace* не равно нулю, пробельные символы будут закодированы в base-64. Оба параметра установлены в ноль для кодека Python «utf-7».790791Устарело с версии 3.3, будет удалено в версии 4.0: Часть старого API [`Py_UNICODE`](https://python-all.ru/3.4/c-api/unicode.html#c.Py_UNICODE).792793### Кодеки Unicode-Escape794795Это API кодеков «Unicode Escape»:796797#### `PyObject* PyUnicode_DecodeUnicodeEscape(const char *s, Py_ssize_t size, const char *errors)`798799*Возвращаемое значение: новая ссылка.*800801Создаёт объект Unicode путём декодирования *size* байт строки в кодировке Unicode-Escape *s*. Возвращает *NULL*, если кодек сгенерировал исключение.802803#### `PyObject* PyUnicode_AsUnicodeEscapeString(PyObject *unicode)`804805*Возвращаемое значение: новая ссылка.*806807Кодирует объект Unicode с использованием Unicode-Escape и возвращает результат в виде строкового объекта Python. Обработка ошибок – «strict». Возвращает *NULL*, если кодек вызвал исключение.808809#### `PyObject* PyUnicode_EncodeUnicodeEscape(const Py_UNICODE *s, Py_ssize_t size)`810811*Возвращаемое значение: новая ссылка.*812813Кодирует буфер [`Py_UNICODE`](https://python-all.ru/3.4/c-api/unicode.html#c.Py_UNICODE) заданного размера *size* с использованием Unicode-Escape и возвращает строковый объект Python. Возвращает *NULL*, если кодек вызвал исключение.814815Устарело с версии 3.3, будет удалено в версии 4.0: Часть старого API [`Py_UNICODE`](https://python-all.ru/3.4/c-api/unicode.html#c.Py_UNICODE); переходите на использование [`PyUnicode_AsUnicodeEscapeString()`](https://python-all.ru/3.4/c-api/unicode.html#c.PyUnicode_AsUnicodeEscapeString).816817### Кодеки Raw-Unicode-Escape818819Это API кодеков «Raw Unicode Escape»:820821#### `PyObject* PyUnicode_DecodeRawUnicodeEscape(const char *s, Py_ssize_t size, const char *errors)`822823*Возвращаемое значение: новая ссылка.*824825Создаёт объект Unicode путём декодирования *size* байт строки *s*, закодированной в Raw-Unicode-Escape. Возвращает *NULL*, если кодек вызвал исключение.826827#### `PyObject* PyUnicode_AsRawUnicodeEscapeString(PyObject *unicode)`828829*Возвращаемое значение: новая ссылка.*830831Кодирует объект Unicode с использованием Raw-Unicode-Escape и возвращает результат в виде строкового объекта Python. Обработка ошибок – «strict». Возвращает *NULL*, если кодек вызвал исключение.832833#### `PyObject* PyUnicode_EncodeRawUnicodeEscape(const Py_UNICODE *s, Py_ssize_t size, const char *errors)`834835*Возвращаемое значение: новая ссылка.*836837Кодирует буфер [`Py_UNICODE`](https://python-all.ru/3.4/c-api/unicode.html#c.Py_UNICODE) заданного размера *size* с использованием Raw-Unicode-Escape и возвращает строковый объект Python. Возвращает *NULL*, если кодек вызвал исключение.838839Устарело с версии 3.3, будет удалено в версии 4.0: Часть старого API [`Py_UNICODE`](https://python-all.ru/3.4/c-api/unicode.html#c.Py_UNICODE); переходите на использование [`PyUnicode_AsRawUnicodeEscapeString()`](https://python-all.ru/3.4/c-api/unicode.html#c.PyUnicode_AsRawUnicodeEscapeString).840841### Кодеки Latin-1842843Это API кодеков Latin-1: Latin-1 соответствует первым 256 кодовым позициям Unicode, и только они принимаются кодеками при кодировании.844845#### `PyObject* PyUnicode_DecodeLatin1(const char *s, Py_ssize_t size, const char *errors)`846847*Возвращаемое значение: новая ссылка.*848849Создаёт объект Unicode путём декодирования *size* байт строки *s*, закодированной в Latin-1. Возвращает *NULL*, если кодек вызвал исключение.850851#### `PyObject* PyUnicode_AsLatin1String(PyObject *unicode)`852853*Возвращаемое значение: новая ссылка.*854855Кодирует объект Unicode с помощью Latin-1 и возвращает результат как объект bytes Python. Обработка ошибок – “strict”. Возвращает *NULL*, если кодек вызвал исключение.856857#### `PyObject* PyUnicode_EncodeLatin1(const Py_UNICODE *s, Py_ssize_t size, const char *errors)`858859*Возвращаемое значение: новая ссылка.*860861Кодирует буфер [`Py_UNICODE`](https://python-all.ru/3.4/c-api/unicode.html#c.Py_UNICODE) заданного размера *size* с помощью Latin-1 и возвращает объект bytes Python. Возвращает *NULL*, если кодек вызвал исключение.862863Устарело с версии 3.3, будет удалено в версии 4.0: Часть старого API на [`Py_UNICODE`](https://python-all.ru/3.4/c-api/unicode.html#c.Py_UNICODE); перейдите на использование [`PyUnicode_AsLatin1String()`](https://python-all.ru/3.4/c-api/unicode.html#c.PyUnicode_AsLatin1String).864865### Кодеки ASCII866867Это API кодеков ASCII. Принимаются только 7-битные данные ASCII. Все остальные коды вызывают ошибки.868869#### `PyObject* PyUnicode_DecodeASCII(const char *s, Py_ssize_t size, const char *errors)`870871*Возвращаемое значение: новая ссылка.*872873Создаёт объект Unicode путём декодирования *size* байт строки *s*, закодированной в ASCII. Возвращает *NULL*, если кодек вызвал исключение.874875#### `PyObject* PyUnicode_AsASCIIString(PyObject *unicode)`876877*Возвращаемое значение: новая ссылка.*878879Кодирует объект Unicode с помощью ASCII и возвращает результат как объект bytes Python. Обработка ошибок – “strict”. Возвращает *NULL*, если кодек вызвал исключение.880881#### `PyObject* PyUnicode_EncodeASCII(const Py_UNICODE *s, Py_ssize_t size, const char *errors)`882883*Возвращаемое значение: новая ссылка.*884885Кодирует буфер [`Py_UNICODE`](https://python-all.ru/3.4/c-api/unicode.html#c.Py_UNICODE) заданного размера *size* с помощью ASCII и возвращает объект bytes Python. Возвращает *NULL*, если кодек вызвал исключение.886887Устарело с версии 3.3, будет удалено в версии 4.0: Часть старого API на [`Py_UNICODE`](https://python-all.ru/3.4/c-api/unicode.html#c.Py_UNICODE); перейдите на использование [`PyUnicode_AsASCIIString()`](https://python-all.ru/3.4/c-api/unicode.html#c.PyUnicode_AsASCIIString).888889### Кодеки с таблицей символов890891Этот кодек особенный, так как его можно использовать для реализации множества разных кодеков (именно так и были получены большинство стандартных кодеков, входящих в пакет `encodings`). Кодек использует отображение для кодирования и декодирования символов.892893Отображения для декодирования должны сопоставлять отдельные строковые символы отдельным символам Unicode, целым числам (которые затем интерпретируются как кодовые точки Unicode) или None (что означает «неопределённое отображение» и вызывает ошибку).894895Отображения для кодирования должны сопоставлять отдельные символы Unicode отдельным строковым символам, целым числам (которые затем интерпретируются как кодовые точки Latin-1) или None (что означает «неопределённое отображение» и вызывает ошибку).896897Объекты отображения должны поддерживать только интерфейс отображения \_\_getitem\_\_.898899Если при поиске символа возникает LookupError, символ копируется как есть; это означает, что его порядковое значение будет интерпретироваться как кодовая точка Unicode или Latin-1 соответственно. Из-за этого отображения должны содержать только те соответствия, которые переводят символы в другие кодовые точки.900901Это API кодеков отображения:902903#### `PyObject* PyUnicode_DecodeCharmap(const char *s, Py_ssize_t size, PyObject *mapping, const char *errors)`904905*Возвращаемое значение: новая ссылка.*906907Создаёт объект Unicode, декодируя *size* байт закодированной строки *s* с помощью заданного объекта *mapping*. Возвращает *NULL*, если кодек вызвал исключение. Если *mapping* равен *NULL*, выполняется декодирование Latin-1. В противном случае это может быть словарь, отображающий байты, или строка Unicode, которая интерпретируется как таблица поиска. Значения байтов, превышающие длину строки, и «символ» U+FFFE считаются «неопределённым отображением».908909#### `PyObject* PyUnicode_AsCharmapString(PyObject *unicode, PyObject *mapping)`910911*Возвращаемое значение: новая ссылка.*912913Кодирует объект Unicode с помощью заданного объекта *mapping* и возвращает результат в виде строкового объекта Python. Обработка ошибок – «strict». Возвращает *NULL*, если кодек вызвал исключение.914915Следующее API кодека особенное тем, что отображает Unicode в Unicode.916917#### `PyObject* PyUnicode_TranslateCharmap(const Py_UNICODE *s, Py_ssize_t size, PyObject *table, const char *errors)`918919*Возвращаемое значение: новая ссылка.*920921Переводит буфер [`Py_UNICODE`](https://python-all.ru/3.4/c-api/unicode.html#c.Py_UNICODE) заданного размера *size*, применяя к нему символьное отображение *table*, и возвращает результирующий объект Unicode. Возвращает *NULL*, если кодек вызвал исключение.922923Таблица *mapping* должна сопоставлять целочисленные кодовые точки Unicode целочисленным кодовым точкам Unicode или None (что приводит к удалению символа).924925Таблицы отображения должны предоставлять только интерфейс [`__getitem__()`](https://python-all.ru/3.4/reference/datamodel.html#object.__getitem__); словари и последовательности работают хорошо. Кодовые точки неотображённых символов (те, которые вызывают [`LookupError`](https://python-all.ru/3.4/library/exceptions.html#LookupError)) остаются нетронутыми и копируются как есть.926927Устарело с версии 3.3, будет удалено в версии 4.0: Часть старого API на [`Py_UNICODE`](https://python-all.ru/3.4/c-api/unicode.html#c.Py_UNICODE).928929#### `PyObject* PyUnicode_EncodeCharmap(const Py_UNICODE *s, Py_ssize_t size, PyObject *mapping, const char *errors)`930931*Возвращаемое значение: новая ссылка.*932933Кодирует буфер [`Py_UNICODE`](https://python-all.ru/3.4/c-api/unicode.html#c.Py_UNICODE) заданного размера *size* с помощью заданного объекта *mapping* и возвращает строковый объект Python. Возвращает *NULL*, если кодек вызвал исключение.934935Устарело с версии 3.3, будет удалено в версии 4.0: Часть старого API на [`Py_UNICODE`](https://python-all.ru/3.4/c-api/unicode.html#c.Py_UNICODE); перейдите на использование [`PyUnicode_AsCharmapString()`](https://python-all.ru/3.4/c-api/unicode.html#c.PyUnicode_AsCharmapString).936937### Кодеки MBCS для Windows938939Это API кодеков MBCS. В настоящее время они доступны только в Windows и используют преобразователи Win32 MBCS для выполнения преобразований. Обратите внимание, что MBCS (или DBCS) – это класс кодировок, а не одна конкретная. Целевая кодировка определяется пользовательскими настройками на машине, где выполняется кодек.940941#### `PyObject* PyUnicode_DecodeMBCS(const char *s, Py_ssize_t size, const char *errors)`942943*Возвращаемое значение: новая ссылка.*944945Создаёт объект Unicode, декодируя *size* байтов строки, закодированной в MBCS, из *s*. Возвращает *NULL*, если кодек вызвал исключение.946947#### `PyObject* PyUnicode_DecodeMBCSStateful(const char *s, int size, const char *errors, int *consumed)`948949Если *consumed* равен *NULL*, ведёт себя как [`PyUnicode_DecodeMBCS()`](https://python-all.ru/3.4/c-api/unicode.html#c.PyUnicode_DecodeMBCS). Если *consumed* не равен *NULL*, то [`PyUnicode_DecodeMBCSStateful()`](https://python-all.ru/3.4/c-api/unicode.html#c.PyUnicode_DecodeMBCSStateful) не будет декодировать конечный ведущий байт, а количество декодированных байтов будет сохранено в *consumed*.950951#### `PyObject* PyUnicode_AsMBCSString(PyObject *unicode)`952953*Возвращаемое значение: новая ссылка.*954955Кодирует объект Unicode с помощью MBCS и возвращает результат в виде объекта bytes Python. Обработка ошибок – "strict". Возвращает *NULL*, если кодек вызвал исключение.956957#### `PyObject* PyUnicode_EncodeCodePage(int code_page, PyObject *unicode, const char *errors)`958959Кодирует объект Unicode, используя указанную кодовую страницу, и возвращает объект bytes Python. Возвращает *NULL*, если кодек вызвал исключение. Используйте кодовую страницу `CP_ACP` для получения кодировщика MBCS.960961Новое в версии 3.3.962963#### `PyObject* PyUnicode_EncodeMBCS(const Py_UNICODE *s, Py_ssize_t size, const char *errors)`964965*Возвращаемое значение: новая ссылка.*966967Кодирует буфер [`Py_UNICODE`](https://python-all.ru/3.4/c-api/unicode.html#c.Py_UNICODE) заданного размера *size* с помощью MBCS и возвращает объект bytes Python. Возвращает *NULL*, если кодек возбудил исключение.968969Устарело с версии 3.3, будет удалено в версии 4.0: Часть старого API [`Py_UNICODE`](https://python-all.ru/3.4/c-api/unicode.html#c.Py_UNICODE); рекомендуется перейти на [`PyUnicode_AsMBCSString()`](https://python-all.ru/3.4/c-api/unicode.html#c.PyUnicode_AsMBCSString) или [`PyUnicode_EncodeCodePage()`](https://python-all.ru/3.4/c-api/unicode.html#c.PyUnicode_EncodeCodePage).970971### Методы и слоты972973## Методы и слот-функции974975Следующие API могут обрабатывать объекты Unicode и строки на входе (в описаниях мы называем их строками) и возвращают объекты Unicode или целые числа по необходимости.976977Все они возвращают *NULL* или `-1` в случае исключения.978979#### `PyObject* PyUnicode_Concat(PyObject *left, PyObject *right)`980981*Возвращаемое значение: новая ссылка.*982983Объединяет две строки, возвращая новую строку Unicode.984985#### `PyObject* PyUnicode_Split(PyObject *s, PyObject *sep, Py_ssize_t maxsplit)`986987*Возвращаемое значение: новая ссылка.*988989Разделяет строку и возвращает список строк Unicode. Если *sep* равен *NULL*, разделение происходит по всем подстрокам из пробельных символов. В противном случае разделение выполняется по указанному разделителю. Выполняется не более *maxsplit* разделений. Если значение отрицательное, ограничение не устанавливается. Разделители не включаются в результирующий список.990991#### `PyObject* PyUnicode_Splitlines(PyObject *s, int keepend)`992993*Возвращаемое значение: новая ссылка.*994995Разделяет строку Unicode по символам перевода строки и возвращает список строк Unicode. CRLF считается одним переносом строки. Если *keepend* равен 0, символы перевода строки не включаются в результирующие строки.996997#### `PyObject* PyUnicode_Translate(PyObject *str, PyObject *table, const char *errors)`998999*Возвращаемое значение: новая ссылка.*10001001Переводит строку, применяя к ней таблицу отображения символов, и возвращает результирующий объект Unicode.10021003Таблица отображения должна сопоставлять целочисленные коды Unicode другим целочисленным кодам Unicode или None (что приводит к удалению символа).10041005Таблицам отображения достаточно реализовать интерфейс [`__getitem__()`](https://python-all.ru/3.4/reference/datamodel.html#object.__getitem__); словари и последовательности подходят. Неотображённые коды символов (те, которые вызывают [`LookupError`](https://python-all.ru/3.4/library/exceptions.html#LookupError)) остаются без изменений и копируются как есть.10061007*errors* имеет обычное для кодеков значение. Может быть *NULL*, что означает использование обработки ошибок по умолчанию.10081009#### `PyObject* PyUnicode_Join(PyObject *separator, PyObject *seq)`10101011*Возвращаемое значение: новая ссылка.*10121013Объединяет последовательность строк, используя заданный *разделитель*, и возвращает полученную Unicode-строку.10141015#### `Py_ssize_t PyUnicode_Tailmatch(PyObject *str, PyObject *substr, Py_ssize_t start, Py_ssize_t end, int direction)`10161017Возвращает 1, если *substr* совпадает с `str[start:end]` на указанном конце (*direction* == -1 означает поиск по префиксу, *direction* == 1 – поиск по суффиксу), и 0 в противном случае. Возвращает `-1`, если произошла ошибка.10181019#### `Py_ssize_t PyUnicode_Find(PyObject *str, PyObject *substr, Py_ssize_t start, Py_ssize_t end, int direction)`10201021Возвращает первую позицию *substr* в `str[start:end]`, используя заданное *direction* (*direction* == 1 означает прямой поиск, *direction* == -1 – обратный). Возвращаемое значение – индекс первого совпадения; значение `-1` означает, что совпадений не найдено, а `-2` – что произошла ошибка и было установлено исключение.10221023#### `Py_ssize_t PyUnicode_FindChar(PyObject *str, Py_UCS4 ch, Py_ssize_t start, Py_ssize_t end, int direction)`10241025Возвращает первую позицию символа *ch* в `str[start:end]`, используя заданное *direction* (*direction* == 1 означает прямой поиск, *direction* == -1 – обратный). Возвращаемое значение – индекс первого совпадения; значение `-1` означает, что совпадений не найдено, а `-2` – что произошла ошибка и было установлено исключение.10261027Новое в версии 3.3.10281029#### `Py_ssize_t PyUnicode_Count(PyObject *str, PyObject *substr, Py_ssize_t start, Py_ssize_t end)`10301031Возвращает количество непересекающихся вхождений *substr* в `str[start:end]`. Возвращает `-1`, если произошла ошибка.10321033#### `PyObject* PyUnicode_Replace(PyObject *str, PyObject *substr, PyObject *replstr, Py_ssize_t maxcount)`10341035*Возвращаемое значение: новая ссылка.*10361037Заменяет не более *maxcount* вхождений *substr* в *str* на *replstr* и возвращает результирующий объект Unicode. *maxcount* == -1 означает замену всех вхождений.10381039#### `int PyUnicode_Compare(PyObject *left, PyObject *right)`10401041Сравнивает две строки и возвращает -1, 0, 1 для случаев «меньше», «равно» и «больше» соответственно.10421043#### `int PyUnicode_CompareWithASCIIString(PyObject *uni, const char *string)`10441045Сравнивает объект Unicode *uni* с *string* и возвращает -1, 0, 1 для случаев «меньше», «равно» и «больше» соответственно. Рекомендуется передавать только строки в кодировке ASCII, но если строка содержит не-ASCII символы, функция интерпретирует её как ISO-8859-1.10461047#### `PyObject* PyUnicode_RichCompare(PyObject *left, PyObject *right, int op)`10481049Выполняет расширенное сравнение двух строк unicode и возвращает одно из следующих значений:10501051- `NULL` в случае возбуждения исключения1052- `Py_True` или `Py_False` при успешном сравнении1053- `Py_NotImplemented` в случае, если комбинация типов неизвестна10541055Обратите внимание, что сравнения с `Py_EQ` и `Py_NE` могут вызвать [`UnicodeWarning`](https://python-all.ru/3.4/library/exceptions.html#UnicodeWarning), если преобразование аргументов в Unicode завершится ошибкой с [`UnicodeDecodeError`](https://python-all.ru/3.4/library/exceptions.html#UnicodeDecodeError).10561057Возможные значения для *op*: `Py_GT`, `Py_GE`, `Py_EQ`, `Py_NE`, `Py_LT` и `Py_LE`.10581059#### `PyObject* PyUnicode_Format(PyObject *format, PyObject *args)`10601061*Возвращаемое значение: новая ссылка.*10621063Возвращает новый строковый объект из *format* и *args*; это аналогично `format % args`.10641065#### `int PyUnicode_Contains(PyObject *container, PyObject *element)`10661067Проверяет, содержится ли *element* в *container*, и возвращает true или false соответственно.10681069*Элемент* должен приводиться к одноэлементной строке Unicode. `-1` возвращается при возникновении ошибки.10701071#### `void PyUnicode_InternInPlace(PyObject **string)`10721073Интернирует аргумент *\*string* на месте. Аргумент должен быть адресом переменной-указателя, указывающей на объект строки Unicode Python. Если уже существует интернированная строка, совпадающая с *\*string*, то она устанавливает *\*string* на эту строку (уменьшая счётчик ссылок старого строкового объекта и увеличивая счётчик интернированной строки); в противном случае она оставляет *\*string* без изменений и интернирует её (увеличивая её счётчик ссылок). (Уточнение: хотя много говорится о счётчиках ссылок, считайте эту функцию нейтральной к счётчикам ссылок – вы владеете объектом после вызова, только если владели им до вызова.)10741075#### `PyObject* PyUnicode_InternFromString(const char *v)`10761077Комбинация [`PyUnicode_FromString()`](https://python-all.ru/3.4/c-api/unicode.html#c.PyUnicode_FromString) и [`PyUnicode_InternInPlace()`](https://python-all.ru/3.4/c-api/unicode.html#c.PyUnicode_InternInPlace), возвращающая либо новый объект unicode-строки, который был интернирован, либо новую (“собственную”) ссылку на ранее интернированный строковый объект с тем же значением.1078