`string.md`

277 строк · 21.3 КБ · обычная страница · сырой текст · скачать
1> **Источник:** https://python-all.ru/2.6/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.6/library/exceptions.html#exceptions.TypeError), если ожидается строковый параметр, а вызываются с нестроковым.1011> **Примечание**12>13> Эти функции были переименованы в PyBytes\_\* в Python 3.x. Если не указано иное, функции PyBytes, доступные в 3.x, являются псевдонимами соответствующих функций PyString\_\* для облегчения переноса.1415**`PyStringObject`**1617Этот подтип1819[`PyObject`](https://python-all.ru/2.6/c-api/structures.html#PyObject)2021представляет Python-строку.2223**[PyTypeObject](https://python-all.ru/2.6/c-api/type.html#PyTypeObject) `PyString_Type`**2425Этот экземпляр [`PyTypeObject`](https://python-all.ru/2.6/c-api/type.html#PyTypeObject) представляет тип Python-строки; это тот же объект, что и `str` и `types.StringType` в Python-слое.2627**int `PyString_Check`([PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject) *\*o*)**2829Возвращает истину, если объект *o* является строковым объектом или экземпляром подтипа строкового типа.3031Изменено в версии 2.2: Теперь допускаются подтипы.3233**int `PyString_CheckExact`([PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject) *\*o*)**3435Возвращает истину, если объект *o* является строковым объектом, но не экземпляром подтипа строкового типа.3637Новое в версии 2.2.3839**[PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject)\* `PyString_FromString`(const char *\*v*)**4041*Возвращаемое значение: новая ссылка.*4243Возвращает новый строковый объект, содержащий копию строки *v* в качестве значения, в случае успеха, и *NULL* в случае ошибки. Параметр *v* не должен быть *NULL*; он не будет проверяться.4445**[PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject)\* `PyString_FromStringAndSize`(const char *\*v*, Py\_ssize\_t *len*)**4647*Возвращаемое значение: новая ссылка.*4849Возвращает новый строковый объект, содержащий копию строки *v* с указанным значением и длиной *len* в случае успеха, и *NULL* в случае ошибки. Если *v* равно *NULL*, содержимое строки не инициализировано.5051Изменено в версии 2.5: Ранее эта функция использовала тип `int` для параметра *len*. Это может потребовать изменений в коде для корректной поддержки 64-битных систем.5253**[PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject)\* `PyString_FromFormat`(const char *\*format*, ...)**5455*Возвращаемое значение: новая ссылка.*5657Принимает строку *format* в стиле C-функции `printf()` и переменное число аргументов, вычисляет размер результирующей Python-строки и возвращает строку с отформатированными в неё значениями. Переменные аргументы должны быть типами C и в точности соответствовать символам формата в строке *format*. Допускаются следующие символы формата:5859| Символы формата | Тип | Описание |60| --- | --- | --- |61| `%%` | *н/д* | Буквальный символ %. |62| `%c` | int | Одиночный символ, представленный как C int. |63| `%d` | int | Полностью эквивалентно `printf("%d")`. |64| `%u` | беззнаковый int | Полностью эквивалентно `printf("%u")`. |65| `%ld` | long | Полностью эквивалентно `printf("%ld")`. |66| `%lu` | беззнаковый long | Полностью эквивалентно `printf("%lu")`. |67| `%zd` | Py\_ssize\_t | Полностью эквивалентно `printf("%zd")`. |68| `%zu` | size\_t | Полностью эквивалентно `printf("%zu")`. |69| `%i` | int | Полностью эквивалентно `printf("%i")`. |70| `%x` | int | Полностью эквивалентно `printf("%x")`. |71| `%s` | char\* | Нуль-терминированный массив символов C. |72| `%p` | void\* | Шестнадцатеричное представление указателя C. В основном эквивалентно `printf("%p")` за исключением того, что гарантированно начинается с литерала `0x` независимо от того, что выдает `printf` на данной платформе. |7374Нераспознанный символ формата приводит к тому, что вся оставшаяся строка формата копируется как есть в результирующую строку, а все лишние аргументы отбрасываются.7576**[PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject)\* `PyString_FromFormatV`(const char *\*format*, va\_list *vargs*)**7778*Возвращаемое значение: новая ссылка.*7980Аналогичен [`PyString_FromFormat()`](https://python-all.ru/2.6/c-api/string.html#PyString_FromFormat), за исключением того, что принимает ровно два аргумента.8182**Py\_ssize\_t `PyString_Size`([PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject) *\*string*)**8384Возвращает длину строки в строковом объекте *string*.8586Изменено в версии 2.5: Эта функция возвращала значение типа `int`. Это может потребовать изменений в вашем коде для корректной поддержки 64-битных систем.8788**Py\_ssize\_t `PyString_GET_SIZE`([PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject) *\*string*)**8990Макро-форма [`PyString_Size()`](https://python-all.ru/2.6/c-api/string.html#PyString_Size), но без проверки ошибок.9192Изменено в версии 2.5: Этот макрос возвращал значение типа `int`. Это может потребовать изменений в вашем коде для корректной поддержки 64-битных систем.9394**char\* `PyString_AsString`([PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject) *\*string*)**9596Возвращает NUL-терминированное представление содержимого9798*string*99100. Указатель ссылается на внутренний буфер101102*string*103104, а не на копию. Данные нельзя изменять никаким образом, если только строка не была только что создана с помощью105106`PyString_FromStringAndSize(NULL, size)`107108. Её нельзя освобождать. Если109110*string*111112является объектом Unicode, эта функция вычисляет кодировку по умолчанию для113114*string*115116и работает с ней. Если117118*string*119120вообще не является строковым объектом,121122[`PyString_AsString()`](https://python-all.ru/2.6/c-api/string.html#PyString_AsString)123124возвращает125126*NULL*127128и возбуждает129130[`TypeError`](https://python-all.ru/2.6/library/exceptions.html#exceptions.TypeError)131132.133134**char\* `PyString_AS_STRING`([PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject) *\*string*)**135136Макро-форма137138[`PyString_AsString()`](https://python-all.ru/2.6/c-api/string.html#PyString_AsString)139140, но без проверки ошибок. Поддерживаются только строковые объекты; объекты Unicode передавать не следует.141142**int `PyString_AsStringAndSize`([PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject) *\*obj*, char *\*\*buffer*, Py\_ssize\_t *\*length*)**143144Возвращает представление содержимого объекта *obj*, завершающееся NUL, через выходные переменные *buffer* и *length*.145146Функция принимает на вход как строковые объекты, так и объекты Unicode. Для объектов Unicode она возвращает версию объекта, закодированную в кодировке по умолчанию. Если *length* равно *NULL*, результирующий буфер не может содержать NUL-символы; если они есть, функция возвращает `-1` и возбуждается [`TypeError`](https://python-all.ru/2.6/library/exceptions.html#exceptions.TypeError).147148Буфер ссылается на внутренний строковый буфер *obj*, а не на копию. Данные нельзя изменять никаким образом, если только строка не была только что создана с помощью `PyString_FromStringAndSize(NULL, size)`. Её нельзя освобождать. Если *string* является объектом Unicode, эта функция вычисляет кодировку по умолчанию для *string* и работает с ней. Если *string* вообще не является строковым объектом, [`PyString_AsStringAndSize()`](https://python-all.ru/2.6/c-api/string.html#PyString_AsStringAndSize) возвращает `-1` и возбуждает [`TypeError`](https://python-all.ru/2.6/library/exceptions.html#exceptions.TypeError).149150Изменено в версии 2.5: Эта функция использовала тип `int *` для *length*. Это может потребовать изменений в вашем коде для корректной поддержки 64-битных систем.151152**void `PyString_Concat`([PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject) *\*\*string*, [PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject) *\*newpart*)**153154Создаёт новый строковый объект в155156*\*string*157158, содержащий содержимое159160*newpart*161162добавленное к163164*string*165166; вызывающий получает новую ссылку. Ссылка на старое значение167168*string*169170будет украдена. Если новую строку создать не удалось, старая ссылка на171172*string*173174всё равно будет отброшена, а значение175176*\*string*177178будет установлено в179180*NULL*181182; будет установлено соответствующее исключение.183184**void `PyString_ConcatAndDel`([PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject) *\*\*string*, [PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject) *\*newpart*)**185186Создаёт новый строковый объект в187188*\*string*189190, содержащий содержимое191192*newpart*193194добавленное к195196*string*197198. Эта версия уменьшает счётчик ссылок199200*newpart*201202.203204**int `_PyString_Resize`([PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject) *\*\*string*, Py\_ssize\_t *newsize*)**205206Способ изменить размер строкового объекта, несмотря на его «неизменяемость». Используйте это только для создания совершенно нового строкового объекта; не используйте, если строка может уже быть известна в других частях кода. Вызов этой функции является ошибкой, если счётчик ссылок на входной строковый объект не равен единице. Передайте адрес существующего строкового объекта как lvalue (в него может быть произведена запись) и новый желаемый размер. В случае успеха *\*string* содержит изменённый строковый объект, и `0` возвращается; адрес в *\*string* может отличаться от исходного. Если перераспределение не удалось, исходный строковый объект по адресу *\*string* освобождается, *\*string* устанавливается в *NULL*, устанавливается исключение памяти, и `-1` возвращается.207208Изменено в версии 2.5: Эта функция использовала тип `int` для *newsize*. Это может потребовать изменений в коде для корректной поддержки 64-битных систем.209210**[PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject)\* `PyString_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*)**211212*Возвращаемое значение: новая ссылка.*213214Возвращает новый строковый объект из *format* и *args*. Аналог `format % args`. Аргумент *args* должен быть кортежем.215216**void `PyString_InternInPlace`([PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject) *\*\*string*)**217218Интернирует аргумент *\*string* на месте. Аргумент должен быть адресом переменной-указателя, указывающей на строковый объект Python. Если уже существует интернированная строка, совпадающая с *\*string*, то *\*string* устанавливается в неё (уменьшая счётчик ссылок старого строкового объекта и увеличивая счётчик ссылок интернированного строкового объекта), в противном случае *\*string* оставляется без изменений и интернируется (увеличивая её счётчик ссылок). (Пояснение: хотя здесь много говорится о счётчиках ссылок, считайте эту функцию нейтральной по отношению к счётчикам ссылок; вы владеете объектом после вызова тогда и только тогда, когда владели им до вызова.)219220> **Примечание**221>222> Эта функция недоступна в 3.x и не имеет псевдонима PyBytes.223224**[PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject)\* `PyString_InternFromString`(const char *\*v*)**225226*Возвращаемое значение: новая ссылка.*227228Комбинация [`PyString_FromString()`](https://python-all.ru/2.6/c-api/string.html#PyString_FromString) и [`PyString_InternInPlace()`](https://python-all.ru/2.6/c-api/string.html#PyString_InternInPlace), возвращающая либо новый строковый объект, который был интернирован, либо новую («владетельную») ссылку на ранее интернированный строковый объект с тем же значением.229230> **Примечание**231>232> Эта функция недоступна в 3.x и не имеет псевдонима PyBytes.233234**[PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject)\* `PyString_Decode`(const char *\*s*, Py\_ssize\_t *size*, const char *\*encoding*, const char *\*errors*)**235236*Возвращаемое значение: новая ссылка.*237238Создаёт объект путём декодирования *size* байтов закодированного буфера *s* с помощью кодека, зарегистрированного для *encoding*. Параметры *encoding* и *errors* имеют то же значение, что и одноимённые параметры встроенной функции [`unicode()`](https://python-all.ru/2.6/library/functions.html#unicode). Используемый кодек ищется в реестре кодеков Python. Возвращает *NULL*, если кодек возбудил исключение.239240> **Примечание**241>242> Эта функция недоступна в 3.x и не имеет псевдонима PyBytes.243244Изменено в версии 2.5: Раньше эта функция использовала тип `int` для *size*. Это может потребовать изменений в вашем коде для корректной поддержки 64-битных систем.245246**[PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject)\* `PyString_AsDecodedObject`([PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject) *\*str*, const char *\*encoding*, const char *\*errors*)**247248*Возвращаемое значение: новая ссылка.*249250Декодирует строковый объект, передавая его кодеку, зарегистрированному для *encoding*, и возвращает результат в виде объекта Python. Параметры *encoding* и *errors* имеют то же значение, что и одноимённые параметры метода строки `encode()`. Используемый кодек ищется в реестре кодеков Python. Возвращает *NULL*, если кодек возбудил исключение.251252> **Примечание**253>254> Эта функция недоступна в 3.x и не имеет псевдонима PyBytes.255256**[PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject)\* `PyString_Encode`(const char *\*s*, Py\_ssize\_t *size*, const char *\*encoding*, const char *\*errors*)**257258*Возвращаемое значение: новая ссылка.*259260Кодирует буфер `char` заданного размера, передавая его кодеку, зарегистрированному для *encoding*, и возвращает объект Python. Параметры *encoding* и *errors* имеют то же значение, что и одноимённые параметры метода строки `encode()`. Используемый кодек ищется в реестре кодеков Python. Возвращает *NULL*, если кодек возбудил исключение.261262> **Примечание**263>264> Эта функция недоступна в 3.x и не имеет псевдонима PyBytes.265266Изменено в версии 2.5: Раньше эта функция использовала тип `int` для *size*. Это может потребовать изменений в вашем коде для корректной поддержки 64-битных систем.267268**[PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject)\* `PyString_AsEncodedObject`([PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject) *\*str*, const char *\*encoding*, const char *\*errors*)**269270*Возвращаемое значение: новая ссылка.*271272Кодирует строковый объект с помощью кодека, зарегистрированного для *encoding*, и возвращает результат в виде объекта Python. Параметры *encoding* и *errors* имеют то же значение, что и одноимённые параметры метода строки `encode()`. Используемый кодек ищется в реестре кодеков Python. Возвращает *NULL*, если кодек возбудил исключение.273274> **Примечание**275>276> Эта функция недоступна в 3.x и не имеет псевдонима PyBytes.277