Bytes Objects

Эти функции возбуждают TypeError, если ожидается строковый параметр, а вызываются с нестроковым.

Примечание

Эти функции были переименованы в PyBytes_* в Python 3.x. Если не указано иное, функции PyBytes, доступные в 3.x, являются псевдонимами соответствующих функций PyString_* для облегчения переноса.

PyStringObject¶: Этот подтип PyObject представляет Python-строку.

PyTypeObject PyString_Type¶: Этот экземпляр PyTypeObject представляет тип Python-строки; это тот же объект, что и str и types.StringType в Python-слое.

int PyString_Check(PyObject *o)¶

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

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

int PyString_CheckExact(PyObject *o)¶

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

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

PyObject* PyString_FromString(const char *v)¶: Возвращаемое значение: новая ссылка.
Возвращает новый строковый объект, содержащий копию строки v в качестве значения, в случае успеха, и NULL в случае ошибки. Параметр v не должен быть NULL; он не будет проверяться.

PyObject* PyString_FromStringAndSize(const char *v, Py_ssize_t len)¶

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

Возвращает новый строковый объект, содержащий копию строки v с указанным значением и длиной len в случае успеха, и NULL в случае ошибки. Если v равно NULL, содержимое строки не инициализировано.

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

PyObject* PyString_FromFormat(const char *format, ...)¶

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

Принимает строку format в стиле C-функции printf() и переменное число аргументов, вычисляет размер результирующей Python-строки и возвращает строку с отформатированными в неё значениями. Переменные аргументы должны быть типами C и в точности соответствовать символам формата в строке format. Допускаются следующие символы формата:

Символы формата	Тип	Описание
`%%`	н/д	Буквальный символ %.
`%c`	int	Одиночный символ, представленный как C int.
`%d`	int	Полностью эквивалентно `printf("%d")`.
`%u`	беззнаковый int	Полностью эквивалентно `printf("%u")`.
`%ld`	long	Полностью эквивалентно `printf("%ld")`.
`%lu`	беззнаковый long	Полностью эквивалентно `printf("%lu")`.
`%zd`	Py_ssize_t	Полностью эквивалентно `printf("%zd")`.
`%zu`	size_t	Полностью эквивалентно `printf("%zu")`.
`%i`	int	Полностью эквивалентно `printf("%i")`.
`%x`	int	Полностью эквивалентно `printf("%x")`.
`%s`	char*	Нуль-терминированный массив символов C.
`%p`	void*	Шестнадцатеричное представление указателя C. В основном эквивалентно `printf("%p")` за исключением того, что гарантированно начинается с литерала `0x` независимо от того, что выдает `printf` на данной платформе.

Нераспознанный символ формата приводит к тому, что вся оставшаяся строка формата копируется как есть в результирующую строку, а все лишние аргументы отбрасываются.

PyObject* PyString_FromFormatV(const char *format, va_list vargs)¶: Возвращаемое значение: новая ссылка.
Аналогичен PyString_FromFormat(), за исключением того, что принимает ровно два аргумента.

Py_ssize_t PyString_Size(PyObject *string)¶

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

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

Py_ssize_t PyString_GET_SIZE(PyObject *string)¶

Макро-форма PyString_Size(), но без проверки ошибок.

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

char* PyString_AsString(PyObject *string)¶: Возвращает NUL-терминированное представление содержимого string. Указатель ссылается на внутренний буфер string, а не на копию. Данные нельзя изменять никаким образом, если только строка не была только что создана с помощью PyString_FromStringAndSize(NULL, size). Её нельзя освобождать. Если string является объектом Unicode, эта функция вычисляет кодировку по умолчанию для string и работает с ней. Если string вообще не является строковым объектом, PyString_AsString() возвращает NULL и возбуждает TypeError.

char* PyString_AS_STRING(PyObject *string)¶: Макро-форма PyString_AsString(), но без проверки ошибок. Поддерживаются только строковые объекты; объекты Unicode передавать не следует.

int PyString_AsStringAndSize(PyObject *obj, char **buffer, Py_ssize_t *length)¶

Возвращает представление содержимого объекта obj, завершающееся NUL, через выходные переменные buffer и length.

Функция принимает на вход как строковые объекты, так и объекты Unicode. Для объектов Unicode она возвращает версию объекта, закодированную в кодировке по умолчанию. Если length равно NULL, результирующий буфер не может содержать NUL-символы; если они есть, функция возвращает -1 и возбуждается TypeError.

