`unicode.md`

1072 строк · 100.4 КБ · обычная страница · сырой текст · скачать
1> **Источник:** https://python-all.ru/3.6/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.6/c-api/unicode.html) в Python 3.3, объекты Unicode внутри используют различные представления, чтобы обеспечить обработку полного диапазона символов Unicode, оставаясь при этом эффективными по памяти. Существуют особые случаи для строк, где все кодовые точки находятся ниже 128, 256 или 65536; в противном случае кодовые точки должны быть ниже 1114112 (то есть полного диапазона Unicode).1213Представления в [`Py_UNICODE*`](https://python-all.ru/3.6/c-api/unicode.html#c.Py_UNICODE) и UTF-8 создаются по запросу и кэшируются в объекте Unicode. Представление [`Py_UNICODE*`](https://python-all.ru/3.6/c-api/unicode.html#c.Py_UNICODE) устарело и неэффективно; его следует избегать в ситуациях, критичных к производительности или памяти.1415Из-за перехода от старых API к новым unicode-объекты внутренне могут находиться в двух состояниях в зависимости от того, как они были созданы:1617- «канонические» unicode-объекты – это все объекты, созданные с помощью не устаревшего unicode API. Они используют наиболее эффективное представление, допускаемое реализацией.18- «устаревшие» unicode-объекты были созданы через один из устаревших API (обычно [`PyUnicode_FromUnicode()`](https://python-all.ru/3.6/c-api/unicode.html#c.PyUnicode_FromUnicode)) и имеют только представление [`Py_UNICODE*`](https://python-all.ru/3.6/c-api/unicode.html#c.Py_UNICODE); перед вызовом любого другого API необходимо вызвать [`PyUnicode_READY()`](https://python-all.ru/3.6/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.6/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.6/c-api/structures.html#c.PyObject) представляют объект Unicode в Python. В почти всех случаях их не следует использовать напрямую, так как все функции API, работающие с объектами Unicode, принимают и возвращают указатели [`PyObject`](https://python-all.ru/3.6/c-api/structures.html#c.PyObject).4748Новое в версии 3.3.4950**[PyTypeObject](https://python-all.ru/3.6/c-api/type.html#c.PyTypeObject) `PyUnicode_Type`**5152Этот экземпляр [`PyTypeObject`](https://python-all.ru/3.6/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.6/c-api/unicode.html#c.PyUnicode_KIND) для выбора правильного макроса. Убедитесь, что [`PyUnicode_READY()`](https://python-all.ru/3.6/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.6/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.6/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.6/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.6/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.6/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.6/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.6/c-api/unicode.html#c.Py_UNICODE) в байтах. *o* должен быть объектом Unicode (не проверяется).149150Устарело с версии 3.3, будет удалено в версии 4.0: Часть старого API Unicode, переходите на использование [`PyUnicode_GET_LENGTH()`](https://python-all.ru/3.6/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.6/c-api/unicode.html#c.Py_UNICODE) объекта. Возвращаемый буфер всегда завершается дополнительной нулевой кодовой точкой. Он также может содержать встроенные нулевые кодовые точки, что приведет к усечению строки при использовании в большинстве функций C. Форма `AS_DATA` приводит указатель к `const char *`. Аргумент *o* должен быть объектом Unicode (не проверяется).157158Изменено в версии 3.3: Этот макрос теперь неэффективен, поскольку во многих случаях представление [`Py_UNICODE`](https://python-all.ru/3.6/c-api/unicode.html#c.Py_UNICODE) не существует и должно быть создано – и может завершиться ошибкой (возвращает *NULL* с установленным исключением). Попробуйте перенести код на использование новых макросов `PyUnicode_nBYTE_DATA()` или используйте [`PyUnicode_WRITE()`](https://python-all.ru/3.6/c-api/unicode.html#c.PyUnicode_WRITE) или [`PyUnicode_READ()`](https://python-all.ru/3.6/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* символом в регистре заголовка (titlecase).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.6/library/functions.html#repr) для строки. Это не влияет на обработку строк, записываемых в [`sys.stdout`](https://python-all.ru/3.6/library/sys.html#sys.stdout) или [`sys.stderr`](https://python-all.ru/3.6/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 с заданным *видом* (возможные значения: [`PyUnicode_1BYTE_KIND`](https://python-all.ru/3.6/c-api/unicode.html#c.PyUnicode_1BYTE_KIND) и т.д., возвращаемые [`PyUnicode_KIND()`](https://python-all.ru/3.6/c-api/unicode.html#c.PyUnicode_KIND)). *Буфер* должен указывать на массив из *size* единиц по 1, 2 или 4 байта на символ, в зависимости от вида.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.6/c-api/unicode.html#c.PyUnicode_FromUnicode) с буфером, установленным в *NULL*. Это использование устарело в пользу [`PyUnicode_New()`](https://python-all.ru/3.6/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.6/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.6/c-api/object.html#c.PyObject_Str). |315| `%R` | PyObject\* | Результат вызова [`PyObject_Repr()`](https://python-all.ru/3.6/c-api/object.html#c.PyObject_Repr). |316317Нераспознанный символ формата приводит к тому, что вся оставшаяся строка формата копируется как есть в результирующую строку, а все лишние аргументы отбрасываются.318319> **Примечание**320>321> Единица ширины форматирования – это количество символов, а не байтов. Единица точности форматирования – количество байтов для `"%s"` и `"%V"` (если аргумент `PyObject*` равен NULL) и количество символов для `"%A"`, `"%U"`, `"%S"`, `"%R"` и `"%V"` (если аргумент `PyObject*` не равен NULL).322323Изменено в версии 3.2: Добавлена поддержка `"%lld"` и `"%llu"`.324325Изменено в версии 3.3: Добавлена поддержка `"%li"`, `"%lli"` и `"%zi"`.326327Изменено в версии 3.4: Добавлена поддержка форматтеров ширины и точности для `"%s"`, `"%A"`, `"%U"`, `"%V"`, `"%S"`, `"%R"`.328329#### `PyObject* PyUnicode_FromFormatV(const char *format, va_list vargs)`330331Идентично [`PyUnicode_FromFormat()`](https://python-all.ru/3.6/c-api/unicode.html#c.PyUnicode_FromFormat), за исключением того, что принимает ровно два аргумента.332333#### `PyObject* PyUnicode_FromEncodedObject(PyObject *obj, const char *encoding, const char *errors)`334335*Возвращаемое значение: новая ссылка.*336337Декодирует закодированный объект *obj* в объект Unicode.338339[`bytes`](https://python-all.ru/3.6/library/stdtypes.html#bytes), [`bytearray`](https://python-all.ru/3.6/library/stdtypes.html#bytearray) и другие [байтоподобные объекты](https://python-all.ru/3.6/glossary.html#term-bytes-like-object) декодируются в соответствии с заданной *кодировкой* и с использованием обработки ошибок, определяемой *errors*. Оба могут быть *NULL*, чтобы интерфейс использовал значения по умолчанию (подробнее см. [Встроенные кодеки](https://python-all.ru/3.6/c-api/unicode.html#builtincodecs)).340341Все остальные объекты, включая объекты Unicode, приводят к установке [`TypeError`](https://python-all.ru/3.6/library/exceptions.html#TypeError).342343API возвращает *NULL* при ошибке. Вызывающий отвечает за уменьшение счётчика ссылок возвращённых объектов.344345#### `Py_ssize_t PyUnicode_GetLength(PyObject *unicode)`346347Возвращает длину объекта Unicode в кодовых точках.348349Новое в версии 3.3.350351#### `Py_ssize_t PyUnicode_CopyCharacters(PyObject *to, Py_ssize_t to_start, PyObject *from, Py_ssize_t from_start, Py_ssize_t how_many)`352353Копирует символы из одного объекта Unicode в другой. При необходимости выполняет преобразование символов и, если возможно, использует `memcpy()`. Возвращает `-1` и устанавливает исключение при ошибке, в противном случае возвращает количество скопированных символов.354355Новое в версии 3.3.356357#### `Py_ssize_t PyUnicode_Fill(PyObject *unicode, Py_ssize_t start, Py_ssize_t length, Py_UCS4 fill_char)`358359Заполняет строку символом: записывает *fill\_char* в `unicode[start:start+length]`.360361Завершается ошибкой, если *fill\_char* больше максимального символа строки или если у строки больше одной ссылки.362363Возвращает количество записанных символов или `-1` и возбуждает исключение при ошибке.364365Новое в версии 3.3.366367#### `int PyUnicode_WriteChar(PyObject *unicode, Py_ssize_t index, Py_UCS4 character)`368369Записывает символ в строку. Строка должна быть создана с помощью [`PyUnicode_New()`](https://python-all.ru/3.6/c-api/unicode.html#c.PyUnicode_New). Поскольку строки Unicode считаются неизменяемыми, строка не должна быть общей или уже хэшированной.370371Эта функция проверяет, что *unicode* является объектом Unicode, индекс не выходит за границы, и объект можно безопасно изменять (т.е. его счётчик ссылок равен единице).372373Новое в версии 3.3.374375#### `Py_UCS4 PyUnicode_ReadChar(PyObject *unicode, Py_ssize_t index)`376377Читает символ из строки. Эта функция проверяет, что *unicode* является объектом Unicode и индекс не выходит за границы, в отличие от макроса [`PyUnicode_READ_CHAR()`](https://python-all.ru/3.6/c-api/unicode.html#c.PyUnicode_READ_CHAR).378379Новое в версии 3.3.380381#### `PyObject* PyUnicode_Substring(PyObject *str, Py_ssize_t start, Py_ssize_t end)`382383Возвращает подстроку *str* от индекса символа *start* (включительно) до индекса символа *end* (исключительно). Отрицательные индексы не поддерживаются.384385Новое в версии 3.3.386387#### `Py_UCS4* PyUnicode_AsUCS4(PyObject *u, Py_UCS4 *buffer, Py_ssize_t buflen, int copy_null)`388389Копирует строку *u* в буфер UCS4, включая нулевой символ, если *copy\_null* установлен. Возвращает *NULL* и устанавливает исключение при ошибке (в частности, [`SystemError`](https://python-all.ru/3.6/library/exceptions.html#SystemError), если *buflen* меньше длины *u*). При успехе возвращается *buffer*.390391Новое в версии 3.3.392393#### `Py_UCS4* PyUnicode_AsUCS4Copy(PyObject *u)`394395Копирует строку *u* в новый буфер UCS4, выделенный с помощью [`PyMem_Malloc()`](https://python-all.ru/3.6/c-api/memory.html#c.PyMem_Malloc). В случае неудачи возвращается *NULL* с установленным [`MemoryError`](https://python-all.ru/3.6/library/exceptions.html#MemoryError). Возвращаемый буфер всегда содержит дополнительный нулевой кодовый знак в конце.396397Новое в версии 3.3.398399### Устаревшие API Py\_UNICODE400401Устарело с версии 3.3, будет удалено в версии 4.0.402403Эти функции API устарели с реализацией [**PEP 393**](https://python-all.ru/3.6/c-api/unicode.html). Модули-расширения могут продолжать их использовать, поскольку они не будут удалены в Python 3.x, но следует учитывать, что их использование теперь может приводить к снижению производительности и увеличению потребления памяти.404405#### `PyObject* PyUnicode_FromUnicode(const Py_UNICODE *u, Py_ssize_t size)`406407*Возвращаемое значение: новая ссылка.*408409Создаёт объект Unicode из буфера *u* типа Py\_UNICODE заданного размера. *u* может быть *NULL*, что приводит к неопределённости содержимого. Пользователь должен заполнить необходимые данные. Буфер копируется в новый объект.410411Если буфер не равен *NULL*, возвращаемое значение может быть разделяемым объектом. Поэтому изменение результирующего объекта Unicode допускается только когда *u* равен *NULL*.412413Если буфер равен *NULL*, необходимо вызвать [`PyUnicode_READY()`](https://python-all.ru/3.6/c-api/unicode.html#c.PyUnicode_READY) после заполнения содержимого строки перед использованием любых макросов доступа, таких как [`PyUnicode_KIND()`](https://python-all.ru/3.6/c-api/unicode.html#c.PyUnicode_KIND).414415Пожалуйста, переходите на использование [`PyUnicode_FromKindAndData()`](https://python-all.ru/3.6/c-api/unicode.html#c.PyUnicode_FromKindAndData), [`PyUnicode_FromWideChar()`](https://python-all.ru/3.6/c-api/unicode.html#c.PyUnicode_FromWideChar) или [`PyUnicode_New()`](https://python-all.ru/3.6/c-api/unicode.html#c.PyUnicode_New).416417#### `Py_UNICODE* PyUnicode_AsUnicode(PyObject *unicode)`418419Возвращает указатель только для чтения на внутренний [`Py_UNICODE`](https://python-all.ru/3.6/c-api/unicode.html#c.Py_UNICODE) буфер объекта Unicode или *NULL* при ошибке. При необходимости создаётся [`Py_UNICODE*`](https://python-all.ru/3.6/c-api/unicode.html#c.Py_UNICODE) представление объекта, если оно ещё не доступно. Буфер всегда завершается дополнительным нулевым кодовым знаком. Обратите внимание, что результирующая строка [`Py_UNICODE`](https://python-all.ru/3.6/c-api/unicode.html#c.Py_UNICODE) может также содержать встроенные нулевые кодовые знаки, что приведёт к усечению строки при использовании в большинстве функций C.420421Пожалуйста, переходите на использование [`PyUnicode_AsUCS4()`](https://python-all.ru/3.6/c-api/unicode.html#c.PyUnicode_AsUCS4), [`PyUnicode_AsWideChar()`](https://python-all.ru/3.6/c-api/unicode.html#c.PyUnicode_AsWideChar), [`PyUnicode_ReadChar()`](https://python-all.ru/3.6/c-api/unicode.html#c.PyUnicode_ReadChar) или аналогичных новых API.422423#### `PyObject* PyUnicode_TransformDecimalToASCII(Py_UNICODE *s, Py_ssize_t size)`424425Создаёт объект Unicode, заменяя все десятичные цифры в буфере [`Py_UNICODE`](https://python-all.ru/3.6/c-api/unicode.html#c.Py_UNICODE) заданного размера *size* на ASCII-цифры 0–9 в соответствии с их десятичным значением. Возвращает *NULL* при возникновении исключения.426427#### `Py_UNICODE* PyUnicode_AsUnicodeAndSize(PyObject *unicode, Py_ssize_t *size)`428429Как и [`PyUnicode_AsUnicode()`](https://python-all.ru/3.6/c-api/unicode.html#c.PyUnicode_AsUnicode), но также сохраняет длину массива [`Py_UNICODE()`](https://python-all.ru/3.6/c-api/unicode.html#c.Py_UNICODE) (исключая дополнительный нулевой терминатор) в *size*. Обратите внимание, что результирующая строка [`Py_UNICODE*`](https://python-all.ru/3.6/c-api/unicode.html#c.Py_UNICODE) может содержать встроенные нулевые кодовые элементы, что приведёт к усечению строки при использовании в большинстве функций C.430431Новое в версии 3.3.432433#### `Py_UNICODE* PyUnicode_AsUnicodeCopy(PyObject *unicode)`434435Создаёт копию строки Unicode, завершающуюся нулевым кодовым знаком. Возвращает *NULL* и возбуждает исключение [`MemoryError`](https://python-all.ru/3.6/library/exceptions.html#MemoryError) при сбое выделения памяти, в противном случае возвращает новый выделенный буфер (используйте [`PyMem_Free()`](https://python-all.ru/3.6/c-api/memory.html#c.PyMem_Free) для освобождения буфера). Обратите внимание, что результирующая строка [`Py_UNICODE*`](https://python-all.ru/3.6/c-api/unicode.html#c.Py_UNICODE) может содержать встроенные нулевые кодовые знаки, что приведёт к усечению строки при использовании в большинстве функций C.436437Новое в версии 3.2.438439Переходите на использование [`PyUnicode_AsUCS4Copy()`](https://python-all.ru/3.6/c-api/unicode.html#c.PyUnicode_AsUCS4Copy) или аналогичных новых API.440441#### `Py_ssize_t PyUnicode_GetSize(PyObject *unicode)`442443Возвращает размер устаревшего представления [`Py_UNICODE`](https://python-all.ru/3.6/c-api/unicode.html#c.Py_UNICODE), в кодовых единицах (суррогатные пары учитываются как 2 единицы).444445Пожалуйста, переходите на использование [`PyUnicode_GetLength()`](https://python-all.ru/3.6/c-api/unicode.html#c.PyUnicode_GetLength).446447#### `PyObject* PyUnicode_FromObject(PyObject *obj)`448449*Возвращаемое значение: новая ссылка.*450451Копирует экземпляр подтипа Unicode в новый истинный объект Unicode, если это необходимо. Если *obj* уже является истинным объектом Unicode (не подтипом), возвращает ссылку с увеличенным счётчиком ссылок.452453Объекты, отличные от Unicode или его подтипов, вызывают [`TypeError`](https://python-all.ru/3.6/library/exceptions.html#TypeError).454455### Кодировка локали456457Текущую кодировку локали можно использовать для декодирования текста из операционной системы.458459#### `PyObject* PyUnicode_DecodeLocaleAndSize(const char *str, Py_ssize_t len, const char *errors)`460461Декодирует строку из текущей кодировки локали. Поддерживаемые обработчики ошибок: `"strict"` и `"surrogateescape"` ([**PEP 383**](https://python-all.ru/3.6/c-api/unicode.html)). Декодер использует обработчик ошибок `"strict"`, если *errors* равен `NULL`. *str* должен заканчиваться нулевым символом, но не может содержать встроенных нулевых символов.462463Используйте [`PyUnicode_DecodeFSDefaultAndSize()`](https://python-all.ru/3.6/c-api/unicode.html#c.PyUnicode_DecodeFSDefaultAndSize) для декодирования строки из `Py_FileSystemDefaultEncoding` (кодировка локали, полученная при запуске Python).464465> **См. также**466>467> Функция [`Py_DecodeLocale()`](https://python-all.ru/3.6/c-api/sys.html#c.Py_DecodeLocale).468469Новое в версии 3.3.470471Изменено в версии 3.6.5: Теперь функция также использует текущую кодировку локали для обработчика ошибок `surrogateescape`. Ранее для `surrogateescape` использовался [`Py_DecodeLocale()`](https://python-all.ru/3.6/c-api/sys.html#c.Py_DecodeLocale), а для `strict` – текущая кодировка локали.472473#### `PyObject* PyUnicode_DecodeLocale(const char *str, const char *errors)`474475Аналогично [`PyUnicode_DecodeLocaleAndSize()`](https://python-all.ru/3.6/c-api/unicode.html#c.PyUnicode_DecodeLocaleAndSize), но длина строки вычисляется с помощью `strlen()`.476477Новое в версии 3.3.478479#### `PyObject* PyUnicode_EncodeLocale(PyObject *unicode, const char *errors)`480481Кодирует объект Unicode в текущую кодировку локали. Поддерживаемые обработчики ошибок: `"strict"` и `"surrogateescape"` ([**PEP 383**](https://python-all.ru/3.6/c-api/unicode.html)). Кодировщик использует обработчик ошибок `"strict"`, если *errors* равен `NULL`. Возвращает объект [`bytes`](https://python-all.ru/3.6/library/stdtypes.html#bytes). *unicode* не может содержать встроенных нулевых символов.482483Используйте [`PyUnicode_EncodeFSDefault()`](https://python-all.ru/3.6/c-api/unicode.html#c.PyUnicode_EncodeFSDefault) для кодирования строки в `Py_FileSystemDefaultEncoding` (кодировка локали, полученная при запуске Python).484485> **См. также**486>487> Функция [`Py_EncodeLocale()`](https://python-all.ru/3.6/c-api/sys.html#c.Py_EncodeLocale).488489Новое в версии 3.3.490491Изменено в версии 3.6.5: Теперь функция также использует текущую кодировку локали для обработчика ошибок `surrogateescape`. Ранее для `surrogateescape` использовался [`Py_EncodeLocale()`](https://python-all.ru/3.6/c-api/sys.html#c.Py_EncodeLocale), а для `strict` – текущая кодировка локали.492493### Кодировка файловой системы494495Для кодирования и декодирования имён файлов и других строк окружения в качестве кодировки следует использовать `Py_FileSystemDefaultEncoding`, а в качестве обработчика ошибок – `Py_FileSystemDefaultEncodeErrors` ([**PEP 383**](https://python-all.ru/3.6/c-api/unicode.html) и [**PEP 529**](https://python-all.ru/3.6/c-api/unicode.html)). Для кодирования имён файлов в [`bytes`](https://python-all.ru/3.6/library/stdtypes.html#bytes) при разборе аргументов следует использовать преобразователь `"O&"`, передавая [`PyUnicode_FSConverter()`](https://python-all.ru/3.6/c-api/unicode.html#c.PyUnicode_FSConverter) в качестве функции преобразования:496497#### `int PyUnicode_FSConverter(PyObject* obj, void* result)`498499Конвертер ParseTuple: кодирует объекты [`str`](https://python-all.ru/3.6/library/stdtypes.html#str) – полученные напрямую или через интерфейс [`os.PathLike`](https://python-all.ru/3.6/library/os.html#os.PathLike) – в [`bytes`](https://python-all.ru/3.6/library/stdtypes.html#bytes) с помощью [`PyUnicode_EncodeFSDefault()`](https://python-all.ru/3.6/c-api/unicode.html#c.PyUnicode_EncodeFSDefault); объекты [`bytes`](https://python-all.ru/3.6/library/stdtypes.html#bytes) выводятся как есть. *result* должен быть [`PyBytesObject*`](https://python-all.ru/3.6/c-api/bytes.html#c.PyBytesObject), который необходимо освободить, когда он больше не используется.500501Новое в версии 3.1.502503Изменено в версии 3.6: Принимает [объект, подобный пути](https://python-all.ru/3.6/glossary.html#term-path-like-object).504505Для декодирования имен файлов в [`str`](https://python-all.ru/3.6/library/stdtypes.html#str) во время разбора аргументов следует использовать конвертер `"O&"`, передавая [`PyUnicode_FSDecoder()`](https://python-all.ru/3.6/c-api/unicode.html#c.PyUnicode_FSDecoder) в качестве функции преобразования:506507#### `int PyUnicode_FSDecoder(PyObject* obj, void* result)`508509Конвертер ParseTuple: декодирует объекты [`bytes`](https://python-all.ru/3.6/library/stdtypes.html#bytes) – полученные либо напрямую, либо косвенно через интерфейс [`os.PathLike`](https://python-all.ru/3.6/library/os.html#os.PathLike) – в [`str`](https://python-all.ru/3.6/library/stdtypes.html#str) с помощью [`PyUnicode_DecodeFSDefaultAndSize()`](https://python-all.ru/3.6/c-api/unicode.html#c.PyUnicode_DecodeFSDefaultAndSize); объекты [`str`](https://python-all.ru/3.6/library/stdtypes.html#str) выводятся как есть. *result* должен быть [`PyUnicodeObject*`](https://python-all.ru/3.6/c-api/unicode.html#c.PyUnicodeObject), который необходимо освободить, когда он больше не используется.510511Новое в версии 3.2.512513Изменено в версии 3.6: Принимает [объект, подобный пути](https://python-all.ru/3.6/glossary.html#term-path-like-object).514515#### `PyObject* PyUnicode_DecodeFSDefaultAndSize(const char *s, Py_ssize_t size)`516517Декодирует строку с использованием `Py_FileSystemDefaultEncoding` и обработчика ошибок `Py_FileSystemDefaultEncodeErrors`.518519Если `Py_FileSystemDefaultEncoding` не задана, используется кодировка локали.520521`Py_FileSystemDefaultEncoding` инициализируется при запуске из кодировки локали и не может быть изменена позднее. Если требуется декодировать строку из текущей кодировки локали, используйте [`PyUnicode_DecodeLocaleAndSize()`](https://python-all.ru/3.6/c-api/unicode.html#c.PyUnicode_DecodeLocaleAndSize).522523> **См. также**524>525> Функция [`Py_DecodeLocale()`](https://python-all.ru/3.6/c-api/sys.html#c.Py_DecodeLocale).526527Изменено в версии 3.6: Используйте обработчик ошибок `Py_FileSystemDefaultEncodeErrors`.528529#### `PyObject* PyUnicode_DecodeFSDefault(const char *s)`530531Декодирует строку, завершающуюся нулевым символом, с использованием `Py_FileSystemDefaultEncoding` и обработчика ошибок `Py_FileSystemDefaultEncodeErrors`.532533Если `Py_FileSystemDefaultEncoding` не задана, используется кодировка локали.534535Используйте [`PyUnicode_DecodeFSDefaultAndSize()`](https://python-all.ru/3.6/c-api/unicode.html#c.PyUnicode_DecodeFSDefaultAndSize), если известна длина строки.536537Изменено в версии 3.6: Используйте обработчик ошибок `Py_FileSystemDefaultEncodeErrors`.538539#### `PyObject* PyUnicode_EncodeFSDefault(PyObject *unicode)`540541Кодирует объект Unicode в `Py_FileSystemDefaultEncoding` с обработчиком ошибок `Py_FileSystemDefaultEncodeErrors` и возвращает [`bytes`](https://python-all.ru/3.6/library/stdtypes.html#bytes). Обратите внимание, что результирующий объект [`bytes`](https://python-all.ru/3.6/library/stdtypes.html#bytes) может содержать нулевые байты.542543Если `Py_FileSystemDefaultEncoding` не задана, используется кодировка локали.544545`Py_FileSystemDefaultEncoding` инициализируется при запуске из кодировки локали и не может быть изменена позднее. Если требуется закодировать строку в текущую кодировку локали, используйте [`PyUnicode_EncodeLocale()`](https://python-all.ru/3.6/c-api/unicode.html#c.PyUnicode_EncodeLocale).546547> **См. также**548>549> Функция [`Py_EncodeLocale()`](https://python-all.ru/3.6/c-api/sys.html#c.Py_EncodeLocale).550551Новое в версии 3.2.552553Изменено в версии 3.6: Используйте обработчик ошибок `Py_FileSystemDefaultEncodeErrors`.554555### Поддержка wchar\_t556557`wchar_t` поддержка на платформах, которые её поддерживают:558559#### `PyObject* PyUnicode_FromWideChar(const wchar_t *w, Py_ssize_t size)`560561*Возвращаемое значение: новая ссылка.*562563Создаёт объект Unicode из буфера `wchar_t` *w* заданного *размера*. Передача `-1` в качестве *size* означает, что функция должна сама вычислить длину, используя wcslen. Возвращает *NULL* при ошибке.564565#### `Py_ssize_t PyUnicode_AsWideChar(PyObject *unicode, wchar_t *w, Py_ssize_t size)`566567Копирует содержимое объекта Unicode в буфер `wchar_t` *w*. Копируется не более *size* символов `wchar_t` (исключая возможный завершающий нулевой символ). Возвращает количество скопированных символов `wchar_t` или `-1` в случае ошибки. Обратите внимание, что результирующая строка `wchar_t*` может быть как завершена нулевым символом, так и нет. Вызывающий обязан убедиться, что строка `wchar_t*` завершена нулевым символом, если это требуется приложением. Кроме того, строка `wchar_t*` может содержать нулевые символы, что приведёт к усечению строки при использовании с большинством функций C.568569#### `wchar_t* PyUnicode_AsWideCharString(PyObject *unicode, Py_ssize_t *size)`570571Преобразует объект Unicode в строку широких символов. Выходная строка всегда завершается нулевым символом. Если *size* не равно *NULL*, записывает количество широких символов (исключая завершающий нулевой символ) в *\*size*.572573Возвращает буфер, выделенный `PyMem_Alloc()` (используйте [`PyMem_Free()`](https://python-all.ru/3.6/c-api/memory.html#c.PyMem_Free) для его освобождения) в случае успеха. При ошибке возвращает *NULL*, *\*size* не определено и возбуждается [`MemoryError`](https://python-all.ru/3.6/library/exceptions.html#MemoryError). Обратите внимание, что результирующая строка `wchar_t` может содержать нулевые символы, что приведёт к усечению строки при использовании с большинством функций C.574575Новое в версии 3.2.576577## Встроенные кодеки578579Python предоставляет набор встроенных кодеков, написанных на C для скорости. Все эти кодеки могут использоваться напрямую через следующие функции.580581Многие из следующих API принимают два аргумента: encoding и errors, и их семантика совпадает с семантикой соответствующих аргументов встроенного конструктора строк [`str()`](https://python-all.ru/3.6/library/stdtypes.html#str).582583Установка encoding в *NULL* приводит к использованию кодировки по умолчанию, которой является ASCII. Системные вызовы файловой системы должны использовать [`PyUnicode_FSConverter()`](https://python-all.ru/3.6/c-api/unicode.html#c.PyUnicode_FSConverter) для кодирования имён файлов. Внутри это использует переменную `Py_FileSystemDefaultEncoding`. Эту переменную следует рассматривать как доступную только для чтения: на некоторых системах она будет указателем на статическую строку, на других – изменяться во время выполнения (например, когда приложение вызывает setlocale).584585Обработка ошибок задаётся параметром errors, который также может быть установлен в *NULL*, что означает использование обработки по умолчанию, определённой для кодека. Обработка ошибок по умолчанию для всех встроенных кодеков – «strict» (возбуждается [`ValueError`](https://python-all.ru/3.6/library/exceptions.html#ValueError)).586587Все кодеки используют похожий интерфейс. Для простоты документированы только отклонения от следующего общего описания.588589### Общие кодеки590591Это общие API кодеков:592593#### `PyObject* PyUnicode_Decode(const char *s, Py_ssize_t size, const char *encoding, const char *errors)`594595*Возвращаемое значение: новая ссылка.*596597Создаёт объект Unicode путём декодирования *size* байт закодированной строки *s*. *encoding* и *errors* имеют тот же смысл, что и одноимённые параметры во встроенной функции [`str()`](https://python-all.ru/3.6/library/stdtypes.html#str). Используемый кодек ищется с помощью реестра кодеков Python. Возвращает *NULL*, если кодек возбудил исключение.598599#### `PyObject* PyUnicode_AsEncodedString(PyObject *unicode, const char *encoding, const char *errors)`600601*Возвращаемое значение: новая ссылка.*602603Кодирует объект Unicode и возвращает результат в виде объекта bytes Python. *encoding* и *errors* имеют тот же смысл, что и одноимённые параметры в методе Unicode [`encode()`](https://python-all.ru/3.6/library/stdtypes.html#str.encode). Используемый кодек ищется с помощью реестра кодеков Python. Возвращает *NULL*, если кодек возбудил исключение.604605#### `PyObject* PyUnicode_Encode(const Py_UNICODE *s, Py_ssize_t size, const char *encoding, const char *errors)`606607*Возвращаемое значение: новая ссылка.*608609Кодирует буфер [`Py_UNICODE`](https://python-all.ru/3.6/c-api/unicode.html#c.Py_UNICODE) *s* заданного *размера* и возвращает объект bytes Python. *encoding* и *errors* имеют тот же смысл, что и одноимённые параметры в методе Unicode [`encode()`](https://python-all.ru/3.6/library/stdtypes.html#str.encode). Используемый кодек ищется с помощью реестра кодеков Python. Возвращает *NULL*, если кодек возбудил исключение.610611Устарело с версии 3.3, будет удалено в версии 4.0: Часть старого API [`Py_UNICODE`](https://python-all.ru/3.6/c-api/unicode.html#c.Py_UNICODE); переходите на использование [`PyUnicode_AsEncodedString()`](https://python-all.ru/3.6/c-api/unicode.html#c.PyUnicode_AsEncodedString).612613### Кодеки UTF-8614615Это API кодеков UTF-8:616617#### `PyObject* PyUnicode_DecodeUTF8(const char *s, Py_ssize_t size, const char *errors)`618619*Возвращаемое значение: новая ссылка.*620621Создаёт объект Unicode путём декодирования *size* байт строки, закодированной в UTF-8, *s*. Возвращает *NULL*, если кодек возбудил исключение.622623#### `PyObject* PyUnicode_DecodeUTF8Stateful(const char *s, Py_ssize_t size, const char *errors, Py_ssize_t *consumed)`624625*Возвращаемое значение: новая ссылка.*626627Если *consumed* равно *NULL*, ведёт себя как [`PyUnicode_DecodeUTF8()`](https://python-all.ru/3.6/c-api/unicode.html#c.PyUnicode_DecodeUTF8). Если *consumed* не равно *NULL*, концевые неполные последовательности байт UTF-8 не будут считаться ошибкой. Эти байты не будут декодированы, а количество байт, которые были декодированы, будет сохранено в *consumed*.628629#### `PyObject* PyUnicode_AsUTF8String(PyObject *unicode)`630631*Возвращаемое значение: новая ссылка.*632633Кодирует объект Unicode с использованием UTF-8 и возвращает результат в виде объекта bytes Python. Обработка ошибок – «strict». Возвращает *NULL*, если кодек возбудил исключение.634635#### `char* PyUnicode_AsUTF8AndSize(PyObject *unicode, Py_ssize_t *size)`636637Возвращает указатель на UTF-8 кодировку объекта Unicode и сохраняет размер закодированного представления (в байтах) в *size*. Аргумент *size* может быть *NULL*; в этом случае размер не сохраняется. Возвращаемый буфер всегда имеет добавленный дополнительный нулевой байт (не включённый в *size*), независимо от наличия других нулевых кодовых точек.638639В случае ошибки возвращается *NULL* с установленным исключением, и *size* не сохраняется.640641Это кэширует UTF-8 представление строки в объекте Unicode, и последующие вызовы будут возвращать указатель на тот же буфер. Вызывающая сторона не отвечает за освобождение буфера.642643Новое в версии 3.3.644645#### `char* PyUnicode_AsUTF8(PyObject *unicode)`646647Как [`PyUnicode_AsUTF8AndSize()`](https://python-all.ru/3.6/c-api/unicode.html#c.PyUnicode_AsUTF8AndSize), но не сохраняет размер.648649Новое в версии 3.3.650651#### `PyObject* PyUnicode_EncodeUTF8(const Py_UNICODE *s, Py_ssize_t size, const char *errors)`652653*Возвращаемое значение: новая ссылка.*654655Кодирует буфер [`Py_UNICODE`](https://python-all.ru/3.6/c-api/unicode.html#c.Py_UNICODE) *s* заданного *размера* с использованием UTF-8 и возвращает объект bytes Python. Возвращает *NULL*, если кодек возбудил исключение.656657Устарело с версии 3.3, будет удалено в версии 4.0: Часть старого API [`Py_UNICODE`](https://python-all.ru/3.6/c-api/unicode.html#c.Py_UNICODE); переходите на использование [`PyUnicode_AsUTF8String()`](https://python-all.ru/3.6/c-api/unicode.html#c.PyUnicode_AsUTF8String), [`PyUnicode_AsUTF8AndSize()`](https://python-all.ru/3.6/c-api/unicode.html#c.PyUnicode_AsUTF8AndSize) или [`PyUnicode_AsEncodedString()`](https://python-all.ru/3.6/c-api/unicode.html#c.PyUnicode_AsEncodedString).658659### Кодеки UTF-32660661Это API кодеков UTF-32:662663#### `PyObject* PyUnicode_DecodeUTF32(const char *s, Py_ssize_t size, const char *errors, int *byteorder)`664665Декодирует *size* байт из строки буфера в кодировке UTF-32 и возвращает соответствующий объект Unicode. *errors* (если не *NULL*) определяет обработку ошибок. По умолчанию используется «strict».666667Если *byteorder* не равен *NULL*, декодер начинает декодирование с использованием заданного порядка байтов:668669```c670*byteorder == -1: little endian671*byteorder == 0:  native order672*byteorder == 1:  big endian673```674675Если `*byteorder` равен нулю и первые четыре байта входных данных являются маркером порядка байтов (BOM), декодер переключается на этот порядок байтов, и BOM не копируется в результирующую строку Unicode. Если `*byteorder` равно `-1` или `1`, любой маркер порядка байтов копируется в выходные данные.676677После завершения *\*byteorder* устанавливается в текущий порядок байтов в конце входных данных.678679Если *byteorder* равен *NULL*, кодек запускается в режиме собственного порядка байтов.680681Возвращает *NULL*, если кодек сгенерировал исключение.682683#### `PyObject* PyUnicode_DecodeUTF32Stateful(const char *s, Py_ssize_t size, const char *errors, int *byteorder, Py_ssize_t *consumed)`684685Если *consumed* равен *NULL*, ведёт себя как [`PyUnicode_DecodeUTF32()`](https://python-all.ru/3.6/c-api/unicode.html#c.PyUnicode_DecodeUTF32). Если *consumed* не равен *NULL*, [`PyUnicode_DecodeUTF32Stateful()`](https://python-all.ru/3.6/c-api/unicode.html#c.PyUnicode_DecodeUTF32Stateful) не будет считать неполные завершающие последовательности байт UTF-32 (например, количество байт, не кратное четырём) ошибкой. Эти байты не будут декодированы, а количество декодированных байт будет сохранено в *consumed*.686687#### `PyObject* PyUnicode_AsUTF32String(PyObject *unicode)`688689Возвращает Python-строку байт в кодировке UTF-32 с собственным порядком байтов. Строка всегда начинается с маркера BOM. Обработка ошибок – «strict». Возвращает *NULL*, если кодек сгенерировал исключение.690691#### `PyObject* PyUnicode_EncodeUTF32(const Py_UNICODE *s, Py_ssize_t size, const char *errors, int byteorder)`692693Возвращает объект Python bytes, содержащий значение Unicode-данных из *s*, закодированное в UTF-32. Вывод записывается в соответствии со следующим порядком байтов:694695```c696byteorder == -1: little endian697byteorder == 0:  native byte order (writes a BOM mark)698byteorder == 1:  big endian699```700701Если `0`, выходная строка всегда начинается с метки BOM Unicode (U+FEFF). В двух других режимах метка BOM не добавляется.702703Если *Py\_UNICODE\_WIDE* не определён, суррогатные пары будут выводиться как одна кодовая точка.704705Возвращает *NULL*, если кодек сгенерировал исключение.706707Устарело с версии 3.3, будет удалено в версии 4.0: Часть устаревшего [`Py_UNICODE`](https://python-all.ru/3.6/c-api/unicode.html#c.Py_UNICODE) API; переходите на использование [`PyUnicode_AsUTF32String()`](https://python-all.ru/3.6/c-api/unicode.html#c.PyUnicode_AsUTF32String) или [`PyUnicode_AsEncodedString()`](https://python-all.ru/3.6/c-api/unicode.html#c.PyUnicode_AsEncodedString).708709### Кодеки UTF-32710711Это API кодеков UTF-32:712713#### `PyObject* PyUnicode_DecodeUTF16(const char *s, Py_ssize_t size, const char *errors, int *byteorder)`714715*Возвращаемое значение: новая ссылка.*716717Декодирует *size* байт из строки буфера в кодировке UTF-16 и возвращает соответствующий объект Unicode. *errors* (если не *NULL*) определяет обработку ошибок. По умолчанию используется «strict».718719Если *byteorder* не равен *NULL*, декодер начинает декодирование с использованием заданного порядка байтов:720721```c722*byteorder == -1: little endian723*byteorder == 0:  native order724*byteorder == 1:  big endian725```726727Если `*byteorder` равен нулю и первые два байта входных данных являются меткой порядка байтов (BOM), декодер переключается на этот порядок байтов, а BOM не копируется в результирующую строку Unicode. Если `*byteorder` равен `-1` или `1`, любая метка порядка байтов копируется в выходные данные (что приведёт к символу `\ufeff` или `\ufffe`).728729После завершения *\*byteorder* устанавливается в текущий порядок байтов в конце входных данных.730731Если *byteorder* равен *NULL*, кодек запускается в режиме собственного порядка байтов.732733Возвращает *NULL*, если кодек сгенерировал исключение.734735#### `PyObject* PyUnicode_DecodeUTF16Stateful(const char *s, Py_ssize_t size, const char *errors, int *byteorder, Py_ssize_t *consumed)`736737*Возвращаемое значение: новая ссылка.*738739Если *consumed* равен *NULL*, ведёт себя как [`PyUnicode_DecodeUTF16()`](https://python-all.ru/3.6/c-api/unicode.html#c.PyUnicode_DecodeUTF16). Если *consumed* не равен *NULL*, [`PyUnicode_DecodeUTF16Stateful()`](https://python-all.ru/3.6/c-api/unicode.html#c.PyUnicode_DecodeUTF16Stateful) не будет считать неполные завершающие последовательности байт UTF-16 (например, нечётное количество байт или разделённую суррогатную пару) ошибкой. Эти байты не будут декодированы, а количество декодированных байт будет сохранено в *consumed*.740741#### `PyObject* PyUnicode_AsUTF16String(PyObject *unicode)`742743*Возвращаемое значение: новая ссылка.*744745Возвращает Python-строку байт в кодировке UTF-16 с собственным порядком байтов. Строка всегда начинается с маркера BOM. Обработка ошибок – «strict». Возвращает *NULL*, если кодек сгенерировал исключение.746747#### `PyObject* PyUnicode_EncodeUTF16(const Py_UNICODE *s, Py_ssize_t size, const char *errors, int byteorder)`748749*Возвращаемое значение: новая ссылка.*750751Возвращает объект Python bytes, содержащий значение Unicode-данных из *s*, закодированное в UTF-16. Вывод записывается в соответствии со следующим порядком байтов:752753```c754byteorder == -1: little endian755byteorder == 0:  native byte order (writes a BOM mark)756byteorder == 1:  big endian757```758759Если `0`, выходная строка всегда начинается с метки BOM Unicode (U+FEFF). В двух других режимах метка BOM не добавляется.760761Если *Py\_UNICODE\_WIDE* определён, одно значение [`Py_UNICODE`](https://python-all.ru/3.6/c-api/unicode.html#c.Py_UNICODE) может быть представлено как суррогатная пара. Если он не определён, каждое значение [`Py_UNICODE`](https://python-all.ru/3.6/c-api/unicode.html#c.Py_UNICODE) интерпретируется как символ UCS-2.762763Возвращает *NULL*, если кодек сгенерировал исключение.764765Устарело с версии 3.3, будет удалено в версии 4.0: Часть устаревшего [`Py_UNICODE`](https://python-all.ru/3.6/c-api/unicode.html#c.Py_UNICODE) API; переходите на использование [`PyUnicode_AsUTF16String()`](https://python-all.ru/3.6/c-api/unicode.html#c.PyUnicode_AsUTF16String) или [`PyUnicode_AsEncodedString()`](https://python-all.ru/3.6/c-api/unicode.html#c.PyUnicode_AsEncodedString).766767### Кодеки UTF-7768769Это API кодеков UTF-7:770771#### `PyObject* PyUnicode_DecodeUTF7(const char *s, Py_ssize_t size, const char *errors)`772773Создаёт объект Unicode путём декодирования *size* байт строки в кодировке UTF-7 *s*. Возвращает *NULL*, если кодек сгенерировал исключение.774775#### `PyObject* PyUnicode_DecodeUTF7Stateful(const char *s, Py_ssize_t size, const char *errors, Py_ssize_t *consumed)`776777Если *consumed* равен *NULL*, ведёт себя как [`PyUnicode_DecodeUTF7()`](https://python-all.ru/3.6/c-api/unicode.html#c.PyUnicode_DecodeUTF7). Если *consumed* не равен *NULL*, завершающие неполные секции base-64 UTF-7 не будут считаться ошибкой. Эти байты не будут декодированы, а количество декодированных байт будет сохранено в *consumed*.778779#### `PyObject* PyUnicode_EncodeUTF7(const Py_UNICODE *s, Py_ssize_t size, int base64SetO, int base64WhiteSpace, const char *errors)`780781Кодирует буфер [`Py_UNICODE`](https://python-all.ru/3.6/c-api/unicode.html#c.Py_UNICODE) заданного размера с использованием UTF-7 и возвращает объект Python bytes. Возвращает *NULL*, если кодек сгенерировал исключение.782783Если *base64SetO* не равно нулю, «Set O» (знаки препинания, не имеющие иного особого значения) будут закодированы в base-64. Если *base64WhiteSpace* не равно нулю, пробельные символы будут закодированы в base-64. Оба параметра установлены в ноль для кодека Python «utf-7».784785Устарело с версии 3.3, будет удалено в версии 4.0: Часть старого API [`Py_UNICODE`](https://python-all.ru/3.6/c-api/unicode.html#c.Py_UNICODE); переходите на использование [`PyUnicode_AsEncodedString()`](https://python-all.ru/3.6/c-api/unicode.html#c.PyUnicode_AsEncodedString).786787### Кодеки Unicode-Escape788789Это API кодеков «Unicode Escape»:790791#### `PyObject* PyUnicode_DecodeUnicodeEscape(const char *s, Py_ssize_t size, const char *errors)`792793*Возвращаемое значение: новая ссылка.*794795Создаёт объект Unicode путём декодирования *size* байт строки в кодировке Unicode-Escape *s*. Возвращает *NULL*, если кодек сгенерировал исключение.796797#### `PyObject* PyUnicode_AsUnicodeEscapeString(PyObject *unicode)`798799*Возвращаемое значение: новая ссылка.*800801Кодирует объект Unicode с помощью Unicode-Escape и возвращает результат как объект bytes. Обработка ошибок – “strict”. Возвращает *NULL*, если кодек вызвал исключение.802803#### `PyObject* PyUnicode_EncodeUnicodeEscape(const Py_UNICODE *s, Py_ssize_t size)`804805*Возвращаемое значение: новая ссылка.*806807Кодирует буфер [`Py_UNICODE`](https://python-all.ru/3.6/c-api/unicode.html#c.Py_UNICODE) заданного размера *size* с помощью Unicode-Escape и возвращает объект bytes. Возвращает *NULL*, если кодек вызвал исключение.808809Устарело с версии 3.3, будет удалено в версии 4.0: Часть старого API [`Py_UNICODE`](https://python-all.ru/3.6/c-api/unicode.html#c.Py_UNICODE); переходите на использование [`PyUnicode_AsUnicodeEscapeString()`](https://python-all.ru/3.6/c-api/unicode.html#c.PyUnicode_AsUnicodeEscapeString).810811### Кодеки Raw-Unicode-Escape812813Это API кодеков «Raw Unicode Escape»:814815#### `PyObject* PyUnicode_DecodeRawUnicodeEscape(const char *s, Py_ssize_t size, const char *errors)`816817*Возвращаемое значение: новая ссылка.*818819Создаёт объект Unicode путём декодирования *size* байт строки *s*, закодированной в Raw-Unicode-Escape. Возвращает *NULL*, если кодек вызвал исключение.820821#### `PyObject* PyUnicode_AsRawUnicodeEscapeString(PyObject *unicode)`822823*Возвращаемое значение: новая ссылка.*824825Кодирует объект Unicode с помощью Raw-Unicode-Escape и возвращает результат как объект bytes. Обработка ошибок – “strict”. Возвращает *NULL*, если кодек вызвал исключение.826827#### `PyObject* PyUnicode_EncodeRawUnicodeEscape(const Py_UNICODE *s, Py_ssize_t size)`828829*Возвращаемое значение: новая ссылка.*830831Кодирует буфер [`Py_UNICODE`](https://python-all.ru/3.6/c-api/unicode.html#c.Py_UNICODE) заданного размера *size* с помощью Raw-Unicode-Escape и возвращает объект bytes. Возвращает *NULL*, если кодек вызвал исключение.832833Устарело с версии 3.3, будет удалено в версии 4.0: часть старого API [`Py_UNICODE`](https://python-all.ru/3.6/c-api/unicode.html#c.Py_UNICODE); переходите на использование [`PyUnicode_AsRawUnicodeEscapeString()`](https://python-all.ru/3.6/c-api/unicode.html#c.PyUnicode_AsRawUnicodeEscapeString) или [`PyUnicode_AsEncodedString()`](https://python-all.ru/3.6/c-api/unicode.html#c.PyUnicode_AsEncodedString).834835### Кодеки Latin-1836837Это API кодеков Latin-1: Latin-1 соответствует первым 256 кодовым позициям Unicode, и только они принимаются кодеками при кодировании.838839#### `PyObject* PyUnicode_DecodeLatin1(const char *s, Py_ssize_t size, const char *errors)`840841*Возвращаемое значение: новая ссылка.*842843Создаёт объект Unicode путём декодирования *size* байт строки *s*, закодированной в Latin-1. Возвращает *NULL*, если кодек вызвал исключение.844845#### `PyObject* PyUnicode_AsLatin1String(PyObject *unicode)`846847*Возвращаемое значение: новая ссылка.*848849Кодирует объект Unicode с помощью Latin-1 и возвращает результат как объект bytes Python. Обработка ошибок – “strict”. Возвращает *NULL*, если кодек вызвал исключение.850851#### `PyObject* PyUnicode_EncodeLatin1(const Py_UNICODE *s, Py_ssize_t size, const char *errors)`852853*Возвращаемое значение: новая ссылка.*854855Кодирует буфер [`Py_UNICODE`](https://python-all.ru/3.6/c-api/unicode.html#c.Py_UNICODE) заданного размера *size* с помощью Latin-1 и возвращает объект bytes Python. Возвращает *NULL*, если кодек вызвал исключение.856857Устарело с версии 3.3, будет удалено в версии 4.0: часть старого API [`Py_UNICODE`](https://python-all.ru/3.6/c-api/unicode.html#c.Py_UNICODE); переходите на использование [`PyUnicode_AsLatin1String()`](https://python-all.ru/3.6/c-api/unicode.html#c.PyUnicode_AsLatin1String) или [`PyUnicode_AsEncodedString()`](https://python-all.ru/3.6/c-api/unicode.html#c.PyUnicode_AsEncodedString).858859### Кодеки ASCII860861Это API кодеков ASCII. Принимаются только 7-битные данные ASCII. Все остальные коды вызывают ошибки.862863#### `PyObject* PyUnicode_DecodeASCII(const char *s, Py_ssize_t size, const char *errors)`864865*Возвращаемое значение: новая ссылка.*866867Создаёт объект Unicode путём декодирования *size* байт строки *s*, закодированной в ASCII. Возвращает *NULL*, если кодек вызвал исключение.868869#### `PyObject* PyUnicode_AsASCIIString(PyObject *unicode)`870871*Возвращаемое значение: новая ссылка.*872873Кодирует объект Unicode с помощью ASCII и возвращает результат как объект bytes Python. Обработка ошибок – “strict”. Возвращает *NULL*, если кодек вызвал исключение.874875#### `PyObject* PyUnicode_EncodeASCII(const Py_UNICODE *s, Py_ssize_t size, const char *errors)`876877*Возвращаемое значение: новая ссылка.*878879Кодирует буфер [`Py_UNICODE`](https://python-all.ru/3.6/c-api/unicode.html#c.Py_UNICODE) заданного размера *size* с помощью ASCII и возвращает объект bytes Python. Возвращает *NULL*, если кодек вызвал исключение.880881Устарело с версии 3.3, будет удалено в версии 4.0: часть старого API [`Py_UNICODE`](https://python-all.ru/3.6/c-api/unicode.html#c.Py_UNICODE); переходите на использование [`PyUnicode_AsASCIIString()`](https://python-all.ru/3.6/c-api/unicode.html#c.PyUnicode_AsASCIIString) или [`PyUnicode_AsEncodedString()`](https://python-all.ru/3.6/c-api/unicode.html#c.PyUnicode_AsEncodedString).882883### Кодеки с таблицей символов884885Этот кодек особенный тем, что его можно использовать для реализации множества различных кодеков (и именно так были получены большинство стандартных кодеков, входящих в пакет `encodings`). Кодек использует отображение для кодирования и декодирования символов. Предоставляемые объекты отображения должны поддерживать интерфейс отображения [`__getitem__()`](https://python-all.ru/3.6/reference/datamodel.html#object.__getitem__); словари и последовательности хорошо подходят.886887Это API кодеков отображения:888889#### `PyObject* PyUnicode_DecodeCharmap(const char *data, Py_ssize_t size, PyObject *mapping, const char *errors)`890891*Возвращаемое значение: новая ссылка.*892893Создаёт объект Unicode путём декодирования *size* байт закодированной строки *s* с использованием заданного объекта *mapping*. Возвращает *NULL*, если кодек вызвал исключение.894895Если *mapping* равен *NULL*, применяется декодирование Latin-1. В противном случае *mapping* должен отображать порядковые номера байт (целые числа от 0 до 255) в строки Unicode, целые числа (которые затем интерпретируются как кодовые точки Unicode) или `None`. Неотображённые байты данных – те, которые вызывают [`LookupError`](https://python-all.ru/3.6/library/exceptions.html#LookupError), а также те, которые отображаются в `None`, `0xFFFE` или `'\ufffe'`, считаются неопределёнными отображениями и вызывают ошибку.896897#### `PyObject* PyUnicode_AsCharmapString(PyObject *unicode, PyObject *mapping)`898899*Возвращаемое значение: новая ссылка.*900901Кодирует объект Unicode с использованием заданного объекта *mapping* и возвращает результат как объект bytes. Обработка ошибок – “strict”. Возвращает *NULL*, если кодек вызвал исключение.902903Объект *mapping* должен отображать целые числа – кодовые позиции Unicode – в объекты bytes, целые числа в диапазоне от 0 до 255 или `None`. Неотображённые кодовые позиции символов (те, которые вызывают [`LookupError`](https://python-all.ru/3.6/library/exceptions.html#LookupError)), а также отображённые в `None` считаются «неопределённым отображением» и вызывают ошибку.904905#### `PyObject* PyUnicode_EncodeCharmap(const Py_UNICODE *s, Py_ssize_t size, PyObject *mapping, const char *errors)`906907*Возвращаемое значение: новая ссылка.*908909Кодирует буфер [`Py_UNICODE`](https://python-all.ru/3.6/c-api/unicode.html#c.Py_UNICODE) заданного размера *size* с использованием заданного объекта *mapping* и возвращает результат как объект bytes. Возвращает *NULL*, если кодек вызвал исключение.910911Устарело с версии 3.3, будет удалено в версии 4.0: часть старого API [`Py_UNICODE`](https://python-all.ru/3.6/c-api/unicode.html#c.Py_UNICODE); переходите на использование [`PyUnicode_AsCharmapString()`](https://python-all.ru/3.6/c-api/unicode.html#c.PyUnicode_AsCharmapString) или [`PyUnicode_AsEncodedString()`](https://python-all.ru/3.6/c-api/unicode.html#c.PyUnicode_AsEncodedString).912913Следующее API кодека особенное тем, что отображает Unicode в Unicode.914915#### `PyObject* PyUnicode_Translate(PyObject *unicode, PyObject *mapping, const char *errors)`916917*Возвращаемое значение: новая ссылка.*918919Преобразует объект Unicode с использованием заданного объекта *mapping* и возвращает результирующий объект Unicode. Возвращает *NULL*, если кодек вызвал исключение.920921Объект *mapping* должен отображать целые числа – коды Unicode – в строки Unicode, целые числа (которые затем интерпретируются как коды Unicode) или `None` (что приводит к удалению символа). Неотображённые коды символов (те, которые вызывают [`LookupError`](https://python-all.ru/3.6/library/exceptions.html#LookupError)) остаются нетронутыми и копируются как есть.922923#### `PyObject* PyUnicode_TranslateCharmap(const Py_UNICODE *s, Py_ssize_t size, PyObject *mapping, const char *errors)`924925*Возвращаемое значение: новая ссылка.*926927Преобразует буфер [`Py_UNICODE`](https://python-all.ru/3.6/c-api/unicode.html#c.Py_UNICODE) заданного размера *size*, применяя к нему таблицу *mapping* символов, и возвращает результирующий объект Unicode. Возвращает *NULL*, если кодек вызвал исключение.928929Устарело с версии 3.3, будет удалено в версии 4.0: часть старого API [`Py_UNICODE`](https://python-all.ru/3.6/c-api/unicode.html#c.Py_UNICODE); переходите на использование [`PyUnicode_Translate()`](https://python-all.ru/3.6/c-api/unicode.html#c.PyUnicode_Translate). или [API на основе обобщённых кодеков](https://python-all.ru/3.6/c-api/codec.html#codec-registry)930931### Кодеки MBCS для Windows932933Это API кодеков MBCS. В настоящее время они доступны только в Windows и используют преобразователи Win32 MBCS для выполнения преобразований. Обратите внимание, что MBCS (или DBCS) – это класс кодировок, а не одна конкретная. Целевая кодировка определяется пользовательскими настройками на машине, где выполняется кодек.934935#### `PyObject* PyUnicode_DecodeMBCS(const char *s, Py_ssize_t size, const char *errors)`936937*Возвращаемое значение: новая ссылка.*938939Создаёт объект Unicode, декодируя *size* байтов строки, закодированной в MBCS, из *s*. Возвращает *NULL*, если кодек вызвал исключение.940941#### `PyObject* PyUnicode_DecodeMBCSStateful(const char *s, Py_ssize_t size, const char *errors, Py_ssize_t *consumed)`942943Если *consumed* равен *NULL*, действует как [`PyUnicode_DecodeMBCS()`](https://python-all.ru/3.6/c-api/unicode.html#c.PyUnicode_DecodeMBCS). Если *consumed* не равен *NULL*, [`PyUnicode_DecodeMBCSStateful()`](https://python-all.ru/3.6/c-api/unicode.html#c.PyUnicode_DecodeMBCSStateful) не будет декодировать замыкающий ведущий байт, а количество декодированных байтов будет сохранено в *consumed*.944945#### `PyObject* PyUnicode_AsMBCSString(PyObject *unicode)`946947*Возвращаемое значение: новая ссылка.*948949Кодирует объект Unicode с помощью MBCS и возвращает результат в виде объекта bytes Python. Обработка ошибок – "strict". Возвращает *NULL*, если кодек вызвал исключение.950951#### `PyObject* PyUnicode_EncodeCodePage(int code_page, PyObject *unicode, const char *errors)`952953Кодирует объект Unicode, используя указанную кодовую страницу, и возвращает объект bytes Python. Возвращает *NULL*, если кодек вызвал исключение. Используйте кодовую страницу `CP_ACP` для получения кодировщика MBCS.954955Новое в версии 3.3.956957#### `PyObject* PyUnicode_EncodeMBCS(const Py_UNICODE *s, Py_ssize_t size, const char *errors)`958959*Возвращаемое значение: новая ссылка.*960961Кодирует буфер [`Py_UNICODE`](https://python-all.ru/3.6/c-api/unicode.html#c.Py_UNICODE) заданного размера *size* с помощью MBCS и возвращает объект bytes Python. Возвращает *NULL*, если кодек вызвал исключение.962963Устарело с версии 3.3, будет удалено в версии 4.0: Часть старого API [`Py_UNICODE`](https://python-all.ru/3.6/c-api/unicode.html#c.Py_UNICODE); переходите на использование [`PyUnicode_AsMBCSString()`](https://python-all.ru/3.6/c-api/unicode.html#c.PyUnicode_AsMBCSString), [`PyUnicode_EncodeCodePage()`](https://python-all.ru/3.6/c-api/unicode.html#c.PyUnicode_EncodeCodePage) или [`PyUnicode_AsEncodedString()`](https://python-all.ru/3.6/c-api/unicode.html#c.PyUnicode_AsEncodedString).964965### Методы и слоты966967## Методы и слот-функции968969Следующие API могут обрабатывать объекты Unicode и строки на входе (в описаниях мы называем их строками) и возвращают объекты Unicode или целые числа по необходимости.970971Все они возвращают *NULL* или `-1` в случае исключения.972973#### `PyObject* PyUnicode_Concat(PyObject *left, PyObject *right)`974975*Возвращаемое значение: новая ссылка.*976977Объединяет две строки, возвращая новую строку Unicode.978979#### `PyObject* PyUnicode_Split(PyObject *s, PyObject *sep, Py_ssize_t maxsplit)`980981*Возвращаемое значение: новая ссылка.*982983Разделяет строку и возвращает список строк Unicode. Если *sep* равен *NULL*, разделение происходит по всем подстрокам из пробельных символов. В противном случае разделение выполняется по указанному разделителю. Выполняется не более *maxsplit* разделений. Если значение отрицательное, ограничение не устанавливается. Разделители не включаются в результирующий список.984985#### `PyObject* PyUnicode_Splitlines(PyObject *s, int keepend)`986987*Возвращаемое значение: новая ссылка.*988989Разделяет строку Unicode по символам перевода строки и возвращает список строк Unicode. CRLF считается одним переносом строки. Если *keepend* равно `0`, символы перевода строки не включаются в результирующие строки.990991#### `PyObject* PyUnicode_Translate(PyObject *str, PyObject *table, const char *errors)`992993Переводит строку, применяя к ней таблицу отображения символов, и возвращает результирующий объект Unicode.994995Таблица отображения должна отображать целые числа – кодовые позиции Unicode – в целые числа – кодовые позиции Unicode – или в `None` (вызывает удаление символа).996997Таблицы отображения должны лишь предоставлять интерфейс [`__getitem__()`](https://python-all.ru/3.6/reference/datamodel.html#object.__getitem__); словари и последовательности работают хорошо. Неотображённые кодовые позиции символов (те, которые вызывают [`LookupError`](https://python-all.ru/3.6/library/exceptions.html#LookupError)) остаются нетронутыми и копируются как есть.998999*errors* имеет обычное для кодеков значение. Может быть *NULL*, что означает использование обработки ошибок по умолчанию.10001001#### `PyObject* PyUnicode_Join(PyObject *separator, PyObject *seq)`10021003*Возвращаемое значение: новая ссылка.*10041005Объединяет последовательность строк, используя заданный *разделитель*, и возвращает полученную Unicode-строку.10061007#### `Py_ssize_t PyUnicode_Tailmatch(PyObject *str, PyObject *substr, Py_ssize_t start, Py_ssize_t end, int direction)`10081009Возвращает `1`, если *substr* совпадает с `str[start:end]` на заданном хвосте (*direction* == `-1` означает проверку на совпадение с началом, *direction* == `1` – с концом), иначе `0`. Возвращает `-1`, если произошла ошибка.10101011#### `Py_ssize_t PyUnicode_Find(PyObject *str, PyObject *substr, Py_ssize_t start, Py_ssize_t end, int direction)`10121013Возвращает первую позицию *substr* в `str[start:end]`, используя заданное *direction* (*direction* == `1` означает прямой поиск, *direction* == `-1` – обратный). Возвращаемое значение – индекс первого совпадения; значение `-1` означает, что совпадений не найдено, а `-2` – что произошла ошибка и было установлено исключение.10141015#### `Py_ssize_t PyUnicode_FindChar(PyObject *str, Py_UCS4 ch, Py_ssize_t start, Py_ssize_t end, int direction)`10161017Возвращает первую позицию символа *ch* в `str[start:end]`, используя заданное *direction* (*direction* == `1` означает прямой поиск, *direction* == `-1` – обратный). Возвращаемое значение – индекс первого совпадения; значение `-1` означает, что совпадений не найдено, а `-2` – что произошла ошибка и было установлено исключение.10181019Новое в версии 3.3.10201021#### `Py_ssize_t PyUnicode_Count(PyObject *str, PyObject *substr, Py_ssize_t start, Py_ssize_t end)`10221023Возвращает количество неперекрывающихся вхождений *substr* в `str[start:end]`. Возвращает `-1`, если произошла ошибка.10241025#### `PyObject* PyUnicode_Replace(PyObject *str, PyObject *substr, PyObject *replstr, Py_ssize_t maxcount)`10261027*Возвращаемое значение: новая ссылка.*10281029Заменяет не более *maxcount* вхождений *substr* в *str* на *replstr* и возвращает результирующий объект Unicode. *maxcount* == `-1` означает замену всех вхождений.10301031#### `int PyUnicode_Compare(PyObject *left, PyObject *right)`10321033Сравнивает две строки и возвращает `-1`, `0`, `1` для случаев меньше, равно и больше соответственно.10341035Эта функция возвращает `-1` при ошибке, поэтому для проверки на ошибки следует вызывать [`PyErr_Occurred()`](https://python-all.ru/3.6/c-api/exceptions.html#c.PyErr_Occurred).10361037#### `int PyUnicode_CompareWithASCIIString(PyObject *uni, const char *string)`10381039Сравнивает объект unicode *uni* со строкой *string* и возвращает `-1`, `0`, `1` для меньше, равно и больше соответственно. Рекомендуется передавать только строки в кодировке ASCII, но функция интерпретирует входную строку как ISO-8859-1, если она содержит не-ASCII символы.10401041Эта функция не вызывает исключений.10421043#### `PyObject* PyUnicode_RichCompare(PyObject *left, PyObject *right, int op)`10441045Выполняет расширенное сравнение двух строк unicode и возвращает одно из следующих значений:10461047- `NULL` в случае, если возникло исключение1048- `Py_True` или `Py_False` для успешных сравнений1049- `Py_NotImplemented` в случае, если комбинация типов неизвестна10501051Возможные значения для *op*: `Py_GT`, `Py_GE`, `Py_EQ`, `Py_NE`, `Py_LT` и `Py_LE`.10521053#### `PyObject* PyUnicode_Format(PyObject *format, PyObject *args)`10541055*Возвращаемое значение: новая ссылка.*10561057Возвращает новый строковый объект из *format* и *args*; это аналог `format % args`.10581059#### `int PyUnicode_Contains(PyObject *container, PyObject *element)`10601061Проверяет, содержится ли *element* в *container*, и возвращает true или false соответственно.10621063*Элемент* должен приводиться к одноэлементной строке Unicode. `-1` возвращается при возникновении ошибки.10641065#### `void PyUnicode_InternInPlace(PyObject **string)`10661067Интернирует аргумент *\*string* на месте. Аргумент должен быть адресом переменной-указателя, указывающей на объект строки Unicode Python. Если уже существует интернированная строка, совпадающая с *\*string*, то она устанавливает *\*string* на эту строку (уменьшая счётчик ссылок старого строкового объекта и увеличивая счётчик интернированной строки); в противном случае она оставляет *\*string* без изменений и интернирует её (увеличивая её счётчик ссылок). (Уточнение: хотя много говорится о счётчиках ссылок, считайте эту функцию нейтральной к счётчикам ссылок – вы владеете объектом после вызова, только если владели им до вызова.)10681069#### `PyObject* PyUnicode_InternFromString(const char *v)`10701071Комбинация [`PyUnicode_FromString()`](https://python-all.ru/3.6/c-api/unicode.html#c.PyUnicode_FromString) и [`PyUnicode_InternInPlace()`](https://python-all.ru/3.6/c-api/unicode.html#c.PyUnicode_InternInPlace), возвращающая либо новый объект строки Unicode, который был интернирован, либо новую («принадлежащую») ссылку на более ранний интернированный строковый объект с тем же значением.1072