`string.md`

197 строк · 19.9 КБ · обычная страница · сырой текст · скачать
1> **Источник:** https://python-all.ru/2.7/c-api/string.html2>3> «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor.45---67# Объекты строк/байтов89Эти функции возбуждают [`TypeError`](https://python-all.ru/2.7/library/exceptions.html#exceptions.TypeError), когда ожидают строковый параметр, но вызываются с нестроковым.1011> **Примечание**12>13> Эти функции были переименованы в PyBytes\_\* в Python 3.x. Если не указано иное, функции PyBytes, доступные в 3.x, являются псевдонимами соответствующих функций PyString\_\* для облегчения переноса.1415**`PyStringObject`**1617Этот подтип [`PyObject`](https://python-all.ru/2.7/c-api/structures.html#c.PyObject) представляет строковый объект Python.1819**[PyTypeObject](https://python-all.ru/2.7/c-api/type.html#c.PyTypeObject) `PyString_Type`**2021Этот экземпляр [`PyTypeObject`](https://python-all.ru/2.7/c-api/type.html#c.PyTypeObject) представляет строковый тип Python; это tот же объект, что и `str` и `types.StringType` на уровне Python.2223#### `int PyString_Check(PyObject *o)`2425Возвращает истину, если объект *o* является строковым объектом или экземпляром подтипа строкового типа.2627Изменено в версии 2.2: Теперь допускаются подтипы.2829#### `int PyString_CheckExact(PyObject *o)`3031Возвращает истину, если объект *o* является строковым объектом, но не экземпляром подтипа строкового типа.3233Новое в версии 2.2.3435#### `PyObject* PyString_FromString(const char *v)`3637*Возвращаемое значение: новая ссылка.*3839Возвращает новый строковый объект, содержащий копию строки *v* в качестве значения, в случае успеха, и *NULL* в случае ошибки. Параметр *v* не должен быть *NULL*; он не будет проверяться.4041#### `PyObject* PyString_FromStringAndSize(const char *v, Py_ssize_t len)`4243*Возвращаемое значение: новая ссылка.*4445Возвращает новый строковый объект, содержащий копию строки *v* с указанным значением и длиной *len* в случае успеха, и *NULL* в случае ошибки. Если *v* равно *NULL*, содержимое строки не инициализировано.4647Изменено в версии 2.5: Эта функция использовала тип `int` для *len*. Это может потребовать изменений в вашем коде для корректной поддержки 64-битных систем.4849#### `PyObject* PyString_FromFormat(const char *format, ...)`5051*Возвращаемое значение: новая ссылка.*5253Принимает строку формата *format* в стиле C `printf()` и переменное количество аргументов, вычисляет размер результирующей строки Python и возвращает строку с отформатированными в неё значениями. Переменные аргументы должны быть типами C и должны точно соответствовать символам формата в строке *format*. Допускаются следующие символы формата:5455| Символы формата | Тип | Описание |56| --- | --- | --- |57| `%%` | *н/д* | Буквальный символ %. |58| `%c` | int | Один символ, представленный как C int. |59| `%d` | int | Полностью эквивалентно `printf("%d")`. |60| `%u` | беззнаковый int | Полностью эквивалентно `printf("%u")`. |61| `%ld` | long | Полностью эквивалентно `printf("%ld")`. |62| `%lu` | беззнаковый long | Полностью эквивалентно `printf("%lu")`. |63| `%lld` | long long | Полностью эквивалентно `printf("%lld")`. |64| `%llu` | unsigned long long | Полностью эквивалентно `printf("%llu")`. |65| `%zd` | Py\_ssize\_t | Полностью эквивалентно `printf("%zd")`. |66| `%zu` | size\_t | Полностью эквивалентно `printf("%zu")`. |67| `%i` | int | Полностью эквивалентно `printf("%i")`. |68| `%x` | int | Полностью эквивалентно `printf("%x")`. |69| `%s` | char\* | Нуль-терминированный массив символов C. |70| `%p` | void\* | Шестнадцатеричное представление указателя C. В основном эквивалентно `printf("%p")`, за исключением того, что гарантированно начинается с литерала `0x` независимо от того, что возвращает `printf` на данной платформе. |7172Нераспознанный символ формата приводит к тому, что вся оставшаяся строка формата копируется как есть в результирующую строку, а все лишние аргументы отбрасываются.7374> **Примечание**75>76> Спецификаторы формата *“%lld”* и *“%llu”* доступны только когда определён `HAVE_LONG_LONG`.7778Изменено в версии 2.7: Добавлена поддержка *“%lld”* и *“%llu”*.7980#### `PyObject* PyString_FromFormatV(const char *format, va_list vargs)`8182*Возвращаемое значение: новая ссылка.*8384Идентично [`PyString_FromFormat()`](https://python-all.ru/2.7/c-api/string.html#c.PyString_FromFormat), за исключением того, что принимает ровно два аргумента.8586#### `Py_ssize_t PyString_Size(PyObject *string)`8788Возвращает длину строки в строковом объекте *string*.8990Изменено в версии 2.5: Эта функция возвращала тип `int`. Это может потребовать изменений в вашем коде для корректной поддержки 64-битных систем.9192#### `Py_ssize_t PyString_GET_SIZE(PyObject *string)`9394Макроформа [`PyString_Size()`](https://python-all.ru/2.7/c-api/string.html#c.PyString_Size) без проверки ошибок.9596Изменено в версии 2.5: Этот макрос возвращал тип `int`. Это может потребовать изменений в вашем коде для корректной поддержки 64-битных систем.9798#### `char* PyString_AsString(PyObject *string)`99100Возвращает NUL-терминированное представление содержимого *string*. Указатель ссылается на внутренний буфер *string*, а не на копию. Данные не должны изменяться никоим образом, если только строка не была только что создана с помощью `PyString_FromStringAndSize(NULL, size)`. Они не должны быть освобождены. Если *string* является объектом Unicode, эта функция вычисляет кодировку по умолчанию для *string* и работает с ней. Если *string* вовсе не является строковым объектом, [`PyString_AsString()`](https://python-all.ru/2.7/c-api/string.html#c.PyString_AsString) возвращает *NULL* и возбуждает [`TypeError`](https://python-all.ru/2.7/library/exceptions.html#exceptions.TypeError).101102#### `char* PyString_AS_STRING(PyObject *string)`103104Макро-форма [`PyString_AsString()`](https://python-all.ru/2.7/c-api/string.html#c.PyString_AsString), но без проверки ошибок. Поддерживаются только строковые объекты; объекты Unicode передавать не следует.105106#### `int PyString_AsStringAndSize(PyObject *obj, char **buffer, Py_ssize_t *length)`107108Возвращает представление содержимого объекта *obj*, завершающееся NUL, через выходные переменные *buffer* и *length*.109110Функция принимает на вход как строковые объекты, так и объекты Unicode. Для объектов Unicode она возвращает версию объекта, закодированную в кодировке по умолчанию. Если *length* равно *NULL*, результирующий буфер может не содержать NUL-символов; если они есть, функция возвращает `-1` и возбуждается [`TypeError`](https://python-all.ru/2.7/library/exceptions.html#exceptions.TypeError).111112Буфер ссылается на внутренний строковый буфер объекта *obj*, а не на копию. Данные нельзя изменять никоим образом, если только строка не была только что создана с помощью `PyString_FromStringAndSize(NULL, size)`. Его нельзя освобождать. Если *string* – объект Unicode, эта функция вычисляет кодировку по умолчанию для *string* и работает с ней. Если *string* вообще не является строковым объектом, [`PyString_AsStringAndSize()`](https://python-all.ru/2.7/c-api/string.html#c.PyString_AsStringAndSize) возвращает `-1` и возбуждает [`TypeError`](https://python-all.ru/2.7/library/exceptions.html#exceptions.TypeError).113114Изменено в версии 2.5: Эта функция использовала тип `int *` для *length*. Это может потребовать изменений в коде для корректной поддержки 64-битных систем.115116#### `void PyString_Concat(PyObject **string, PyObject *newpart)`117118Создаёт новый строковый объект в *\*string*, содержащий содержимое *newpart* добавленное к *string*; вызывающий получает новую ссылку. Ссылка на старое значение *string* будет украдена. Если новую строку создать не удалось, старая ссылка на *string* всё равно будет отброшена, а значение *\*string* будет установлено в *NULL*; будет установлено соответствующее исключение.119120#### `void PyString_ConcatAndDel(PyObject **string, PyObject *newpart)`121122Создаёт новый строковый объект в *\*string*, содержащий содержимое *newpart* добавленное к *string*. Эта версия уменьшает счётчик ссылок *newpart*.123124#### `int _PyString_Resize(PyObject **string, Py_ssize_t newsize)`125126Способ изменить размер строкового объекта, несмотря на его «неизменяемость». Используйте это только для создания совершенно нового строкового объекта; не используйте, если строка может уже быть известна в других частях кода. Вызов этой функции является ошибкой, если счётчик ссылок на входной строковый объект не равен единице. Передайте адрес существующего строкового объекта как lvalue (в него может быть произведена запись) и новый желаемый размер. В случае успеха *\*string* содержит изменённый строковый объект, и `0` возвращается; адрес в *\*string* может отличаться от исходного. Если перераспределение не удалось, исходный строковый объект по адресу *\*string* освобождается, *\*string* устанавливается в *NULL*, устанавливается исключение памяти, и `-1` возвращается.127128Изменено в версии 2.5: Эта функция использовала тип `int` для *newsize*. Возможно, потребуются изменения в вашем коде для корректной поддержки 64-битных систем.129130#### `PyObject* PyString_Format(PyObject *format, PyObject *args)`131132*Возвращаемое значение: новая ссылка.*133134Возвращает новый строковый объект из *format* и *args*. Аналог `format % args`. Аргумент *args* должен быть кортежем или словарём.135136#### `void PyString_InternInPlace(PyObject **string)`137138Интернирует аргумент *\*string* на месте. Аргумент должен быть адресом переменной-указателя, указывающей на строковый объект Python. Если уже существует интернированная строка, совпадающая с *\*string*, то *\*string* устанавливается в неё (уменьшая счётчик ссылок старого строкового объекта и увеличивая счётчик ссылок интернированного строкового объекта), в противном случае *\*string* оставляется без изменений и интернируется (увеличивая её счётчик ссылок). (Пояснение: хотя здесь много говорится о счётчиках ссылок, считайте эту функцию нейтральной по отношению к счётчикам ссылок; вы владеете объектом после вызова тогда и только тогда, когда владели им до вызова.)139140> **Примечание**141>142> Эта функция недоступна в 3.x и не имеет псевдонима PyBytes.143144#### `PyObject* PyString_InternFromString(const char *v)`145146*Возвращаемое значение: новая ссылка.*147148Комбинация [`PyString_FromString()`](https://python-all.ru/2.7/c-api/string.html#c.PyString_FromString) и [`PyString_InternInPlace()`](https://python-all.ru/2.7/c-api/string.html#c.PyString_InternInPlace), возвращающая либо новый интернированный строковый объект, либо новую («владетельную») ссылку на ранее интернированный строковый объект с тем же значением.149150> **Примечание**151>152> Эта функция недоступна в 3.x и не имеет псевдонима PyBytes.153154#### `PyObject* PyString_Decode(const char *s, Py_ssize_t size, const char *encoding, const char *errors)`155156*Возвращаемое значение: новая ссылка.*157158Создаёт объект путём декодирования *size* байт закодированного буфера *s* с помощью кодека, зарегистрированного для *encoding*. *encoding* и *errors* имеют тот же смысл, что и одноимённые параметры встроенной функции [`unicode()`](https://python-all.ru/2.7/library/functions.html#unicode). Используемый кодек находится через реестр кодеков Python. Возвращает *NULL*, если кодек возбудил исключение.159160> **Примечание**161>162> Эта функция недоступна в 3.x и не имеет псевдонима PyBytes.163164Изменено в версии 2.5: Эта функция использовала тип `int` для *size*. Это может потребовать изменений в коде для корректной поддержки 64-битных систем.165166#### `PyObject* PyString_AsDecodedObject(PyObject *str, const char *encoding, const char *errors)`167168*Возвращаемое значение: новая ссылка.*169170Декодирует строковый объект, передавая его кодеку, зарегистрированному для *encoding*, и возвращает результат как объект Python. *encoding* и *errors* имеют тот же смысл, что и одноимённые параметры метода строки `encode()`. Используемый кодек находится через реестр кодеков Python. Возвращает *NULL*, если кодек возбудил исключение.171172> **Примечание**173>174> Эта функция недоступна в 3.x и не имеет псевдонима PyBytes.175176#### `PyObject* PyString_Encode(const char *s, Py_ssize_t size, const char *encoding, const char *errors)`177178*Возвращаемое значение: новая ссылка.*179180Кодирует буфер `char` заданного размера, передавая его кодеку, зарегистрированному для *encoding*, и возвращает объект Python. *encoding* и *errors* имеют тот же смысл, что и одноимённые параметры метода строки `encode()`. Используемый кодек находится через реестр кодеков Python. Возвращает *NULL*, если кодек возбудил исключение.181182> **Примечание**183>184> Эта функция недоступна в 3.x и не имеет псевдонима PyBytes.185186Изменено в версии 2.5: Эта функция использовала тип `int` для *size*. Это может потребовать изменений в коде для корректной поддержки 64-битных систем.187188#### `PyObject* PyString_AsEncodedObject(PyObject *str, const char *encoding, const char *errors)`189190*Возвращаемое значение: новая ссылка.*191192Кодирует строковый объект с помощью кодека, зарегистрированного для *encoding*, и возвращает результат как объект Python. *encoding* и *errors* имеют тот же смысл, что и одноимённые параметры метода строки `encode()`. Используемый кодек находится через реестр кодеков Python. Возвращает *NULL*, если кодек возбудил исключение.193194> **Примечание**195>196> Эта функция недоступна в 3.x и не имеет псевдонима PyBytes.197