Буфер ссылается на внутренний строковый буфер obj, а не на копию. Данные нельзя изменять никаким образом, если только строка не была только что создана с помощью PyString_FromStringAndSize(NULL, size). Её нельзя освобождать. Если string является объектом Unicode, эта функция вычисляет кодировку по умолчанию для string и работает с ней. Если string вообще не является строковым объектом, PyString_AsStringAndSize() возвращает -1 и возбуждает TypeError.

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

void PyString_Concat(PyObject **string, PyObject *newpart)¶: Создаёт новый строковый объект в *string, содержащий содержимое newpart добавленное к string; вызывающий получает новую ссылку. Ссылка на старое значение string будет украдена. Если новую строку создать не удалось, старая ссылка на string всё равно будет отброшена, а значение *string будет установлено в NULL; будет установлено соответствующее исключение.

void PyString_ConcatAndDel(PyObject **string, PyObject *newpart)¶: Создаёт новый строковый объект в *string, содержащий содержимое newpart добавленное к string. Эта версия уменьшает счётчик ссылок newpart.

int _PyString_Resize(PyObject **string, Py_ssize_t newsize)¶

Способ изменить размер строкового объекта, несмотря на его «неизменяемость». Используйте это только для создания совершенно нового строкового объекта; не используйте, если строка может уже быть известна в других частях кода. Вызов этой функции является ошибкой, если счётчик ссылок на входной строковый объект не равен единице. Передайте адрес существующего строкового объекта как lvalue (в него может быть произведена запись) и новый желаемый размер. В случае успеха *string содержит изменённый строковый объект, и 0 возвращается; адрес в *string может отличаться от исходного. Если перераспределение не удалось, исходный строковый объект по адресу *string освобождается, *string устанавливается в NULL, устанавливается исключение памяти, и -1 возвращается.

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

PyObject* PyString_Format(PyObject *format, PyObject *args)¶: Возвращаемое значение: новая ссылка.
Возвращает новый строковый объект из format и args. Аналог format % args. Аргумент args должен быть кортежем.

void PyString_InternInPlace(PyObject **string)¶: Интернирует аргумент *string на месте. Аргумент должен быть адресом переменной-указателя, указывающей на строковый объект Python. Если уже существует интернированная строка, совпадающая с *string, то *string устанавливается в неё (уменьшая счётчик ссылок старого строкового объекта и увеличивая счётчик ссылок интернированного строкового объекта), в противном случае *string оставляется без изменений и интернируется (увеличивая её счётчик ссылок). (Пояснение: хотя здесь много говорится о счётчиках ссылок, считайте эту функцию нейтральной по отношению к счётчикам ссылок; вы владеете объектом после вызова тогда и только тогда, когда владели им до вызова.)

Примечание

Эта функция недоступна в 3.x и не имеет псевдонима PyBytes.

PyObject* PyString_InternFromString(const char *v)¶: Возвращаемое значение: новая ссылка.
Комбинация PyString_FromString() и PyString_InternInPlace(), возвращающая либо новый строковый объект, который был интернирован, либо новую («владетельную») ссылку на ранее интернированный строковый объект с тем же значением.

Примечание

Эта функция недоступна в 3.x и не имеет псевдонима PyBytes.

PyObject* PyString_Decode(const char *s, Py_ssize_t size, const char *encoding, const char *errors)¶

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

Создаёт объект путём декодирования size байтов закодированного буфера s с помощью кодека, зарегистрированного для encoding. Параметры encoding и errors имеют то же значение, что и одноимённые параметры встроенной функции unicode(). Используемый кодек ищется в реестре кодеков Python. Возвращает NULL, если кодек возбудил исключение.

Примечание

Эта функция недоступна в 3.x и не имеет псевдонима PyBytes.

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

PyObject* PyString_AsDecodedObject(PyObject *str, const char *encoding, const char *errors)¶: Возвращаемое значение: новая ссылка.
Декодирует строковый объект, передавая его кодеку, зарегистрированному для encoding, и возвращает результат в виде объекта Python. Параметры encoding и errors имеют то же значение, что и одноимённые параметры метода строки encode(). Используемый кодек ищется в реестре кодеков Python. Возвращает NULL, если кодек возбудил исключение.

Примечание

Эта функция недоступна в 3.x и не имеет псевдонима PyBytes.

PyObject* PyString_Encode(const char *s, Py_ssize_t size, const char *encoding, const char *errors)¶

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

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

Примечание

Эта функция недоступна в 3.x и не имеет псевдонима PyBytes.

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

Примечание

Эта функция недоступна в 3.x и не имеет псевдонима PyBytes.