Bytes Objects

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

Примечание

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

PyStringObject¶: Этот подтип PyObject представляет строковый объект Python.

PyTypeObject PyString_Type¶: Этот экземпляр PyTypeObject представляет строковый тип Python; это tот же объект, что и 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")`.
`%lld`	long long	Полностью эквивалентно `printf("%lld")`.
`%llu`	unsigned long long	Полностью эквивалентно `printf("%llu")`.
`%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` на данной платформе.

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

Примечание

Спецификаторы формата “%lld” и “%llu” доступны только когда определён HAVE_LONG_LONG.

Изменено в версии 2.7: Добавлена поддержка “%lld” и “%llu”.

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.

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

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

Примечание

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