Объекты и кодеки Юникода¶
Объекты Юникода¶
Начиная с реализации PEP 393 в Python 3.3, объекты Unicode внутри используют различные представления, чтобы обеспечить работу с полным диапазоном символов Unicode и при этом не занимать много памяти. Существуют специальные случаи для строк, когда все кодовые точки меньше 128, 256 или 65536; в противном случае кодовые точки должны быть меньше 1114112 (это полный диапазон Unicode).
Представление UTF-8 создается по требованию и кэшируется в объекте Unicode.
Примечание
Представление Py_UNICODE
было удалено из Python 3.12 вместе с устаревшими API. Для получения дополнительной информации смотрите PEP 623.
Тип Юникода¶
Это основные типы объектов Unicode, используемые для реализации Unicode в Python:
-
type Py_UCS4¶
-
type Py_UCS2¶
-
type Py_UCS1¶
- Часть Стабильный ABI.
Эти типы являются типизациями для беззнаковых целых типов, достаточно широких, чтобы содержать символы размером 32 бита, 16 бит и 8 бит соответственно. При работе с одиночными символами Юникода используйте
Py_UCS4
.Added in version 3.3.
-
type Py_UNICODE¶
Это типизация
wchar_t
, которая является 16-битным или 32-битным типом в зависимости от платформы.Изменено в версии 3.3: В предыдущих версиях это был 16-битный или 32-битный тип в зависимости от того, какую версию Python вы выбрали при сборке - «узкую» или «широкую» Unicode.
Утратил актуальность с версии 3.13, будет удален в версии 3.15.
-
type PyASCIIObject¶
-
type PyCompactUnicodeObject¶
-
type PyUnicodeObject¶
Эти подтипы
PyObject
представляют объект Python Unicode. Почти во всех случаях их не следует использовать напрямую, поскольку все функции API, работающие с объектами Unicode, принимают и возвращают указателиPyObject
.Added in version 3.3.
-
PyTypeObject PyUnicode_Type¶
- Часть Стабильный ABI.
Этот экземпляр
PyTypeObject
представляет тип Python Unicode. В коде Python он отображается какstr
.
Следующие API представляют собой макросы и статические встроенные функции языка C для быстрых проверок и доступа к внутренним данным объектов Unicode, доступным только для чтения:
-
int PyUnicode_Check(PyObject *obj)¶
Возвращает true, если объект obj является объектом Unicode или экземпляром подтипа Unicode. Эта функция всегда работает успешно.
-
int PyUnicode_CheckExact(PyObject *obj)¶
Возвращает true, если объект obj является объектом Unicode, но не является экземпляром подтипа. Эта функция всегда работает успешно.
-
int PyUnicode_READY(PyObject *unicode)¶
Возвращает
0
. Этот API сохраняется только для обратной совместимости.Added in version 3.3.
Не рекомендуется, начиная с версии 3.10: Этот API ничего не делает, начиная с версии Python 3.12.
-
Py_ssize_t PyUnicode_GET_LENGTH(PyObject *unicode)¶
Возвращает длину строки Unicode в кодовых точках. unicode должен быть объектом Unicode в «каноническом» представлении (не проверяется).
Added in version 3.3.
-
Py_UCS1 *PyUnicode_1BYTE_DATA(PyObject *unicode)¶
-
Py_UCS2 *PyUnicode_2BYTE_DATA(PyObject *unicode)¶
-
Py_UCS4 *PyUnicode_4BYTE_DATA(PyObject *unicode)¶
Возвращает указатель на каноническое представление, приведенное к целочисленным типам UCS1, UCS2 или UCS4 для прямого доступа к символам. Проверка на то, что каноническое представление имеет правильный размер символа, не выполняется; используйте
PyUnicode_KIND()
для выбора нужной функции.Added in version 3.3.
-
PyUnicode_1BYTE_KIND¶
-
PyUnicode_2BYTE_KIND¶
-
PyUnicode_4BYTE_KIND¶
Возвращаемые значения макроса
PyUnicode_KIND()
.Added in version 3.3.
Изменено в версии 3.12:
PyUnicode_WCHAR_KIND
был удален.
-
int PyUnicode_KIND(PyObject *unicode)¶
Возвращает одну из констант вида PyUnicode (см. выше), которая указывает, сколько байт на символ использует этот объект Unicode для хранения своих данных. unicode должен быть объектом Unicode в «каноническом» представлении (не проверяется).
Added in version 3.3.
-
void *PyUnicode_DATA(PyObject *unicode)¶
Возвращает указатель void на необработанный буфер Unicode. unicode должен быть объектом Unicode в «каноническом» представлении (не проверяется).
Added in version 3.3.
-
void PyUnicode_WRITE(int kind, void *data, Py_ssize_t index, Py_UCS4 value)¶
Запись в каноническое представление данных (как получено с помощью
PyUnicode_DATA()
). Эта функция не выполняет никаких проверок на правильность и предназначена для использования в циклах. Вызывающая сторона должна кэшировать значение kind и указатель data, полученные при других вызовах. index - это индекс в строке (начинается с 0), а value - новое значение кодовой точки, которое должно быть записано в это место.Added in version 3.3.
-
Py_UCS4 PyUnicode_READ(int kind, void *data, Py_ssize_t index)¶
Считывание кодовой точки из канонического представления data (как получено с помощью
PyUnicode_DATA()
). Никаких проверок или вызовов готовности не выполняется.Added in version 3.3.
-
Py_UCS4 PyUnicode_READ_CHAR(PyObject *unicode, Py_ssize_t index)¶
Считывание символа из объекта Unicode unicode, который должен быть в «каноническом» представлении. Это менее эффективно, чем
PyUnicode_READ()
, если вы выполняете несколько последовательных считываний.Added in version 3.3.
-
Py_UCS4 PyUnicode_MAX_CHAR_VALUE(PyObject *unicode)¶
Возвращает максимальную точку кода, которая подходит для создания другой строки на основе unicode, которая должна быть в «каноническом» представлении. Это всегда приближение, но более эффективное, чем итерация по строке.
Added in version 3.3.
-
int PyUnicode_IsIdentifier(PyObject *unicode)¶
- Часть Стабильный ABI.
Верните
1
, если строка является допустимым идентификатором в соответствии с определением языка, раздел Идентификаторы и ключевые слова. В противном случае возвращается0
.Изменено в версии 3.9: Функция больше не вызывает
Py_FatalError()
, если строка не готова.
Свойства символов Юникода¶
Unicode предоставляет множество различных свойств символов. Наиболее часто необходимые из них доступны через эти макросы, которые отображаются на функции C в зависимости от конфигурации Python.
-
int Py_UNICODE_ISSPACE(Py_UCS4 ch)¶
Возвращает
1
или0
в зависимости от того, является ли ch символом пробела.
-
int Py_UNICODE_ISLOWER(Py_UCS4 ch)¶
Возвращает
1
или0
в зависимости от того, является ли ch строчным символом.
-
int Py_UNICODE_ISUPPER(Py_UCS4 ch)¶
Возвращает
1
или0
в зависимости от того, является ли ch прописным символом.
-
int Py_UNICODE_ISTITLE(Py_UCS4 ch)¶
Возвращает
1
или0
в зависимости от того, является ли ch символом заглавной буквы.
-
int Py_UNICODE_ISLINEBREAK(Py_UCS4 ch)¶
Возвращает
1
или0
в зависимости от того, является ли ch символом перевода строки.
-
int Py_UNICODE_ISDECIMAL(Py_UCS4 ch)¶
Возвращает
1
или0
в зависимости от того, является ли ch десятичным символом.
-
int Py_UNICODE_ISDIGIT(Py_UCS4 ch)¶
Возвращает
1
или0
в зависимости от того, является ли ch цифровым символом.
-
int Py_UNICODE_ISNUMERIC(Py_UCS4 ch)¶
Возвращает
1
или0
в зависимости от того, является ли ch числовым символом.
-
int Py_UNICODE_ISALPHA(Py_UCS4 ch)¶
Возвращает
1
или0
в зависимости от того, является ли ch алфавитным символом.
-
int Py_UNICODE_ISALNUM(Py_UCS4 ch)¶
Возвращает
1
или0
в зависимости от того, является ли ch буквенно-цифровым символом.
-
int Py_UNICODE_ISPRINTABLE(Py_UCS4 ch)¶
Возвращает
1
или0
в зависимости от того, является ли ch печатаемым символом. Непечатаемые символы - это символы, определенные в базе данных символов Unicode как «Другие» или «Разделитель», за исключением ASCII-пробела (0x20), который считается печатаемым. (Обратите внимание, что печатаемые символы в данном контексте - это те, которые не должны экранироваться при вызовеrepr()
в строке. Это никак не влияет на обработку строк, записанных вsys.stdout
илиsys.stderr
).
Эти API можно использовать для быстрого прямого преобразования символов:
-
int Py_UNICODE_TODECIMAL(Py_UCS4 ch)¶
Возвращает символ ch, преобразованный в десятичное положительное целое число. Верните
-1
, если это невозможно. Эта функция не вызывает исключений.
-
int Py_UNICODE_TODIGIT(Py_UCS4 ch)¶
Возвращает символ ch, преобразованный в одноразрядное целое число. Верните
-1
, если это невозможно. Эта функция не вызывает исключений.
-
double Py_UNICODE_TONUMERIC(Py_UCS4 ch)¶
Возвращает символ ch, преобразованный в двойное число. Верните
-1.0
, если это невозможно. Эта функция не вызывает исключений.
Эти API можно использовать для работы с суррогатами:
-
int Py_UNICODE_IS_SURROGATE(Py_UCS4 ch)¶
Проверьте, является ли ch суррогатом (
0xD800 <= ch <= 0xDFFF
).
-
int Py_UNICODE_IS_HIGH_SURROGATE(Py_UCS4 ch)¶
Проверьте, является ли ch суррогатом высокого уровня (
0xD800 <= ch <= 0xDBFF
).
-
int Py_UNICODE_IS_LOW_SURROGATE(Py_UCS4 ch)¶
Проверьте, является ли ch суррогатом низкого уровня (
0xDC00 <= ch <= 0xDFFF
).
-
Py_UCS4 Py_UNICODE_JOIN_SURROGATES(Py_UCS4 high, Py_UCS4 low)¶
Объединяет два суррогатных символа и возвращает одно значение
Py_UCS4
. high и low - это соответственно ведущий и последующий суррогаты в паре суррогатов. high должно находиться в диапазоне [0xD800; 0xDBFF], а low - в диапазоне [0xDC00; 0xDFFF].
Создание и доступ к строкам Unicode¶
Чтобы создать объекты Unicode и получить доступ к их основным свойствам последовательности, используйте эти API:
-
PyObject *PyUnicode_New(Py_ssize_t size, Py_UCS4 maxchar)¶
- Возвращаемое значение: Новая ссылка.
Создайте новый объект Unicode. maxchar должно быть истинным максимальным значением кодовой точки, которая будет помещена в строку. В качестве приближения его можно округлить до ближайшего значения в последовательности 127, 255, 65535, 1114111.
Это рекомендуемый способ выделения нового объекта Unicode. Объекты, созданные с помощью этой функции, не могут быть изменены по размеру.
Added in version 3.3.
-
PyObject *PyUnicode_FromKindAndData(int kind, const void *buffer, Py_ssize_t size)¶
- Возвращаемое значение: Новая ссылка.
Создает новый объект Unicode с заданным kind (возможные значения
PyUnicode_1BYTE_KIND
и т.д., как возвращаетсяPyUnicode_KIND()
). Буфер buffer должен указывать на массив size размером 1, 2 или 4 байта на символ, в зависимости от вида.При необходимости входной буфер копируется и преобразуется в каноническое представление. Например, если буфер представляет собой строку UCS4 (
PyUnicode_4BYTE_KIND
) и состоит только из кодовых точек в диапазоне UCS1, он будет преобразован в UCS1 (PyUnicode_1BYTE_KIND
).Added in version 3.3.
-
PyObject *PyUnicode_FromStringAndSize(const char *str, Py_ssize_t size)¶
- Возвращаемое значение: Новая ссылка. Часть Стабильный ABI.
Создайте объект Unicode из буфера символов str. Байты будут интерпретированы как кодированные в UTF-8. Буфер копируется в новый объект. Возвращаемое значение может быть общим объектом, т. е. модификация данных не допускается.
Эта функция поднимает
SystemError
, когда:size < 0,
str равно
NULL
и size > 0
Изменено в версии 3.12: str ==
NULL
с size > 0 больше не допускается.
-
PyObject *PyUnicode_FromString(const char *str)¶
- Возвращаемое значение: Новая ссылка. Часть Стабильный ABI.
Создание объекта Unicode из нуль-терминированного char-буфера str, закодированного в UTF-8.
-
PyObject *PyUnicode_FromFormat(const char *format, ...)¶
- Возвращаемое значение: Новая ссылка. Часть Стабильный ABI.
Принимает строку format в стиле C
printf()
- и переменное количество аргументов, вычисляет размер результирующей строки Python Unicode и возвращает строку с отформатированными в нее значениями. Переменные аргументы должны быть типами C и должны точно соответствовать символам формата в ASCII-кодированной строке format.Спецификатор преобразования содержит два или более символов и состоит из следующих компонентов, которые должны встречаться в указанном порядке:
Символ
'%'
, обозначающий начало спецификатора.Флаги преобразования (необязательно), которые влияют на результат некоторых типов преобразования.
Минимальная ширина поля (необязательно). Если указано
'*'
(звездочка), то фактическая ширина задается в следующем аргументе, который должен иметь тип int, а объект для преобразования идет после минимальной ширины поля и необязательной точности.Точность (необязательно), задается в виде
'.'
(точка), за которой следует точность. Если указано'*'
(звездочка), то фактическая точность задается в следующем аргументе, который должен иметь тип int, а значение для преобразования идет после точности.Модификатор длины (необязательно).
Тип преобразования.
Символы флага преобразования:
Флаг
Значение
0
При преобразовании числовые значения будут обнулены.
-
Преобразованное значение остается скорректированным (отменяет флаг
0
, если заданы оба).Модификаторы длины для следующих целочисленных преобразований (
d
,i
,o
,u
,x
илиX
) определяют тип аргумента (int по умолчанию):Модификатор
Типы
l
long или unsigned long
ll
long long или unsigned long long
j
intmax_t
илиuintmax_t
z
size_t
илиssize_t
t
ptrdiff_t
Модификатор длины
l
для последующих преобразованийs
илиV
указывает, что тип аргумента равен const wchar_t*.Спецификаторами преобразования являются:
Спецификатор преобразования
Тип
Комментарий
%
n/a
Буквальный символ
%
.d
,i
Определяется модификатором длины
Десятичное представление знакового целого числа C.
u
Определяется модификатором длины
Десятичное представление беззнакового целого числа C.
o
Определяется модификатором длины
Восьмеричное представление беззнакового целого числа C.
x
Определяется модификатором длины
Шестнадцатеричное представление беззнакового целого числа C (в нижнем регистре).
X
Определяется модификатором длины
Шестнадцатеричное представление беззнакового целого числа C (в верхнем регистре).
c
int
Одиночный символ.
s
const char* или const wchar_t*
Нуль-терминированный символьный массив на языке C.
p
const void*
Шестнадцатеричное представление указателя в языке C. В основном эквивалентен
printf("%p")
, за исключением того, что гарантированно начинается с литерала0x
, независимо от того, что даетprintf
платформы.A
Результат вызова
ascii()
.U
Объект Unicode.
V
PyObject*, const char* или const wchar_t*
Объект Unicode (который может быть
NULL
) и нуль-терминированный массив символов C в качестве второго параметра (который будет использоваться, если первый параметр равенNULL
).S
Результат вызова
PyObject_Str()
.R
Результат вызова
PyObject_Repr()
.T
Получение полного имени типа объекта; вызов
PyType_GetFullyQualifiedName()
.#T
Аналогичен формату
T
, но в качестве разделителя между именем модуля и квалифицированным именем используется двоеточие (:
).N
Получение полного имени типа; вызов
PyType_GetFullyQualifiedName()
.#N
Аналогичен формату
N
, но в качестве разделителя между именем модуля и квалифицированным именем используется двоеточие (:
).Примечание
Единицей ширины форматера является количество символов, а не байт. Единицей точности является количество байт или элементов
wchar_t
(если используется модификатор длиныl
) для"%s"
и"%V"
(если аргументPyObject*
равенNULL
), и количество символов для"%A"
,"%U"
,"%S"
,"%R"
и"%V"
(если аргументPyObject*
не равенNULL
).Примечание
В отличие от C
printf()
, флаг0
действует даже в том случае, если для целочисленных преобразований задана точность (d
,i
,u
,o
,x
илиX
).Изменено в версии 3.2: Добавлена поддержка
"%lld"
и"%llu"
.Изменено в версии 3.3: Добавлена поддержка
"%li"
,"%lli"
и"%zi"
.Изменено в версии 3.4: Добавлена поддержка ширины и точности форматера для
"%s"
,"%A"
,"%U"
,"%V"
,"%S"
,"%R"
.Изменено в версии 3.12: Поддержка спецификаторов преобразования
o
иX
. Поддержка модификаторов длиныj
иt
. Модификаторы длины теперь применяются ко всем целочисленным преобразованиям. Модификатор длиныl
теперь применяется к спецификаторам преобразованияs
иV
. Поддержка переменной ширины и точности*
. Поддержка флага-
.Нераспознанный символ формата теперь устанавливает
SystemError
. В предыдущих версиях это приводило к тому, что вся остальная часть строки формата копировалась в строку результата как есть, а лишние аргументы отбрасывались.Изменено в версии 3.13: Добавлена поддержка форматов
%T
,%#T
,%N
и%#N
.
-
PyObject *PyUnicode_FromFormatV(const char *format, va_list vargs)¶
- Возвращаемое значение: Новая ссылка. Часть Стабильный ABI.
Идентичен
PyUnicode_FromFormat()
, за исключением того, что принимает ровно два аргумента.
-
PyObject *PyUnicode_FromObject(PyObject *obj)¶
- Возвращаемое значение: Новая ссылка. Часть Стабильный ABI.
При необходимости скопируйте экземпляр подтипа Unicode в новый истинный объект Unicode. Если obj уже является истинным объектом Unicode (не подтипом), верните объекту новый strong reference.
Объекты, отличные от Unicode или его подтипов, приведут к появлению
TypeError
.
-
PyObject *PyUnicode_FromEncodedObject(PyObject *obj, const char *encoding, const char *errors)¶
- Возвращаемое значение: Новая ссылка. Часть Стабильный ABI.
Декодируйте закодированный объект obj в объект Unicode.
bytes
,bytearray
и другие bytes-like objects декодируются в соответствии с заданным кодированием и с использованием обработки ошибок, определенных ошибками. Оба параметра могут бытьNULL
, чтобы интерфейс использовал значения по умолчанию (см. Встроенные кодеки для деталей).Для всех остальных объектов, включая объекты Unicode, устанавливается значение
TypeError
.API возвращает
NULL
, если произошла ошибка. Вызывающая сторона отвечает за уменьшение возвращаемых объектов.
-
Py_ssize_t PyUnicode_GetLength(PyObject *unicode)¶
- Часть Стабильный ABI с версии 3.7.
Возвращает длину объекта Unicode в кодовых точках.
Added in version 3.3.
-
Py_ssize_t PyUnicode_CopyCharacters(PyObject *to, Py_ssize_t to_start, PyObject *from, Py_ssize_t from_start, Py_ssize_t how_many)¶
Копирование символов из одного объекта Unicode в другой. Эта функция выполняет преобразование символов, когда это необходимо, и возвращается к
memcpy()
, если это возможно. Возвращает-1
и устанавливает исключение при ошибке, в противном случае возвращает количество скопированных символов.Added in version 3.3.
-
Py_ssize_t PyUnicode_Fill(PyObject *unicode, Py_ssize_t start, Py_ssize_t length, Py_UCS4 fill_char)¶
Заполните строку символом: запишите fill_char в
unicode[start:start+length]
.Неудача, если fill_char больше, чем максимальный символ строки, или если строка содержит более 1 ссылки.
Возвращает количество записанных символов, либо возвращает
-1
и вызывает исключение при ошибке.Added in version 3.3.
-
int PyUnicode_WriteChar(PyObject *unicode, Py_ssize_t index, Py_UCS4 character)¶
- Часть Стабильный ABI с версии 3.7.
Запись символа в строку. Строка должна быть создана через
PyUnicode_New()
. Поскольку строки Unicode должны быть неизменяемыми, строка не должна быть общей или еще не подвергалась хешированию.Эта функция проверяет, что unicode является объектом Unicode, что индекс не выходит за границы и что объект может быть безопасно изменен (т.е. что количество его ссылок равно единице).
Added in version 3.3.
-
Py_UCS4 PyUnicode_ReadChar(PyObject *unicode, Py_ssize_t index)¶
- Часть Стабильный ABI с версии 3.7.
Считывание символа из строки. Эта функция проверяет, что unicode является объектом Unicode и индекс не выходит за границы, в отличие от
PyUnicode_READ_CHAR()
, которая не выполняет проверку ошибок.Added in version 3.3.
-
PyObject *PyUnicode_Substring(PyObject *unicode, Py_ssize_t start, Py_ssize_t end)¶
- Возвращаемое значение: Новая ссылка. Часть Стабильный ABI с версии 3.7.
Возвращает подстроку unicode, начиная с символьного индекса start (включено) и заканчивая символьным индексом end (исключено). Отрицательные индексы не поддерживаются.
Added in version 3.3.
-
Py_UCS4 *PyUnicode_AsUCS4(PyObject *unicode, Py_UCS4 *buffer, Py_ssize_t buflen, int copy_null)¶
- Часть Стабильный ABI с версии 3.7.
Копирует строку unicode в буфер UCS4, включая нулевой символ, если установлено значение copy_null. Возвращает
NULL
и устанавливает исключение при ошибке (в частности,SystemError
, если buflen меньше длины unicode). При успехе возвращается buffer.Added in version 3.3.
-
Py_UCS4 *PyUnicode_AsUCS4Copy(PyObject *unicode)¶
- Часть Стабильный ABI с версии 3.7.
Скопируйте строку unicode в новый буфер UCS4, выделенный с помощью
PyMem_Malloc()
. Если это не удается, возвращаетсяNULL
с установленнымMemoryError
. В возвращаемый буфер всегда добавляется дополнительная нулевая точка кода.Added in version 3.3.
Кодировка локали¶
Текущая кодировка локали может быть использована для декодирования текста из операционной системы.
-
PyObject *PyUnicode_DecodeLocaleAndSize(const char *str, Py_ssize_t length, const char *errors)¶
- Возвращаемое значение: Новая ссылка. Часть Стабильный ABI с версии 3.7.
Декодируйте строку из UTF-8 на Android и VxWorks или из текущей кодировки локали на других платформах. Поддерживаются следующие обработчики ошибок:
"strict"
и"surrogateescape"
(PEP 383). Декодер использует обработчик ошибок"strict"
, если errors имеет значениеNULL
. str должен заканчиваться нулевым символом, но не может содержать встроенных нулевых символов.Используйте
PyUnicode_DecodeFSDefaultAndSize()
для декодирования строки из filesystem encoding and error handler.Эта функция игнорирует Python UTF-8 Mode.
См.также
Функция
Py_DecodeLocale()
.Added in version 3.3.
Изменено в версии 3.7: Теперь функция также использует текущую кодировку локали для обработчика ошибки
surrogateescape
, кроме Android. Ранее дляsurrogateescape
использовалась кодировкаPy_DecodeLocale()
, а дляstrict
- текущая кодировка локали.
-
PyObject *PyUnicode_DecodeLocale(const char *str, const char *errors)¶
- Возвращаемое значение: Новая ссылка. Часть Стабильный ABI с версии 3.7.
Аналогично
PyUnicode_DecodeLocaleAndSize()
, но длина строки вычисляется с помощьюstrlen()
.Added in version 3.3.
-
PyObject *PyUnicode_EncodeLocale(PyObject *unicode, const char *errors)¶
- Возвращаемое значение: Новая ссылка. Часть Стабильный ABI с версии 3.7.
Перекодируйте объект Unicode в UTF-8 на Android и VxWorks или в текущую кодировку локали на других платформах. Поддерживаются следующие обработчики ошибок:
"strict"
и"surrogateescape"
(PEP 383). Кодер использует обработчик ошибок"strict"
, если значение errors равноNULL
. Возвращается объектbytes
. unicode не может содержать встроенные нулевые символы.Используйте
PyUnicode_EncodeFSDefault()
для кодирования строки в filesystem encoding and error handler.Эта функция игнорирует Python UTF-8 Mode.
См.также
Функция
Py_EncodeLocale()
.Added in version 3.3.
Изменено в версии 3.7: Теперь функция также использует текущую кодировку локали для обработчика ошибки
surrogateescape
, кроме Android. Ранее дляsurrogateescape
использовалась кодировкаPy_EncodeLocale()
, а дляstrict
- текущая кодировка локали.
Кодирование файловой системы¶
Функции кодирования в filesystem encoding and error handler и декодирования из PEP 383 (PEP 383 и PEP 529).
Для кодирования имен файлов в bytes
при разборе аргументов следует использовать конвертер "O&"
, передав в качестве функции преобразования PyUnicode_FSConverter()
:
-
int PyUnicode_FSConverter(PyObject *obj, void *result)¶
- Часть Стабильный ABI.
Конвертер ParseTuple: кодирует объекты
str
- полученные напрямую или через интерфейсos.PathLike
- вbytes
с помощьюPyUnicode_EncodeFSDefault()
; объектыbytes
выводятся как есть. Результатом должен быть PyBytesObject*, который должен быть освобожден, когда он больше не используется.Added in version 3.1.
Изменено в версии 3.6: Принимает path-like object.
Для декодирования имен файлов в str
при разборе аргументов следует использовать конвертер "O&"
, передав в качестве функции преобразования PyUnicode_FSDecoder()
:
-
int PyUnicode_FSDecoder(PyObject *obj, void *result)¶
- Часть Стабильный ABI.
Конвертер ParseTuple: декодирует объекты
bytes
- полученные прямо или косвенно через интерфейсos.PathLike
- вstr
с помощьюPyUnicode_DecodeFSDefaultAndSize()
; объектыstr
выводятся как есть. Результатом должен быть PyUnicodeObject*, который должен быть освобожден, когда он больше не используется.Added in version 3.2.
Изменено в версии 3.6: Принимает path-like object.
-
PyObject *PyUnicode_DecodeFSDefaultAndSize(const char *str, Py_ssize_t size)¶
- Возвращаемое значение: Новая ссылка. Часть Стабильный ABI.
Декодируйте строку из filesystem encoding and error handler.
Если вам нужно декодировать строку из текущей кодировки локали, используйте
PyUnicode_DecodeLocaleAndSize()
.См.также
Функция
Py_DecodeLocale()
.Изменено в версии 3.6: Теперь используется filesystem error handler.
-
PyObject *PyUnicode_DecodeFSDefault(const char *str)¶
- Возвращаемое значение: Новая ссылка. Часть Стабильный ABI.
Декодирование нуль-терминированной строки из filesystem encoding and error handler.
Если длина строки известна, используйте
PyUnicode_DecodeFSDefaultAndSize()
.Изменено в версии 3.6: Теперь используется filesystem error handler.
-
PyObject *PyUnicode_EncodeFSDefault(PyObject *unicode)¶
- Возвращаемое значение: Новая ссылка. Часть Стабильный ABI.
Перекодируйте объект Unicode в filesystem encoding and error handler и верните
bytes
. Обратите внимание, что результирующий объектbytes
может содержать нулевые байты.Если вам нужно перекодировать строку в кодировку текущей локали, используйте
PyUnicode_EncodeLocale()
.См.также
Функция
Py_EncodeLocale()
.Added in version 3.2.
Изменено в версии 3.6: Теперь используется filesystem error handler.
wchar_t Поддержка¶
Поддержка wchar_t
для платформ, которые ее поддерживают:
-
PyObject *PyUnicode_FromWideChar(const wchar_t *wstr, Py_ssize_t size)¶
- Возвращаемое значение: Новая ссылка. Часть Стабильный ABI.
Создает объект Unicode из
wchar_t
буфера wstr заданного размера. Передача-1
в качестве размера указывает на то, что функция должна сама вычислить длину, используяwcslen()
. В случае неудачи возвращаетсяNULL
.
-
Py_ssize_t PyUnicode_AsWideChar(PyObject *unicode, wchar_t *wstr, Py_ssize_t size)¶
- Часть Стабильный ABI.
Скопируйте содержимое объекта Unicode в
wchar_t
буфер wstr. Копируется не более sizewchar_t
символов (за исключением, возможно, идущего в конце нулевого символа завершения). Возвращается количество скопированныхwchar_t
символов или-1
в случае ошибки.Если wstr равно
NULL
, вместо этого верните размер, который потребуется для хранения всего unicode, включая завершающий null.Обратите внимание, что результирующая строка wchar_t* может быть нуль-терминированной, а может и не быть. Ответственность за то, чтобы строка wchar_t* была нуль-терминированной, лежит на вызывающей стороне, если это требуется приложению. Также обратите внимание, что строка wchar_t* может содержать нулевые символы, что приведет к ее усечению при использовании с большинством функций языка Си.
-
wchar_t *PyUnicode_AsWideCharString(PyObject *unicode, Py_ssize_t *size)¶
- Часть Стабильный ABI с версии 3.7.
Преобразование объекта Unicode в широкую символьную строку. Выходная строка всегда заканчивается нулевым символом. Если size не
NULL
, запишите в *size количество широких символов (исключая завершающий нулевой символ). Обратите внимание, что полученная строкаwchar_t
может содержать нулевые символы, что приведет к ее усечению при использовании с большинством функций языка Си. Если size равенNULL
, а строка wchar_t* содержит нулевые символы, то возникает сообщениеValueError
.Возвращает буфер, выделенный
PyMem_New
(используйтеPyMem_Free()
, чтобы освободить его) в случае успеха. При ошибке возвращаетсяNULL
и *size не определен. Вызывает ошибкуMemoryError
, если выделение памяти не удалось.Added in version 3.2.
Изменено в версии 3.7: Вызывает ошибку
ValueError
, если size равенNULL
и строка wchar_t* содержит нулевые символы.
Встроенные кодеки¶
Python предоставляет набор встроенных кодеков, которые для скорости написаны на языке C. Все эти кодеки можно напрямую использовать с помощью следующих функций.
Многие из следующих API принимают два аргумента encoding и errors, и имеют ту же семантику, что и встроенный конструктор строковых объектов str()
.
Установка кодировки в NULL
приводит к использованию кодировки по умолчанию, которая является UTF-8. Вызовы файловой системы должны использовать PyUnicode_FSConverter()
для кодировки имен файлов. Здесь используется внутренняя кодировка filesystem encoding and error handler.
Обработка ошибок задается ошибками, которые также могут быть установлены в значение NULL
, означающее использование обработки по умолчанию, определенной для кодека. Обработка ошибок по умолчанию для всех встроенных кодеков - «строгая» (ValueError
поднимается).
Все кодеки используют схожий интерфейс. Для простоты документируются только отклонения от типового интерфейса.
Общие кодеки¶
Это общие API кодеков:
-
PyObject *PyUnicode_Decode(const char *str, Py_ssize_t size, const char *encoding, const char *errors)¶
- Возвращаемое значение: Новая ссылка. Часть Стабильный ABI.
Создайте объект Unicode, декодировав size байт закодированной строки str. Параметры encoding и errors имеют то же значение, что и одноименные параметры во встроенной функции
str()
. Используемый кодек ищется в реестре кодеков Python. ВозвращаетсяNULL
, если кодек вызвал исключение.
-
PyObject *PyUnicode_AsEncodedString(PyObject *unicode, const char *encoding, const char *errors)¶
- Возвращаемое значение: Новая ссылка. Часть Стабильный ABI.
Кодирует объект Unicode и возвращает результат в виде объекта Python bytes. Параметры encoding и errors имеют то же значение, что и одноименные параметры в методе Unicode
encode()
. Используемый кодек ищется с помощью реестра кодеков Python. ВозвращаетсяNULL
, если кодек вызвал исключение.
Кодеки UTF-8¶
Это API кодеков UTF-8:
-
PyObject *PyUnicode_DecodeUTF8(const char *str, Py_ssize_t size, const char *errors)¶
- Возвращаемое значение: Новая ссылка. Часть Стабильный ABI.
Создайте объект Unicode, декодировав size байт строки str, закодированной в UTF-8. Возвращает
NULL
, если кодек вызвал исключение.
-
PyObject *PyUnicode_DecodeUTF8Stateful(const char *str, Py_ssize_t size, const char *errors, Py_ssize_t *consumed)¶
- Возвращаемое значение: Новая ссылка. Часть Стабильный ABI.
Если consumed равно
NULL
, ведите себя какPyUnicode_DecodeUTF8()
. Если consumed неNULL
, то неполные последовательности байтов UTF-8 не будут рассматриваться как ошибка. Эти байты не будут декодированы, а количество байтов, которые были декодированы, будет сохранено в consumed.
-
PyObject *PyUnicode_AsUTF8String(PyObject *unicode)¶
- Возвращаемое значение: Новая ссылка. Часть Стабильный ABI.
Кодирует объект Unicode с помощью UTF-8 и возвращает результат в виде объекта Python bytes. Обработка ошибок «строгая». Возвращается
NULL
, если кодек вызвал исключение.
-
const char *PyUnicode_AsUTF8AndSize(PyObject *unicode, Py_ssize_t *size)¶
- Часть Стабильный ABI с версии 3.10.
Возвращает указатель на кодировку UTF-8 объекта Unicode и сохраняет размер кодированного представления (в байтах) в size. Аргумент size может быть
NULL
; в этом случае размер не сохраняется. В возвращаемый буфер всегда добавляется дополнительный нулевой байт (не включенный в size), независимо от наличия других нулевых кодовых точек.При ошибке создайте исключение, установите size в
-1
(если он не NULL) и вернитеNULL
.Это кэширует UTF-8-представление строки в объекте Unicode, и последующие вызовы будут возвращать указатель на тот же буфер. Вызывающая сторона не отвечает за деаллокацию буфера. Буфер удаляется, а указатели на него становятся недействительными при сборке мусора в объекте Unicode.
Added in version 3.3.
Изменено в версии 3.7: Тип возврата теперь
const char *
, а неchar *
.Изменено в версии 3.10: Эта функция является частью limited API.
-
const char *PyUnicode_AsUTF8(PyObject *unicode)¶
Как
PyUnicode_AsUTF8AndSize()
, но не хранит размер.Added in version 3.3.
Изменено в версии 3.7: Тип возврата теперь
const char *
, а неchar *
.
Кодеки UTF-32¶
Это API кодеков UTF-32:
-
PyObject *PyUnicode_DecodeUTF32(const char *str, Py_ssize_t size, const char *errors, int *byteorder)¶
- Возвращаемое значение: Новая ссылка. Часть Стабильный ABI.
Декодирует size байт из буферной строки, закодированной в UTF-32, и возвращает соответствующий объект Unicode. errors (если не``NULL``) определяет обработку ошибок. По умолчанию используется значение «strict».
Если byteorder не``NULL``, декодер начинает декодирование, используя заданный порядок байтов:
*byteorder == -1: little endian *byteorder == 0: native order *byteorder == 1: big endian
Если
*byteorder
равен нулю, а первые четыре байта входных данных представляют собой метку порядка байтов (BOM), декодер переключается на этот порядок байтов, и BOM не копируется в результирующую строку Юникода. Если*byteorder
равен-1
или1
, на выход копируется любая метка порядка байтов.После завершения *byteorder устанавливается на текущий порядок байтов в конце входных данных.
Если значение byteorder равно
NULL
, кодек запускается в режиме собственного порядка.Возвращает
NULL
, если кодек вызвал исключение.
-
PyObject *PyUnicode_DecodeUTF32Stateful(const char *str, Py_ssize_t size, const char *errors, int *byteorder, Py_ssize_t *consumed)¶
- Возвращаемое значение: Новая ссылка. Часть Стабильный ABI.
Если consumed равно
NULL
, то ведет себя какPyUnicode_DecodeUTF32()
. Если consumed не равноNULL
, тоPyUnicode_DecodeUTF32Stateful()
не будет рассматривать неполные последовательности байтов UTF-32 (например, количество байтов, не кратное четырем) как ошибку. Эти байты не будут декодированы, а количество байтов, которые были декодированы, будет сохранено в consumed.
-
PyObject *PyUnicode_AsUTF32String(PyObject *unicode)¶
- Возвращаемое значение: Новая ссылка. Часть Стабильный ABI.
Возвращает байтовую строку Python в кодировке UTF-32 в собственном порядке байтов. Строка всегда начинается с метки BOM. Обработка ошибок «строгая». Возвращает
NULL
, если кодек вызвал исключение.
Кодеки UTF-16¶
Это API кодеков UTF-16:
-
PyObject *PyUnicode_DecodeUTF16(const char *str, Py_ssize_t size, const char *errors, int *byteorder)¶
- Возвращаемое значение: Новая ссылка. Часть Стабильный ABI.
Декодирует size байт из буферной строки, закодированной в UTF-16, и возвращает соответствующий объект Unicode. errors (если не``NULL``) определяет обработку ошибок. По умолчанию используется значение «strict».
Если byteorder не``NULL``, декодер начинает декодирование, используя заданный порядок байтов:
*byteorder == -1: little endian *byteorder == 0: native order *byteorder == 1: big endian
Если
*byteorder
равен нулю, а первые два байта входных данных представляют собой метку порядка байтов (BOM), декодер переключается на этот порядок байтов, и BOM не копируется в результирующую строку Юникода. Если*byteorder
равен-1
или1
, любая метка порядка байтов копируется на выход (где в результате получится либо\ufeff
, либо\ufffe
).После завершения
*byteorder
устанавливается в текущий порядок байтов в конце входных данных.Если значение byteorder равно
NULL
, кодек запускается в режиме собственного порядка.Возвращает
NULL
, если кодек вызвал исключение.
-
PyObject *PyUnicode_DecodeUTF16Stateful(const char *str, Py_ssize_t size, const char *errors, int *byteorder, Py_ssize_t *consumed)¶
- Возвращаемое значение: Новая ссылка. Часть Стабильный ABI.
Если consumed равно
NULL
, то ведет себя какPyUnicode_DecodeUTF16()
. Если consumed не равноNULL
, тоPyUnicode_DecodeUTF16Stateful()
не будет рассматривать неполные последовательности байтов UTF-16 (например, нечетное количество байтов или разделенную суррогатную пару) как ошибку. Эти байты не будут декодированы, а количество байтов, которые были декодированы, будет сохранено в consumed.
-
PyObject *PyUnicode_AsUTF16String(PyObject *unicode)¶
- Возвращаемое значение: Новая ссылка. Часть Стабильный ABI.
Возвращает байтовую строку Python в кодировке UTF-16 в собственном порядке байтов. Строка всегда начинается с метки BOM. Обработка ошибок «строгая». Возвращается
NULL
, если кодек вызвал исключение.
Кодеки UTF-7¶
Это API кодеков UTF-7:
-
PyObject *PyUnicode_DecodeUTF7(const char *str, Py_ssize_t size, const char *errors)¶
- Возвращаемое значение: Новая ссылка. Часть Стабильный ABI.
Создает объект Unicode, декодируя size байт строки str, закодированной в UTF-7. Возвращает
NULL
, если кодек вызвал исключение.
-
PyObject *PyUnicode_DecodeUTF7Stateful(const char *str, Py_ssize_t size, const char *errors, Py_ssize_t *consumed)¶
- Возвращаемое значение: Новая ссылка. Часть Стабильный ABI.
Если consumed равно
NULL
, ведите себя какPyUnicode_DecodeUTF7()
. Если consumed неNULL
, то неполные секции UTF-7 base-64 не будут рассматриваться как ошибка. Эти байты не будут декодированы, а количество байтов, которые были декодированы, будет сохранено в consumed.
Кодеки Unicode-Escape¶
Это API кодека «Unicode Escape»:
-
PyObject *PyUnicode_DecodeUnicodeEscape(const char *str, Py_ssize_t size, const char *errors)¶
- Возвращаемое значение: Новая ссылка. Часть Стабильный ABI.
Создает объект Unicode, декодируя size байт строки str, закодированной в Unicode-Escape. Возвращает
NULL
, если кодек вызвал исключение.
-
PyObject *PyUnicode_AsUnicodeEscapeString(PyObject *unicode)¶
- Возвращаемое значение: Новая ссылка. Часть Стабильный ABI.
Закодируйте объект Unicode с помощью Unicode-Escape и верните результат в виде объекта bytes. Обработка ошибок «строгая». Возвращает
NULL
, если кодек вызвал исключение.
Кодеки Raw-Unicode-Escape¶
Это API кодека «Raw Unicode Escape»:
-
PyObject *PyUnicode_DecodeRawUnicodeEscape(const char *str, Py_ssize_t size, const char *errors)¶
- Возвращаемое значение: Новая ссылка. Часть Стабильный ABI.
Создает объект Unicode, декодируя size байт строки str, закодированной в Raw-Unicode-Escape. Возвращает
NULL
, если кодек вызвал исключение.
-
PyObject *PyUnicode_AsRawUnicodeEscapeString(PyObject *unicode)¶
- Возвращаемое значение: Новая ссылка. Часть Стабильный ABI.
Закодируйте объект Unicode с помощью Raw-Unicode-Escape и верните результат в виде объекта bytes. Обработка ошибок «строгая». Возвращает
NULL
, если кодек вызвал исключение.
Кодеки Latin-1¶
Это API-интерфейсы для кодеков Latin-1: Latin-1 соответствует первым 256 ординалам Unicode, и только они принимаются кодеками при кодировании.
-
PyObject *PyUnicode_DecodeLatin1(const char *str, Py_ssize_t size, const char *errors)¶
- Возвращаемое значение: Новая ссылка. Часть Стабильный ABI.
Создайте объект Unicode, декодировав size байт строки str, закодированной в Latin-1. Возвращает
NULL
, если кодек вызвал исключение.
-
PyObject *PyUnicode_AsLatin1String(PyObject *unicode)¶
- Возвращаемое значение: Новая ссылка. Часть Стабильный ABI.
Закодируйте объект Unicode с помощью Latin-1 и верните результат в виде объекта Python bytes. Обработка ошибок «строгая». Возвращается
NULL
, если кодек вызвал исключение.
Кодеки ASCII¶
Это API кодеков ASCII. Принимаются только 7-битные данные ASCII. Все остальные коды приводят к ошибкам.
-
PyObject *PyUnicode_DecodeASCII(const char *str, Py_ssize_t size, const char *errors)¶
- Возвращаемое значение: Новая ссылка. Часть Стабильный ABI.
Создайте объект Unicode, декодировав size байт ASCII-кодированной строки str. Возвращает
NULL
, если кодек вызвал исключение.
-
PyObject *PyUnicode_AsASCIIString(PyObject *unicode)¶
- Возвращаемое значение: Новая ссылка. Часть Стабильный ABI.
Закодируйте объект Unicode с помощью ASCII и верните результат в виде объекта Python bytes. Обработка ошибок «строгая». Возвращает
NULL
, если кодек вызвал исключение.
Кодеки для карт символов¶
Особенность этого кодека в том, что он может быть использован для реализации множества различных кодеков (что, собственно, и было сделано для получения большинства стандартных кодеков, включенных в пакет encodings
). Кодек использует отображения для кодирования и декодирования символов. Предоставляемые объекты отображения должны поддерживать интерфейс отображения __getitem__()
; хорошо работают словари и последовательности.
Это API кодеков отображения:
-
PyObject *PyUnicode_DecodeCharmap(const char *str, Py_ssize_t length, PyObject *mapping, const char *errors)¶
- Возвращаемое значение: Новая ссылка. Часть Стабильный ABI.
Создает объект Unicode, декодируя size байт закодированной строки str с помощью заданного объекта mapping. Возвращает
NULL
, если кодек вызвал исключение.Если mapping равно
NULL
, будет применено декодирование Latin-1. В противном случае mapping должен сопоставлять ординалы байтов (целые числа в диапазоне от 0 до 255) со строками Юникода, целыми числами (которые затем интерпретируются как ординалы Юникода) илиNone
. Не отображенные байты данных - те, которые вызываютLookupError
, а также те, которые отображаются вNone
,0xFFFE
или'\ufffe'
, - рассматриваются как неопределенные отображения и вызывают ошибку.
-
PyObject *PyUnicode_AsCharmapString(PyObject *unicode, PyObject *mapping)¶
- Возвращаемое значение: Новая ссылка. Часть Стабильный ABI.
Кодирует объект Unicode с помощью заданного объекта mapping и возвращает результат в виде объекта bytes. Обработка ошибок «строгая». Возвращает
NULL
, если кодек вызвал исключение.Объект mapping должен отображать целые порядковые числа Unicode на объекты байтов, целые числа в диапазоне от 0 до 255 или
None
. Не отображенные символьные ординалы (те, которые приводят кLookupError
), а также отображенные наNone
рассматриваются как «неопределенное отображение» и вызывают ошибку.
Следующий API кодека отличается тем, что отображает Unicode в Unicode.
-
PyObject *PyUnicode_Translate(PyObject *unicode, PyObject *table, const char *errors)¶
- Возвращаемое значение: Новая ссылка. Часть Стабильный ABI.
Переведите строку, применив к ней таблицу сопоставления символов, и верните полученный объект Unicode. Возвращает
NULL
, если кодек вызвал исключение.Таблица сопоставления должна сопоставлять целые порядковые числа Юникода с целыми порядковыми числами Юникода или
None
(что приводит к удалению символа).Таблицы отображения должны обеспечивать только интерфейс
__getitem__()
; хорошо работают словари и последовательности. Несопоставленные ординалы символов (те, которые вызываютLookupError
) остаются нетронутыми и копируются как есть.errors имеет обычное значение для кодеков. Оно может быть
NULL
, что указывает на использование обработки ошибок по умолчанию.
Кодеки MBCS для Windows¶
Это API-интерфейсы кодеков MBCS. В настоящее время они доступны только в Windows и используют конвертеры Win32 MBCS для осуществления преобразований. Обратите внимание, что MBCS (или DBCS) - это класс кодировок, а не одна. Целевая кодировка определяется настройками пользователя на машине, на которой запущен кодек.
-
PyObject *PyUnicode_DecodeMBCS(const char *str, Py_ssize_t size, const char *errors)¶
- Возвращаемое значение: Новая ссылка. Часть Стабильный ABI on Windows с версии 3.7.
Создайте объект Unicode, декодировав size байт закодированной в MBCS строки str. Возвращает
NULL
, если кодек вызвал исключение.
-
PyObject *PyUnicode_DecodeMBCSStateful(const char *str, Py_ssize_t size, const char *errors, Py_ssize_t *consumed)¶
- Возвращаемое значение: Новая ссылка. Часть Стабильный ABI on Windows с версии 3.7.
Если consumed равно
NULL
, ведите себя какPyUnicode_DecodeMBCS()
. Если consumed неNULL
, тоPyUnicode_DecodeMBCSStateful()
не будет декодировать ведущий байт, а количество байтов, которые были декодированы, будет сохранено в consumed.
-
PyObject *PyUnicode_AsMBCSString(PyObject *unicode)¶
- Возвращаемое значение: Новая ссылка. Часть Стабильный ABI on Windows с версии 3.7.
Закодируйте объект Unicode с помощью MBCS и верните результат в виде объекта Python bytes. Обработка ошибок «строгая». Возвращается
NULL
, если кодек вызвал исключение.
-
PyObject *PyUnicode_EncodeCodePage(int code_page, PyObject *unicode, const char *errors)¶
- Возвращаемое значение: Новая ссылка. Часть Стабильный ABI on Windows с версии 3.7.
Кодирует объект Unicode, используя указанную кодовую страницу, и возвращает объект Python bytes. Верните
NULL
, если кодек вызвал исключение. Используйте кодовую страницуCP_ACP
для получения кодека MBCS.Added in version 3.3.
Методы и слоты¶
Методы и функции слотов¶
Следующие API способны работать с объектами и строками Юникода на входе (в описаниях мы называем их строками) и возвращать объекты Юникода или целые числа в зависимости от ситуации.
Все они возвращают NULL
или -1
при возникновении исключения.
-
PyObject *PyUnicode_Concat(PyObject *left, PyObject *right)¶
- Возвращаемое значение: Новая ссылка. Часть Стабильный ABI.
Конкатенация двух строк с получением новой строки Unicode.
-
PyObject *PyUnicode_Split(PyObject *unicode, PyObject *sep, Py_ssize_t maxsplit)¶
- Возвращаемое значение: Новая ссылка. Часть Стабильный ABI.
Разделяет строку, выдавая список строк Unicode. Если sep равно
NULL
, то разбиение будет производиться по всем пробельным подстрокам. В противном случае разбиение происходит по заданному разделителю. Будет выполнено не более maxsplit разбиений. Если значение отрицательно, то ограничение не устанавливается. Разделители не включаются в результирующий список.
-
PyObject *PyUnicode_Splitlines(PyObject *unicode, int keepends)¶
- Возвращаемое значение: Новая ссылка. Часть Стабильный ABI.
Разделяет строку Unicode на переносы строк, возвращая список строк Unicode. CRLF считается одним переводом строки. Если keepends имеет значение
0
, символы перевода строки не включаются в результирующие строки.
-
PyObject *PyUnicode_Join(PyObject *separator, PyObject *seq)¶
- Возвращаемое значение: Новая ссылка. Часть Стабильный ABI.
Объединяет последовательность строк с помощью заданного разделителя и возвращает результирующую строку Unicode.
-
Py_ssize_t PyUnicode_Tailmatch(PyObject *unicode, PyObject *substr, Py_ssize_t start, Py_ssize_t end, int direction)¶
- Часть Стабильный ABI.
Верните
1
, если substr совпадает сunicode[start:end]
в заданном хвосте (direction ==-1
означает префиксное совпадение, direction ==1
- суффиксное),0
в противном случае. Возвращает-1
, если произошла ошибка.
-
Py_ssize_t PyUnicode_Find(PyObject *unicode, PyObject *substr, Py_ssize_t start, Py_ssize_t end, int direction)¶
- Часть Стабильный ABI.
Возвращает первую позицию substr в
unicode[start:end]
, используя заданное направление (направление ==1
означает прямой поиск, направление ==-1
- обратный поиск). Возвращаемое значение - индекс первого совпадения; значение-1
означает, что совпадение не найдено, а-2
- что произошла ошибка и было задано исключение.
-
Py_ssize_t PyUnicode_FindChar(PyObject *unicode, Py_UCS4 ch, Py_ssize_t start, Py_ssize_t end, int direction)¶
- Часть Стабильный ABI с версии 3.7.
Возвращает первую позицию символа ch в
unicode[start:end]
, используя заданное направление (направление ==1
означает поиск вперед, направление ==-1
- поиск назад). Возвращаемое значение - индекс первого совпадения; значение-1
означает, что совпадение не найдено, а-2
- что произошла ошибка и было задано исключение.Added in version 3.3.
Изменено в версии 3.7: start и end теперь ведут себя как
unicode[start:end]
.
-
Py_ssize_t PyUnicode_Count(PyObject *unicode, PyObject *substr, Py_ssize_t start, Py_ssize_t end)¶
- Часть Стабильный ABI.
Возвращает количество непересекающихся вхождений substr в
unicode[start:end]
. Верните-1
, если произошла ошибка.
-
PyObject *PyUnicode_Replace(PyObject *unicode, PyObject *substr, PyObject *replstr, Py_ssize_t maxcount)¶
- Возвращаемое значение: Новая ссылка. Часть Стабильный ABI.
Заменяет не более maxcount вхождений substr в unicode на replstr и возвращает результирующий объект Unicode. maxcount ==
-1
означает замену всех вхождений.
-
int PyUnicode_Compare(PyObject *left, PyObject *right)¶
- Часть Стабильный ABI.
Сравните две строки и верните
-1
,0
,1
для значений «меньше, чем», «равно» и «больше, чем» соответственно.Эта функция возвращает
-1
в случае неудачи, поэтому для проверки ошибок следует вызыватьPyErr_Occurred()
.
-
int PyUnicode_EqualToUTF8AndSize(PyObject *unicode, const char *string, Py_ssize_t size)¶
- Часть Стабильный ABI с версии 3.13.
Сравните объект Unicode с буфером char, который интерпретируется как кодировка UTF-8 или ASCII, и верните true (
1
), если они равны, или false (0
) в противном случае. Если объект Unicode содержит суррогатные символы или строка C не является правильной UTF-8, возвращается false (0
).Эта функция не вызывает исключений.
Added in version 3.13.
-
int PyUnicode_EqualToUTF8(PyObject *unicode, const char *string)¶
- Часть Стабильный ABI с версии 3.13.
Аналогично
PyUnicode_EqualToUTF8AndSize()
, но вычисляет длину строки с помощьюstrlen()
. Если объект Unicode содержит нулевые символы, возвращается false (0
).Added in version 3.13.
-
int PyUnicode_CompareWithASCIIString(PyObject *unicode, const char *string)¶
- Часть Стабильный ABI.
Сравнивает объект Unicode, unicode, с string и возвращает
-1
,0
,1
для значений меньше, равно и больше, соответственно. Лучше всего передавать только строки в кодировке ASCII, но функция интерпретирует входную строку как ISO-8859-1, если она содержит символы, отличные от ASCII.Эта функция не вызывает исключений.
-
PyObject *PyUnicode_RichCompare(PyObject *left, PyObject *right, int op)¶
- Возвращаемое значение: Новая ссылка. Часть Стабильный ABI.
Rich сравнивает две строки Unicode и возвращает одно из следующих значений:
NULL
в случае, если возникло исключениеPy_NotImplemented
в случае, если комбинация типов неизвестна
Возможные значения для op:
Py_GT
,Py_GE
,Py_EQ
,Py_NE
,Py_LT
иPy_LE
.
-
PyObject *PyUnicode_Format(PyObject *format, PyObject *args)¶
- Возвращаемое значение: Новая ссылка. Часть Стабильный ABI.
Возвращает новый строковый объект из format и args; это аналогично
format % args
.
-
int PyUnicode_Contains(PyObject *unicode, PyObject *substr)¶
- Часть Стабильный ABI.
Проверяет, содержится ли substr в unicode, и возвращает true или false соответственно.
substr должен быть приведен к одноэлементной строке Unicode. Если произошла ошибка, возвращается
-1
.
-
void PyUnicode_InternInPlace(PyObject **p_unicode)¶
- Часть Стабильный ABI.
Вставьте аргумент *p_unicode на место. Аргумент должен быть адресом переменной-указателя, указывающей на строковый объект Python Unicode. Если уже существует интернированная строка, совпадающая с *p_unicode, она устанавливает *p_unicode на нее (освобождая ссылку на старый строковый объект и создавая новый strong reference на интернированный строковый объект), в противном случае она оставляет *p_unicode в покое и интернирует его (создавая новый strong reference). (Пояснение: несмотря на то что много говорят о ссылках, считайте эту функцию нейтральной к ссылкам; вы владеете объектом после вызова, если и только если вы владели им до вызова).
-
PyObject *PyUnicode_InternFromString(const char *str)¶
- Возвращаемое значение: Новая ссылка. Часть Стабильный ABI.
Комбинация
PyUnicode_FromString()
иPyUnicode_InternInPlace()
, возвращающая либо новый строковый объект Unicode, который был интернирован, либо новую («собственную») ссылку на ранее интернированный строковый объект с тем же значением.