> **Источник:** https://python-all.ru/2.6/c-api/unicode.html
>
> «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor.

---

# Объекты Unicode и кодеки

## Объекты Unicode

### Тип Unicode

Это основные типы объектов Unicode, используемые в реализации Unicode в Python:

**`Py_UNICODE`**

Этот тип представляет тип хранения, который используется внутри Python в качестве основы для хранения порядковых номеров символов Unicode. В стандартной сборке Python используется 16-битный тип для

[`Py_UNICODE`](https://python-all.ru/2.6/c-api/unicode.html#Py_UNICODE)

, и значения Unicode хранятся внутри в UCS2. Также возможна сборка Python с UCS4 (большинство современных дистрибутивов Linux поставляются с UCS4-сборками Python). В таких сборках используется 32-битный тип для

[`Py_UNICODE`](https://python-all.ru/2.6/c-api/unicode.html#Py_UNICODE)

, и данные Unicode хранятся внутри в UCS4. На платформах, где

`wchar_t`

доступен и совместим с выбранным вариантом сборки Unicode Python,

[`Py_UNICODE`](https://python-all.ru/2.6/c-api/unicode.html#Py_UNICODE)

является псевдонимом typedef для

`wchar_t`

для улучшения совместимости с нативной платформой. На всех остальных платформах

[`Py_UNICODE`](https://python-all.ru/2.6/c-api/unicode.html#Py_UNICODE)

является псевдонимом typedef для

`unsigned short`

(UCS2) или

`unsigned long`

(UCS4).

Обратите внимание, что сборки Python с UCS2 и UCS4 не являются двоично совместимыми. Учитывайте это при написании расширений или интерфейсов.

**`PyUnicodeObject`**

Этот подтип

[`PyObject`](https://python-all.ru/2.6/c-api/structures.html#PyObject)

представляет объект Unicode в Python.

**[PyTypeObject](https://python-all.ru/2.6/c-api/type.html#PyTypeObject) `PyUnicode_Type`**

Этот экземпляр

[`PyTypeObject`](https://python-all.ru/2.6/c-api/type.html#PyTypeObject)

представляет тип Python Unicode. Он доступен из кода Python как

`unicode`

и

`types.UnicodeType`

.

Следующие API на самом деле являются макросами C и могут использоваться для быстрых проверок и доступа к внутренним данным Unicode объектов только для чтения:

**int `PyUnicode_Check`([PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject) *\*o*)**

Возвращает true, если объект *o* является объектом Unicode или экземпляром подтипа Unicode.

Изменено в версии 2.2: Теперь допускаются подтипы.

**int `PyUnicode_CheckExact`([PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject) *\*o*)**

Возвращает true, если объект *o* является объектом Unicode, но не экземпляром подтипа.

Новое в версии 2.2.

**Py\_ssize\_t `PyUnicode_GET_SIZE`([PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject) *\*o*)**

Возвращает размер объекта. *o* должен быть [`PyUnicodeObject`](https://python-all.ru/2.6/c-api/unicode.html#PyUnicodeObject) (не проверяется).

Изменено в версии 2.5:Эта функция возвращала тип `int`. Это может потребовать изменений в вашем коде для корректной поддержки 64-битных систем.

**Py\_ssize\_t `PyUnicode_GET_DATA_SIZE`([PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject) *\*o*)**

Возвращает размер внутреннего буфера объекта в байтах. *o* должен быть [`PyUnicodeObject`](https://python-all.ru/2.6/c-api/unicode.html#PyUnicodeObject) (не проверяется).

Изменено в версии 2.5:Эта функция возвращала тип `int`. Это может потребовать изменений в вашем коде для корректной поддержки 64-битных систем.

**[Py\_UNICODE](https://python-all.ru/2.6/c-api/unicode.html#Py_UNICODE)\* `PyUnicode_AS_UNICODE`([PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject) *\*o*)**

Возвращает указатель на внутренний буфер

[`Py_UNICODE`](https://python-all.ru/2.6/c-api/unicode.html#Py_UNICODE)

объекта.

*o*

должен быть

[`PyUnicodeObject`](https://python-all.ru/2.6/c-api/unicode.html#PyUnicodeObject)

(не проверяется).

**const char\* `PyUnicode_AS_DATA`([PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject) *\*o*)**

Возвращает указатель на внутренний буфер объекта.

*o*

должен быть

[`PyUnicodeObject`](https://python-all.ru/2.6/c-api/unicode.html#PyUnicodeObject)

(не проверяется).

**int `PyUnicode_ClearFreeList`()**

Очищает список свободных элементов. Возвращает общее количество освобождённых элементов.

Новое в версии 2.6.

### Свойства символов Unicode

Unicode предоставляет множество различных свойств символов. Наиболее востребованные из них доступны через следующие макросы, которые сопоставляются с функциями на C в зависимости от конфигурации Python.

**int `Py_UNICODE_ISSPACE`([Py\_UNICODE](https://python-all.ru/2.6/c-api/unicode.html#Py_UNICODE) *ch*)**

Возвращает 1 или 0 в зависимости от того, является ли

*ch*

пробельным символом.

**int `Py_UNICODE_ISLOWER`([Py\_UNICODE](https://python-all.ru/2.6/c-api/unicode.html#Py_UNICODE) *ch*)**

Возвращает 1 или 0 в зависимости от того, является ли

*ch*

символом нижнего регистра.

**int `Py_UNICODE_ISUPPER`([Py\_UNICODE](https://python-all.ru/2.6/c-api/unicode.html#Py_UNICODE) *ch*)**

Возвращает 1 или 0 в зависимости от того, является ли

*ch*

символом верхнего регистра.

**int `Py_UNICODE_ISTITLE`([Py\_UNICODE](https://python-all.ru/2.6/c-api/unicode.html#Py_UNICODE) *ch*)**

Возвращает 1 или 0 в зависимости от того, является ли

*ch*

символом в регистре заголовка.

**int `Py_UNICODE_ISLINEBREAK`([Py\_UNICODE](https://python-all.ru/2.6/c-api/unicode.html#Py_UNICODE) *ch*)**

Возвращает 1 или 0 в зависимости от того, является ли

*ch*

символом разрыва строки.

**int `Py_UNICODE_ISDECIMAL`([Py\_UNICODE](https://python-all.ru/2.6/c-api/unicode.html#Py_UNICODE) *ch*)**

Возвращает 1 или 0 в зависимости от того, является ли

*ch*

десятичной цифрой.

**int `Py_UNICODE_ISDIGIT`([Py\_UNICODE](https://python-all.ru/2.6/c-api/unicode.html#Py_UNICODE) *ch*)**

Возвращает 1 или 0 в зависимости от того, является ли

*ch*

цифровым символом.

**int `Py_UNICODE_ISNUMERIC`([Py\_UNICODE](https://python-all.ru/2.6/c-api/unicode.html#Py_UNICODE) *ch*)**

Возвращает 1 или 0 в зависимости от того, является ли

*ch*

числовым символом.

**int `Py_UNICODE_ISALPHA`([Py\_UNICODE](https://python-all.ru/2.6/c-api/unicode.html#Py_UNICODE) *ch*)**

Возвращает 1 или 0 в зависимости от того, является ли

*ch*

буквенным символом.

**int `Py_UNICODE_ISALNUM`([Py\_UNICODE](https://python-all.ru/2.6/c-api/unicode.html#Py_UNICODE) *ch*)**

Возвращает 1 или 0 в зависимости от того, является ли

*ch*

буквенно-цифровым символом.

Эти API можно использовать для быстрых прямых преобразований символов:

**[Py\_UNICODE](https://python-all.ru/2.6/c-api/unicode.html#Py_UNICODE) `Py_UNICODE_TOLOWER`([Py\_UNICODE](https://python-all.ru/2.6/c-api/unicode.html#Py_UNICODE) *ch*)**

Возвращает символ

*ch*

, преобразованный в нижний регистр.

**[Py\_UNICODE](https://python-all.ru/2.6/c-api/unicode.html#Py_UNICODE) `Py_UNICODE_TOUPPER`([Py\_UNICODE](https://python-all.ru/2.6/c-api/unicode.html#Py_UNICODE) *ch*)**

Возвращает символ

*ch*

, преобразованный в верхний регистр.

**[Py\_UNICODE](https://python-all.ru/2.6/c-api/unicode.html#Py_UNICODE) `Py_UNICODE_TOTITLE`([Py\_UNICODE](https://python-all.ru/2.6/c-api/unicode.html#Py_UNICODE) *ch*)**

Возвращает символ

*ch*

, приведённый к регистру заголовка.

**int `Py_UNICODE_TODECIMAL`([Py\_UNICODE](https://python-all.ru/2.6/c-api/unicode.html#Py_UNICODE) *ch*)**

Возвращает символ

*ch*

, преобразованный в десятичное положительное целое. Возвращает

`-1`

, если это невозможно. Этот макрос не вызывает исключений.

**int `Py_UNICODE_TODIGIT`([Py\_UNICODE](https://python-all.ru/2.6/c-api/unicode.html#Py_UNICODE) *ch*)**

Возвращает символ

*ch*

, преобразованный в целое однозначное число. Возвращает

`-1`

, если это невозможно. Этот макрос не вызывает исключений.

**double `Py_UNICODE_TONUMERIC`([Py\_UNICODE](https://python-all.ru/2.6/c-api/unicode.html#Py_UNICODE) *ch*)**

Возвращает символ

*ch*

, преобразованный в double. Возвращает

`-1.0`

, если это невозможно. Этот макрос не вызывает исключений.

### Простой Py\_UNICODE

Для создания объектов Unicode и доступа к их базовым свойствам последовательности используйте следующие API:

**[PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject)\* `PyUnicode_FromUnicode`(const [Py\_UNICODE](https://python-all.ru/2.6/c-api/unicode.html#Py_UNICODE) *\*u*, Py\_ssize\_t *size*)**

*Возвращаемое значение: новая ссылка.*

Создаёт объект Unicode из буфера Py\_UNICODE *u* заданного размера. *u* может быть *NULL*, что делает содержимое неопределённым. Пользователь сам отвечает за заполнение нужных данных. Буфер копируется в новый объект. Если буфер не равен *NULL*, возвращаемое значение может быть общим объектом. Поэтому изменять полученный объект Unicode разрешается только когда *u* равен *NULL*.

Изменено в версии 2.5: Раньше эта функция использовала тип `int` для *size*. Это может потребовать изменений в вашем коде для корректной поддержки 64-битных систем.

**[Py\_UNICODE](https://python-all.ru/2.6/c-api/unicode.html#Py_UNICODE)\* `PyUnicode_AsUnicode`([PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject) *\*unicode*)**

Возвращает указатель только для чтения на внутренний буфер

[`Py_UNICODE`](https://python-all.ru/2.6/c-api/unicode.html#Py_UNICODE)

объекта Unicode;

*NULL*

, если

*unicode*

не является объектом Unicode.

**Py\_ssize\_t `PyUnicode_GetSize`([PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject) *\*unicode*)**

Возвращает длину объекта Unicode.

Изменено в версии 2.5: эта функция возвращала тип `int`. Возможно, потребуется изменить код для корректной поддержки 64-битных систем.

**[PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject)\* `PyUnicode_FromEncodedObject`([PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject) *\*obj*, const char *\*encoding*, const char *\*errors*)**

*Возвращаемое значение: новая ссылка.*

Преобразует закодированный объект *obj* в объект Unicode и возвращает ссылку с увеличенным счётчиком ссылок.

Строки и другие объекты, совместимые с символьными буферами, декодируются в соответствии с заданной кодировкой и с использованием обработки ошибок, определённой параметром errors. Оба параметра могут быть *NULL*, чтобы интерфейс использовал значения по умолчанию (подробнее см. следующий раздел).

Все остальные объекты, включая объекты Unicode, вызывают установку [`TypeError`](https://python-all.ru/2.6/library/exceptions.html#exceptions.TypeError).

API возвращает *NULL* при ошибке. Вызывающий отвечает за уменьшение счётчика ссылок возвращённых объектов.

**[PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject)\* `PyUnicode_FromObject`([PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject) *\*obj*)**

*Возвращаемое значение: новая ссылка.*

Shortcut for `PyUnicode_FromEncodedObject(obj, NULL, "strict")` which is used throughout the interpreter whenever coercion to Unicode is needed.

Если платформа поддерживает `wchar_t` и предоставляет заголовочный файл wchar.h, Python может напрямую взаимодействовать с этим типом с помощью следующих функций. Поддержка оптимизируется, если собственный тип [`Py_UNICODE`](https://python-all.ru/2.6/c-api/unicode.html#Py_UNICODE) Python идентичен системному `wchar_t`.

### Поддержка wchar\_t

wchar\_t support for platforms which support it:

**[PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject)\* `PyUnicode_FromWideChar`(const wchar\_t *\*w*, Py\_ssize\_t *size*)**

*Возвращаемое значение: новая ссылка.*

Создаёт объект Unicode из буфера `wchar_t` *w* заданного размера. Возвращает *NULL* в случае ошибки.

Изменено в версии 2.5: Раньше эта функция использовала тип `int` для *size*. Это может потребовать изменений в вашем коде для корректной поддержки 64-битных систем.

**Py\_ssize\_t `PyUnicode_AsWideChar`([PyUnicodeObject](https://python-all.ru/2.6/c-api/unicode.html#PyUnicodeObject) *\*unicode*, wchar\_t *\*w*, Py\_ssize\_t *size*)**

Копирует содержимое объекта Unicode в буфер `wchar_t` *w*. Копируется не более *size* символов `wchar_t` (возможный завершающий нулевой символ не учитывается). Возвращает количество скопированных символов `wchar_t` или -1 в случае ошибки. Обратите внимание: результирующая строка `wchar_t` может как содержать, так и не содержать завершающий нулевой символ. Вызывающий должен убедиться, что строка `wchar_t` заканчивается нулевым символом, если это требуется приложению.

Изменено в версии 2.5: эта функция возвращала тип `int` и использовала тип `int` для *size*. Возможно, потребуется изменить код для корректной поддержки 64-битных систем.

## Встроенные кодеки

Python предоставляет набор встроенных кодеков, написанных на C для скорости. Все эти кодеки могут использоваться напрямую через следующие функции.

Многие из следующих API принимают два аргумента: encoding и errors. Эти параметры имеют ту же семантику, что и одноимённые параметры встроенного конструктора объекта Unicode [`unicode()`](https://python-all.ru/2.6/library/functions.html#unicode).

Установка encoding в *NULL* приводит к использованию кодировки по умолчанию, которой является ASCII. Системные вызовы для работы с файлами должны использовать `Py_FileSystemDefaultEncoding` в качестве кодировки для имён файлов. Эту переменную следует считать доступной только для чтения: на одних системах это указатель на статическую строку, на других она может изменяться во время выполнения (например, когда приложение вызывает setlocale).

Обработка ошибок задаётся параметром errors, который также может быть установлен в *NULL*, что означает использование обработки по умолчанию, определённой для кодера. Обработка ошибок по умолчанию для всех встроенных кодеров – «strict» (возбуждается [`ValueError`](https://python-all.ru/2.6/library/exceptions.html#exceptions.ValueError)).

Все кодеки используют похожий интерфейс. Для простоты документированы только отклонения от следующего общего описания.

### Общие кодеки

Это общие API кодеков:

**[PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject)\* `PyUnicode_Decode`(const char *\*s*, Py\_ssize\_t *size*, const char *\*encoding*, const char *\*errors*)**

*Возвращаемое значение: новая ссылка.*

Создаёт объект Unicode, декодируя *size* байт закодированной строки *s*. Параметры *encoding* и *errors* имеют тот же смысл, что и одноимённые параметры встроенной функции [`unicode()`](https://python-all.ru/2.6/library/functions.html#unicode). Используемый кодек находится через реестр кодеков Python. Возвращает *NULL*, если кодек возбудил исключение.

Изменено в версии 2.5: Раньше эта функция использовала тип `int` для *size*. Это может потребовать изменений в вашем коде для корректной поддержки 64-битных систем.

**[PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject)\* `PyUnicode_Encode`(const [Py\_UNICODE](https://python-all.ru/2.6/c-api/unicode.html#Py_UNICODE) *\*s*, Py\_ssize\_t *size*, const char *\*encoding*, const char *\*errors*)**

*Возвращаемое значение: новая ссылка.*

Кодирует буфер [`Py_UNICODE`](https://python-all.ru/2.6/c-api/unicode.html#Py_UNICODE) указанного размера и возвращает объект строки Python. Параметры *encoding* и *errors* имеют тот же смысл, что и одноимённые параметры метода Unicode `encode()`. Используемый кодек ищется в реестре кодеков Python. Возвращает *NULL*, если кодек возбудил исключение.

Изменено в версии 2.5: Раньше эта функция использовала тип `int` для *size*. Это может потребовать изменений в вашем коде для корректной поддержки 64-битных систем.

**[PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject)\* `PyUnicode_AsEncodedString`([PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject) *\*unicode*, const char *\*encoding*, const char *\*errors*)**

*Возвращаемое значение: новая ссылка.*

Кодирует объект Unicode и возвращает результат в виде строки Python. Параметры *encoding* и *errors* имеют тот же смысл, что и одноимённые параметры метода Unicode `encode()`. Используемый кодек ищется в реестре кодеков Python. Возвращает *NULL*, если кодек возбудил исключение.

### Кодеки UTF-8

Это API кодеков UTF-8:

**[PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject)\* `PyUnicode_DecodeUTF8`(const char *\*s*, Py\_ssize\_t *size*, const char *\*errors*)**

*Возвращаемое значение: новая ссылка.*

Создаёт объект Unicode путём декодирования *size* байт строки, закодированной в UTF-8, *s*. Возвращает *NULL*, если кодек возбудил исключение.

Изменено в версии 2.5: Раньше эта функция использовала тип `int` для *size*. Это может потребовать изменений в вашем коде для корректной поддержки 64-битных систем.

**[PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject)\* `PyUnicode_DecodeUTF8Stateful`(const char *\*s*, Py\_ssize\_t *size*, const char *\*errors*, Py\_ssize\_t *\*consumed*)**

*Возвращаемое значение: новая ссылка.*

Если *consumed* равно *NULL*, ведёт себя как [`PyUnicode_DecodeUTF8()`](https://python-all.ru/2.6/c-api/unicode.html#PyUnicode_DecodeUTF8). Если *consumed* не равно *NULL*, завершающие неполные последовательности байт UTF-8 не будут считаться ошибкой. Эти байты не будут декодированы, а количество декодированных байт будет сохранено в *consumed*.

Новое в версии 2.4.

Изменено в версии 2.5: Раньше эта функция использовала тип `int` для *size*. Это может потребовать изменений в вашем коде для корректной поддержки 64-битных систем.

**[PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject)\* `PyUnicode_EncodeUTF8`(const [Py\_UNICODE](https://python-all.ru/2.6/c-api/unicode.html#Py_UNICODE) *\*s*, Py\_ssize\_t *size*, const char *\*errors*)**

*Возвращаемое значение: новая ссылка.*

Кодирует буфер [`Py_UNICODE`](https://python-all.ru/2.6/c-api/unicode.html#Py_UNICODE) указанного размера с использованием UTF-8 и возвращает объект строки Python. Возвращает *NULL*, если кодек возбудил исключение.

Изменено в версии 2.5: Раньше эта функция использовала тип `int` для *size*. Это может потребовать изменений в вашем коде для корректной поддержки 64-битных систем.

**[PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject)\* `PyUnicode_AsUTF8String`([PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject) *\*unicode*)**

*Возвращаемое значение: новая ссылка.*

Кодирует объект Unicode с использованием UTF-8 и возвращает результат в виде строки Python. Обработка ошибок – «strict». Возвращает *NULL*, если кодек возбудил исключение.

### Кодеки UTF-32

Это API кодеков UTF-32:

**[PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject)\* `PyUnicode_DecodeUTF32`(const char *\*s*, Py\_ssize\_t *size*, const char *\*errors*, int *\*byteorder*)**

Декодирует *length* байт из строки буфера, закодированной в UTF-32, и возвращает соответствующий объект Unicode. Параметр *errors* (если не *NULL*) определяет обработку ошибок. По умолчанию – «strict».

Если *byteorder* не равен *NULL*, декодер начинает декодирование с использованием заданного порядка байтов:

```c
*byteorder == -1: little endian
*byteorder == 0:  native order
*byteorder == 1:  big endian
```

Если `*byteorder` равен нулю, и первые четыре байта входных данных являются маркером порядка байт (BOM), декодер переключается на этот порядок байт, и BOM не копируется в результирующую строку Unicode. Если `*byteorder` равен `-1` или `1`, любой маркер порядка байт копируется в выходные данные.

После завершения *\*byteorder* устанавливается в текущий порядок байтов в конце входных данных.

В сборке с узким представлением кодовые точки за пределами BMP будут декодироваться как суррогатные пары.

Если *byteorder* равен *NULL*, кодек запускается в режиме собственного порядка байтов.

Возвращает *NULL*, если кодек сгенерировал исключение.

Новое в версии 2.6.

**[PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject)\* `PyUnicode_DecodeUTF32Stateful`(const char *\*s*, Py\_ssize\_t *size*, const char *\*errors*, int *\*byteorder*, Py\_ssize\_t *\*consumed*)**

Если *consumed* равен *NULL*, ведёт себя как [`PyUnicode_DecodeUTF32()`](https://python-all.ru/2.6/c-api/unicode.html#PyUnicode_DecodeUTF32). Если *consumed* не равен *NULL*, [`PyUnicode_DecodeUTF32Stateful()`](https://python-all.ru/2.6/c-api/unicode.html#PyUnicode_DecodeUTF32Stateful) не будет считать неполные конечные последовательности байтов UTF-32 (например, количество байтов, не кратное четырём) ошибкой. Эти байты не будут декодированы, а количество декодированных байтов будет сохранено в *consumed*.

Новое в версии 2.6.

**[PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject)\* `PyUnicode_EncodeUTF32`(const [Py\_UNICODE](https://python-all.ru/2.6/c-api/unicode.html#Py_UNICODE) *\*s*, Py\_ssize\_t *size*, const char *\*errors*, int *byteorder*)**

Возвращает объект Python bytes, содержащий значение Unicode-данных из *s*, закодированное в UTF-32. Вывод записывается в соответствии со следующим порядком байтов:

```c
byteorder == -1: little endian
byteorder == 0:  native byte order (writes a BOM mark)
byteorder == 1:  big endian
```

Если `0`, выходная строка всегда начинается с метки BOM Unicode (U+FEFF). В двух других режимах метка BOM не добавляется.

Если *Py\_UNICODE\_WIDE* не определён, суррогатные пары будут выводиться как одна кодовая точка.

Возвращает *NULL*, если кодек сгенерировал исключение.

Новое в версии 2.6.

**[PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject)\* `PyUnicode_AsUTF32String`([PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject) *\*unicode*)**

Возвращает строку Python, закодированную в UTF-32 с native порядком байтов. Строка всегда начинается с маркера BOM. Обработка ошибок – «strict». Возвращает *NULL*, если кодек вызвал исключение.

Новое в версии 2.6.

### Кодеки UTF-32

Это API кодеков UTF-32:

**[PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject)\* `PyUnicode_DecodeUTF16`(const char *\*s*, Py\_ssize\_t *size*, const char *\*errors*, int *\*byteorder*)**

*Возвращаемое значение: новая ссылка.*

Декодирует *length* байт из строки буфера, закодированной в UTF-16, и возвращает соответствующий объект Unicode. *errors* (если не *NULL*) задаёт обработку ошибок. По умолчанию – «strict».

Если *byteorder* не равен *NULL*, декодер начинает декодирование с использованием заданного порядка байтов:

```c
*byteorder == -1: little endian
*byteorder == 0:  native order
*byteorder == 1:  big endian
```

Если `*byteorder` равен нулю и первые два байта входных данных являются меткой порядка байтов (BOM), декодер переключается на этот порядок байтов, и BOM не копируется в результирующую строку Unicode. Если `*byteorder` равен `-1` или `1`, любая метка порядка байтов копируется в выходные данные (в результате чего появится символ `\ufeff` или `\ufffe`).

После завершения *\*byteorder* устанавливается в текущий порядок байтов в конце входных данных.

Если *byteorder* равен *NULL*, кодек запускается в режиме собственного порядка байтов.

Возвращает *NULL*, если кодек сгенерировал исключение.

Изменено в версии 2.5: Раньше эта функция использовала тип `int` для *size*. Это может потребовать изменений в вашем коде для корректной поддержки 64-битных систем.

**[PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject)\* `PyUnicode_DecodeUTF16Stateful`(const char *\*s*, Py\_ssize\_t *size*, const char *\*errors*, int *\*byteorder*, Py\_ssize\_t *\*consumed*)**

*Возвращаемое значение: новая ссылка.*

Если *consumed* равен *NULL*, ведёт себя как [`PyUnicode_DecodeUTF16()`](https://python-all.ru/2.6/c-api/unicode.html#PyUnicode_DecodeUTF16). Если *consumed* не равен *NULL*, [`PyUnicode_DecodeUTF16Stateful()`](https://python-all.ru/2.6/c-api/unicode.html#PyUnicode_DecodeUTF16Stateful) не будет считать неполные конечные последовательности байтов UTF-16 (например, нечётное количество байтов или разбитая суррогатная пара) ошибкой. Эти байты не будут декодированы, а количество декодированных байтов будет сохранено в *consumed*.

Новое в версии 2.4.

Изменено в версии 2.5: эта функция использовала тип `int` для *size* и тип `int *` для *consumed*. Возможно, потребуется изменить код для корректной поддержки 64-битных систем.

**[PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject)\* `PyUnicode_EncodeUTF16`(const [Py\_UNICODE](https://python-all.ru/2.6/c-api/unicode.html#Py_UNICODE) *\*s*, Py\_ssize\_t *size*, const char *\*errors*, int *byteorder*)**

*Возвращаемое значение: новая ссылка.*

Возвращает объект строки Python, содержащий значение в кодировке UTF-16 для данных Unicode в *s*. Вывод записывается в следующем порядке байтов:

```c
byteorder == -1: little endian
byteorder == 0:  native byte order (writes a BOM mark)
byteorder == 1:  big endian
```

Если `0`, выходная строка всегда начинается с метки BOM Unicode (U+FEFF). В двух других режимах метка BOM не добавляется.

Если *Py\_UNICODE\_WIDE* определён, одно значение [`Py_UNICODE`](https://python-all.ru/2.6/c-api/unicode.html#Py_UNICODE) может быть представлено как суррогатная пара. Если он не определён, каждое значение [`Py_UNICODE`](https://python-all.ru/2.6/c-api/unicode.html#Py_UNICODE) интерпретируется как символ UCS-2.

Возвращает *NULL*, если кодек сгенерировал исключение.

Изменено в версии 2.5: Раньше эта функция использовала тип `int` для *size*. Это может потребовать изменений в вашем коде для корректной поддержки 64-битных систем.

**[PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject)\* `PyUnicode_AsUTF16String`([PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject) *\*unicode*)**

*Возвращаемое значение: новая ссылка.*

Возвращает строку Python, закодированную в UTF-16 с native порядком байтов. Строка всегда начинается с маркера BOM. Обработка ошибок – «strict». Возвращает *NULL*, если кодек вызвал исключение.

### Кодеки UTF-7

Это API кодеков UTF-7:

**[PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject)\* `PyUnicode_DecodeUTF7`(const char *\*s*, Py\_ssize\_t *size*, const char *\*errors*)**

Создаёт объект Unicode путём декодирования

*size*

байт строки в кодировке UTF-7

*s*

. Возвращает

*NULL*

, если кодек сгенерировал исключение.

**[PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject)\* `PyUnicode_DecodeUTF8Stateful`(const char *\*s*, Py\_ssize\_t *size*, const char *\*errors*, Py\_ssize\_t *\*consumed*)**

Если

*consumed*

равен

*NULL*

, ведёт себя как

[`PyUnicode_DecodeUTF7()`](https://python-all.ru/2.6/c-api/unicode.html#PyUnicode_DecodeUTF7)

. Если

*consumed*

не равен

*NULL*

, конечные неполные секции base-64 UTF-7 не будут считаться ошибкой. Эти байты не будут декодированы, а количество декодированных байтов будет сохранено в

*consumed*

.

**[PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject)\* `PyUnicode_EncodeUTF7`(const [Py\_UNICODE](https://python-all.ru/2.6/c-api/unicode.html#Py_UNICODE) *\*s*, Py\_ssize\_t *size*, int *base64SetO*, int *base64WhiteSpace*, const char *\*errors*)**

Кодирует буфер [`Py_UNICODE`](https://python-all.ru/2.6/c-api/unicode.html#Py_UNICODE) заданного размера с использованием UTF-7 и возвращает объект Python bytes. Возвращает *NULL*, если кодек вызвал исключение.

Если *base64SetO* не равно нулю, «Set O» (знаки препинания, не имеющие иного особого значения) будут закодированы в base-64. Если *base64WhiteSpace* не равно нулю, пробельные символы будут закодированы в base-64. Оба параметра установлены в ноль для кодека Python «utf-7».

### Кодеки Unicode-Escape

Это API кодеков «Unicode Escape»:

**[PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject)\* `PyUnicode_DecodeUnicodeEscape`(const char *\*s*, Py\_ssize\_t *size*, const char *\*errors*)**

*Возвращаемое значение: новая ссылка.*

Создаёт объект Unicode путём декодирования *size* байт строки в кодировке Unicode-Escape *s*. Возвращает *NULL*, если кодек сгенерировал исключение.

Изменено в версии 2.5: Раньше эта функция использовала тип `int` для *size*. Это может потребовать изменений в вашем коде для корректной поддержки 64-битных систем.

**[PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject)\* `PyUnicode_EncodeUnicodeEscape`(const [Py\_UNICODE](https://python-all.ru/2.6/c-api/unicode.html#Py_UNICODE) *\*s*, Py\_ssize\_t *size*)**

*Возвращаемое значение: новая ссылка.*

Кодирует буфер [`Py_UNICODE`](https://python-all.ru/2.6/c-api/unicode.html#Py_UNICODE) заданного размера с использованием Unicode-Escape и возвращает объект строки Python. Возвращает *NULL*, если кодек вызвал исключение.

Изменено в версии 2.5: Раньше эта функция использовала тип `int` для *size*. Это может потребовать изменений в вашем коде для корректной поддержки 64-битных систем.

**[PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject)\* `PyUnicode_AsUnicodeEscapeString`([PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject) *\*unicode*)**

*Возвращаемое значение: новая ссылка.*

Кодирует объект Unicode с использованием Unicode-Escape и возвращает результат в виде строкового объекта Python. Обработка ошибок – «strict». Возвращает *NULL*, если кодек вызвал исключение.

### Кодеки Raw-Unicode-Escape

Это API кодеков «Raw Unicode Escape»:

**[PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject)\* `PyUnicode_DecodeRawUnicodeEscape`(const char *\*s*, Py\_ssize\_t *size*, const char *\*errors*)**

*Возвращаемое значение: новая ссылка.*

Создаёт объект Unicode путём декодирования *size* байт строки *s*, закодированной в Raw-Unicode-Escape. Возвращает *NULL*, если кодек вызвал исключение.

Изменено в версии 2.5: Раньше эта функция использовала тип `int` для *size*. Это может потребовать изменений в вашем коде для корректной поддержки 64-битных систем.

**[PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject)\* `PyUnicode_EncodeRawUnicodeEscape`(const [Py\_UNICODE](https://python-all.ru/2.6/c-api/unicode.html#Py_UNICODE) *\*s*, Py\_ssize\_t *size*, const char *\*errors*)**

*Возвращаемое значение: новая ссылка.*

Кодирует буфер [`Py_UNICODE`](https://python-all.ru/2.6/c-api/unicode.html#Py_UNICODE) заданного размера с помощью Raw-Unicode-Escape и возвращает строковый объект Python. Возвращает *NULL*, если кодек вызвал исключение.

Изменено в версии 2.5: Раньше эта функция использовала тип `int` для *size*. Это может потребовать изменений в вашем коде для корректной поддержки 64-битных систем.

**[PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject)\* `PyUnicode_AsRawUnicodeEscapeString`([PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject) *\*unicode*)**

*Возвращаемое значение: новая ссылка.*

Кодирует объект Unicode с использованием Raw-Unicode-Escape и возвращает результат в виде строкового объекта Python. Обработка ошибок – «strict». Возвращает *NULL*, если кодек вызвал исключение.

### Кодеки Latin-1

Это API кодеков Latin-1: Latin-1 соответствует первым 256 кодовым позициям Unicode, и только они принимаются кодеками при кодировании.

**[PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject)\* `PyUnicode_DecodeLatin1`(const char *\*s*, Py\_ssize\_t *size*, const char *\*errors*)**

*Возвращаемое значение: новая ссылка.*

Создаёт объект Unicode путём декодирования *size* байт строки *s*, закодированной в Latin-1. Возвращает *NULL*, если кодек вызвал исключение.

Изменено в версии 2.5: Раньше эта функция использовала тип `int` для *size*. Это может потребовать изменений в вашем коде для корректной поддержки 64-битных систем.

**[PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject)\* `PyUnicode_EncodeLatin1`(const [Py\_UNICODE](https://python-all.ru/2.6/c-api/unicode.html#Py_UNICODE) *\*s*, Py\_ssize\_t *size*, const char *\*errors*)**

*Возвращаемое значение: новая ссылка.*

Кодирует буфер [`Py_UNICODE`](https://python-all.ru/2.6/c-api/unicode.html#Py_UNICODE) заданного размера с помощью Latin-1 и возвращает строковый объект Python. Возвращает *NULL*, если кодек вызвал исключение.

Изменено в версии 2.5: Раньше эта функция использовала тип `int` для *size*. Это может потребовать изменений в вашем коде для корректной поддержки 64-битных систем.

**[PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject)\* `PyUnicode_AsLatin1String`([PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject) *\*unicode*)**

*Возвращаемое значение: новая ссылка.*

Кодирует объект Unicode с помощью Latin-1 и возвращает результат в виде строкового объекта Python. Обработка ошибок – «strict». Возвращает *NULL*, если кодек вызвал исключение.

### Кодеки ASCII

Это API кодеков ASCII. Принимаются только 7-битные данные ASCII. Все остальные коды вызывают ошибки.

**[PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject)\* `PyUnicode_DecodeASCII`(const char *\*s*, Py\_ssize\_t *size*, const char *\*errors*)**

*Возвращаемое значение: новая ссылка.*

Создаёт объект Unicode путём декодирования *size* байт строки *s*, закодированной в ASCII. Возвращает *NULL*, если кодек вызвал исключение.

Изменено в версии 2.5: Раньше эта функция использовала тип `int` для *size*. Это может потребовать изменений в вашем коде для корректной поддержки 64-битных систем.

**[PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject)\* `PyUnicode_EncodeASCII`(const [Py\_UNICODE](https://python-all.ru/2.6/c-api/unicode.html#Py_UNICODE) *\*s*, Py\_ssize\_t *size*, const char *\*errors*)**

*Возвращаемое значение: новая ссылка.*

Кодирует буфер [`Py_UNICODE`](https://python-all.ru/2.6/c-api/unicode.html#Py_UNICODE) заданного размера с помощью ASCII и возвращает строковый объект Python. Возвращает *NULL*, если кодек вызвал исключение.

Изменено в версии 2.5: Раньше эта функция использовала тип `int` для *size*. Это может потребовать изменений в вашем коде для корректной поддержки 64-битных систем.

**[PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject)\* `PyUnicode_AsASCIIString`([PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject) *\*unicode*)**

*Возвращаемое значение: новая ссылка.*

Кодирует объект Unicode с помощью ASCII и возвращает результат в виде строкового объекта Python. Обработка ошибок – «strict». Возвращает *NULL*, если кодек вызвал исключение.

### Кодеки с таблицей символов

Это API кодеков отображения:

Этот кодек особенный, так как его можно использовать для реализации множества разных кодеков (именно так и были получены большинство стандартных кодеков, входящих в пакет `encodings`). Кодек использует отображение для кодирования и декодирования символов.

Отображения для декодирования должны сопоставлять отдельные строковые символы отдельным символам Unicode, целым числам (которые затем интерпретируются как кодовые точки Unicode) или None (что означает «неопределённое отображение» и вызывает ошибку).

Отображения для кодирования должны сопоставлять отдельные символы Unicode отдельным строковым символам, целым числам (которые затем интерпретируются как кодовые точки Latin-1) или None (что означает «неопределённое отображение» и вызывает ошибку).

Объекты отображения должны поддерживать только интерфейс отображения \_\_getitem\_\_.

Если при поиске символа возникает LookupError, символ копируется как есть; это означает, что его порядковое значение будет интерпретироваться как кодовая точка Unicode или Latin-1 соответственно. Из-за этого отображения должны содержать только те соответствия, которые переводят символы в другие кодовые точки.

**[PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject)\* `PyUnicode_DecodeCharmap`(const char *\*s*, Py\_ssize\_t *size*, [PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject) *\*mapping*, const char *\*errors*)**

*Возвращаемое значение: новая ссылка.*

Создаёт объект Unicode, декодируя *size* байт закодированной строки *s* с помощью заданного объекта *mapping*. Возвращает *NULL*, если кодек вызвал исключение. Если *mapping* равен *NULL*, выполняется декодирование Latin-1. В противном случае это может быть словарь, отображающий байты, или строка Unicode, которая интерпретируется как таблица поиска. Значения байтов, превышающие длину строки, и «символ» U+FFFE считаются «неопределённым отображением».

Изменено в версии 2.4: Разрешена строка Unicode в качестве аргумента отображения.

Изменено в версии 2.5: Раньше эта функция использовала тип `int` для *size*. Это может потребовать изменений в вашем коде для корректной поддержки 64-битных систем.

**[PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject)\* `PyUnicode_EncodeCharmap`(const [Py\_UNICODE](https://python-all.ru/2.6/c-api/unicode.html#Py_UNICODE) *\*s*, Py\_ssize\_t *size*, [PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject) *\*mapping*, const char *\*errors*)**

*Возвращаемое значение: новая ссылка.*

Кодирует буфер [`Py_UNICODE`](https://python-all.ru/2.6/c-api/unicode.html#Py_UNICODE) заданного размера, используя заданный *mapping* объект, и возвращает объект строки Python. Возвращает *NULL*, если кодек вызвал исключение.

Изменено в версии 2.5: Раньше эта функция использовала тип `int` для *size*. Это может потребовать изменений в вашем коде для корректной поддержки 64-битных систем.

**[PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject)\* `PyUnicode_AsCharmapString`([PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject) *\*unicode*, [PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject) *\*mapping*)**

*Возвращаемое значение: новая ссылка.*

Кодирует объект Unicode с помощью заданного объекта *mapping* и возвращает результат в виде строкового объекта Python. Обработка ошибок – «strict». Возвращает *NULL*, если кодек вызвал исключение.

Следующее API кодека особенное тем, что отображает Unicode в Unicode.

**[PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject)\* `PyUnicode_TranslateCharmap`(const [Py\_UNICODE](https://python-all.ru/2.6/c-api/unicode.html#Py_UNICODE) *\*s*, Py\_ssize\_t *size*, [PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject) *\*table*, const char *\*errors*)**

*Возвращаемое значение: новая ссылка.*

Преобразует буфер [`Py_UNICODE`](https://python-all.ru/2.6/c-api/unicode.html#Py_UNICODE) заданной длины, применяя к нему таблицу символов *table*, и возвращает полученный объект Unicode. Возвращает *NULL*, когда кодек вызвал исключение.

Таблица *mapping* должна сопоставлять целочисленные кодовые точки Unicode целочисленным кодовым точкам Unicode или None (что приводит к удалению символа).

Таблицам отображения достаточно реализовать интерфейс [`__getitem__()`](https://python-all.ru/2.6/reference/datamodel.html#object.__getitem__); словари и последовательности подходят. Неотображённые коды символов (те, которые вызывают [`LookupError`](https://python-all.ru/2.6/library/exceptions.html#exceptions.LookupError)) остаются без изменений и копируются как есть.

Изменено в версии 2.5: Раньше эта функция использовала тип `int` для *size*. Это может потребовать изменений в вашем коде для корректной поддержки 64-битных систем.

Это API кодеков MBCS. В настоящее время они доступны только в Windows и используют преобразователи Win32 MBCS для выполнения преобразований. Обратите внимание, что MBCS (или DBCS) – это класс кодировок, а не одна конкретная. Целевая кодировка определяется пользовательскими настройками на машине, где выполняется кодек.

### Кодеки MBCS для Windows

**[PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject)\* `PyUnicode_DecodeMBCS`(const char *\*s*, Py\_ssize\_t *size*, const char *\*errors*)**

*Возвращаемое значение: новая ссылка.*

Создаёт объект Unicode, декодируя *size* байтов строки, закодированной в MBCS, из *s*. Возвращает *NULL*, если кодек вызвал исключение.

Изменено в версии 2.5: Раньше эта функция использовала тип `int` для *size*. Это может потребовать изменений в вашем коде для корректной поддержки 64-битных систем.

**[PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject)\* `PyUnicode_DecodeMBCSStateful`(const char *\*s*, int *size*, const char *\*errors*, int *\*consumed*)**

Если *consumed* равен *NULL*, ведёт себя как [`PyUnicode_DecodeMBCS()`](https://python-all.ru/2.6/c-api/unicode.html#PyUnicode_DecodeMBCS). Если *consumed* не равен *NULL*, то [`PyUnicode_DecodeMBCSStateful()`](https://python-all.ru/2.6/c-api/unicode.html#PyUnicode_DecodeMBCSStateful) не будет декодировать конечный ведущий байт, а количество декодированных байтов будет сохранено в *consumed*.

Новое в версии 2.5.

**[PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject)\* `PyUnicode_EncodeMBCS`(const [Py\_UNICODE](https://python-all.ru/2.6/c-api/unicode.html#Py_UNICODE) *\*s*, Py\_ssize\_t *size*, const char *\*errors*)**

*Возвращаемое значение: новая ссылка.*

Кодирует буфер [`Py_UNICODE`](https://python-all.ru/2.6/c-api/unicode.html#Py_UNICODE) заданного размера, используя MBCS, и возвращает объект строки Python. Возвращает *NULL*, если кодек вызвал исключение.

Изменено в версии 2.5: Раньше эта функция использовала тип `int` для *size*. Это может потребовать изменений в вашем коде для корректной поддержки 64-битных систем.

**[PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject)\* `PyUnicode_AsMBCSString`([PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject) *\*unicode*)**

*Возвращаемое значение: новая ссылка.*

Кодирует объект Unicode, используя MBCS, и возвращает результат в виде объекта строки Python. Обработка ошибок – «strict». Возвращает *NULL*, если кодек вызвал исключение.

### Методы и слоты

## Методы и слот-функции

Следующие API могут обрабатывать объекты Unicode и строки на входе (в описаниях мы называем их строками) и возвращают объекты Unicode или целые числа по необходимости.

Все они возвращают *NULL* или `-1` в случае исключения.

**[PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject)\* `PyUnicode_Concat`([PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject) *\*left*, [PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject) *\*right*)**

*Возвращаемое значение: новая ссылка.*

Объединяет две строки, возвращая новую строку Unicode.

**[PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject)\* `PyUnicode_Split`([PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject) *\*s*, [PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject) *\*sep*, Py\_ssize\_t *maxsplit*)**

*Возвращаемое значение: новая ссылка.*

Разделяет строку, возвращая список строк Unicode. Если sep равно *NULL*, разделение происходит по всем подстрокам пробельных символов. В противном случае разделение происходит по заданному разделителю. Будет выполнено не более *maxsplit* разделений. Если отрицательное, ограничение не устанавливается. Разделители не включаются в результирующий список.

Изменено в версии 2.5: Эта функция использовала тип `int` для *maxsplit*. Это может потребовать изменений в вашем коде для корректной поддержки 64-битных систем.

**[PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject)\* `PyUnicode_Splitlines`([PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject) *\*s*, int *keepend*)**

*Возвращаемое значение: новая ссылка.*

Разделяет строку Unicode по символам перевода строки и возвращает список строк Unicode. CRLF считается одним переносом строки. Если *keepend* равен 0, символы перевода строки не включаются в результирующие строки.

**[PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject)\* `PyUnicode_Translate`([PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject) *\*str*, [PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject) *\*table*, const char *\*errors*)**

*Возвращаемое значение: новая ссылка.*

Переводит строку, применяя к ней таблицу отображения символов, и возвращает результирующий объект Unicode.

Таблица отображения должна сопоставлять целочисленные коды Unicode другим целочисленным кодам Unicode или None (что приводит к удалению символа).

Таблицам отображения достаточно реализовать интерфейс [`__getitem__()`](https://python-all.ru/2.6/reference/datamodel.html#object.__getitem__); словари и последовательности подходят. Неотображённые коды символов (те, которые вызывают [`LookupError`](https://python-all.ru/2.6/library/exceptions.html#exceptions.LookupError)) остаются без изменений и копируются как есть.

*errors* имеет обычное для кодеков значение. Может быть *NULL*, что означает использование обработки ошибок по умолчанию.

**[PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject)\* `PyUnicode_Join`([PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject) *\*separator*, [PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject) *\*seq*)**

*Возвращаемое значение: новая ссылка.*

Объединяет последовательность строк, используя заданный разделитель, и возвращает полученную строку Unicode.

**int `PyUnicode_Tailmatch`([PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject) *\*str*, [PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject) *\*substr*, Py\_ssize\_t *start*, Py\_ssize\_t *end*, int *direction*)**

Возвращает 1, если *substr* совпадает с *str\[\*start*:*end*\] на заданном конце (*direction* == -1 означает поиск префикса, *direction* == 1 – поиск суффикса), и 0 в противном случае. Возвращает `-1`, если произошла ошибка.

Изменено в версии 2.5: Эта функция использовала тип `int` для *start* и *end*. Это может потребовать изменений в вашем коде для корректной поддержки 64-битных систем.

**Py\_ssize\_t `PyUnicode_Find`([PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject) *\*str*, [PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject) *\*substr*, Py\_ssize\_t *start*, Py\_ssize\_t *end*, int *direction*)**

Возвращает первую позицию *substr* в *str\[\*start*:*end*\], используя заданное *direction* (*direction* == 1 означает прямой поиск, *direction* == -1 – обратный поиск). Возвращаемое значение – индекс первого совпадения; значение `-1` указывает, что совпадение не найдено, а `-2` указывает, что произошла ошибка и было установлено исключение.

Изменено в версии 2.5: Эта функция использовала тип `int` для *start* и *end*. Это может потребовать изменений в вашем коде для корректной поддержки 64-битных систем.

**Py\_ssize\_t `PyUnicode_Count`([PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject) *\*str*, [PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject) *\*substr*, Py\_ssize\_t *start*, Py\_ssize\_t *end*)**

Возвращает количество непересекающихся вхождений *substr* в `str[start:end]`. Возвращает `-1`, если произошла ошибка.

Изменено в версии 2.5: Эта функция возвращала тип `int` и использовала тип `int` для *start* и *end*. Это может потребовать изменений в вашем коде для корректной поддержки 64-битных систем.

**[PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject)\* `PyUnicode_Replace`([PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject) *\*str*, [PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject) *\*substr*, [PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject) *\*replstr*, Py\_ssize\_t *maxcount*)**

*Возвращаемое значение: новая ссылка.*

Заменяет не более *maxcount* вхождений *substr* в *str* на *replstr* и возвращает результирующий объект Unicode. *maxcount* == -1 означает замену всех вхождений.

Изменено в версии 2.5: Эта функция использовала тип `int` для *maxcount*. Это может потребовать изменений в вашем коде для корректной поддержки 64-битных систем.

**int `PyUnicode_Compare`([PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject) *\*left*, [PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject) *\*right*)**

Сравнивает две строки и возвращает -1, 0, 1 для случаев «меньше», «равно» и «больше» соответственно.

**int `PyUnicode_RichCompare`([PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject) *\*left*, [PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject) *\*right*, int *op*)**

Выполняет расширенное сравнение двух строк unicode и возвращает одно из следующих значений:

- `NULL` в случае возбуждения исключения
- [`Py_True`](https://python-all.ru/2.6/c-api/bool.html#Py_True) или [`Py_False`](https://python-all.ru/2.6/c-api/bool.html#Py_False) для успешных сравнений
- `Py_NotImplemented` в случае, если комбинация типов неизвестна

Обратите внимание, что сравнения с `Py_EQ` и `Py_NE` могут вызвать [`UnicodeWarning`](https://python-all.ru/2.6/library/exceptions.html#exceptions.UnicodeWarning), если преобразование аргументов в Unicode завершится ошибкой с [`UnicodeDecodeError`](https://python-all.ru/2.6/library/exceptions.html#exceptions.UnicodeDecodeError).

Возможные значения для *op*: `Py_GT`, `Py_GE`, `Py_EQ`, `Py_NE`, `Py_LT` и `Py_LE`.

**[PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject)\* `PyUnicode_Format`([PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject) *\*format*, [PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject) *\*args*)**

*Возвращаемое значение: новая ссылка.*

Возвращает новый строковый объект из *format* и *args*; это аналогично `format % args`. Аргумент *args* должен быть кортежем.

**int `PyUnicode_Contains`([PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject) *\*container*, [PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject) *\*element*)**

Проверяет, содержится ли *element* в *container*, и возвращает true или false соответственно.

*element* должен преобразовываться в односимвольную строку Unicode. Если произошла ошибка, возвращается `-1`.