|
1 .. highlightlang:: c |
|
2 |
|
3 .. _stringobjects: |
|
4 |
|
5 String/Bytes Objects |
|
6 -------------------- |
|
7 |
|
8 These functions raise :exc:`TypeError` when expecting a string parameter and are |
|
9 called with a non-string parameter. |
|
10 |
|
11 .. note:: |
|
12 These functions have been renamed to PyBytes_* in Python 3.x. The PyBytes |
|
13 names are also available in 2.6. |
|
14 |
|
15 .. index:: object: string |
|
16 |
|
17 |
|
18 .. ctype:: PyStringObject |
|
19 |
|
20 This subtype of :ctype:`PyObject` represents a Python string object. |
|
21 |
|
22 |
|
23 .. cvar:: PyTypeObject PyString_Type |
|
24 |
|
25 .. index:: single: StringType (in module types) |
|
26 |
|
27 This instance of :ctype:`PyTypeObject` represents the Python string type; it is |
|
28 the same object as ``str`` and ``types.StringType`` in the Python layer. . |
|
29 |
|
30 |
|
31 .. cfunction:: int PyString_Check(PyObject *o) |
|
32 |
|
33 Return true if the object *o* is a string object or an instance of a subtype of |
|
34 the string type. |
|
35 |
|
36 .. versionchanged:: 2.2 |
|
37 Allowed subtypes to be accepted. |
|
38 |
|
39 |
|
40 .. cfunction:: int PyString_CheckExact(PyObject *o) |
|
41 |
|
42 Return true if the object *o* is a string object, but not an instance of a |
|
43 subtype of the string type. |
|
44 |
|
45 .. versionadded:: 2.2 |
|
46 |
|
47 |
|
48 .. cfunction:: PyObject* PyString_FromString(const char *v) |
|
49 |
|
50 Return a new string object with a copy of the string *v* as value on success, |
|
51 and *NULL* on failure. The parameter *v* must not be *NULL*; it will not be |
|
52 checked. |
|
53 |
|
54 |
|
55 .. cfunction:: PyObject* PyString_FromStringAndSize(const char *v, Py_ssize_t len) |
|
56 |
|
57 Return a new string object with a copy of the string *v* as value and length |
|
58 *len* on success, and *NULL* on failure. If *v* is *NULL*, the contents of the |
|
59 string are uninitialized. |
|
60 |
|
61 |
|
62 .. cfunction:: PyObject* PyString_FromFormat(const char *format, ...) |
|
63 |
|
64 Take a C :cfunc:`printf`\ -style *format* string and a variable number of |
|
65 arguments, calculate the size of the resulting Python string and return a string |
|
66 with the values formatted into it. The variable arguments must be C types and |
|
67 must correspond exactly to the format characters in the *format* string. The |
|
68 following format characters are allowed: |
|
69 |
|
70 .. % This should be exactly the same as the table in PyErr_Format. |
|
71 .. % One should just refer to the other. |
|
72 .. % The descriptions for %zd and %zu are wrong, but the truth is complicated |
|
73 .. % because not all compilers support the %z width modifier -- we fake it |
|
74 .. % when necessary via interpolating PY_FORMAT_SIZE_T. |
|
75 .. % %u, %lu, %zu should have "new in Python 2.5" blurbs. |
|
76 |
|
77 +-------------------+---------------+--------------------------------+ |
|
78 | Format Characters | Type | Comment | |
|
79 +===================+===============+================================+ |
|
80 | :attr:`%%` | *n/a* | The literal % character. | |
|
81 +-------------------+---------------+--------------------------------+ |
|
82 | :attr:`%c` | int | A single character, | |
|
83 | | | represented as an C int. | |
|
84 +-------------------+---------------+--------------------------------+ |
|
85 | :attr:`%d` | int | Exactly equivalent to | |
|
86 | | | ``printf("%d")``. | |
|
87 +-------------------+---------------+--------------------------------+ |
|
88 | :attr:`%u` | unsigned int | Exactly equivalent to | |
|
89 | | | ``printf("%u")``. | |
|
90 +-------------------+---------------+--------------------------------+ |
|
91 | :attr:`%ld` | long | Exactly equivalent to | |
|
92 | | | ``printf("%ld")``. | |
|
93 +-------------------+---------------+--------------------------------+ |
|
94 | :attr:`%lu` | unsigned long | Exactly equivalent to | |
|
95 | | | ``printf("%lu")``. | |
|
96 +-------------------+---------------+--------------------------------+ |
|
97 | :attr:`%zd` | Py_ssize_t | Exactly equivalent to | |
|
98 | | | ``printf("%zd")``. | |
|
99 +-------------------+---------------+--------------------------------+ |
|
100 | :attr:`%zu` | size_t | Exactly equivalent to | |
|
101 | | | ``printf("%zu")``. | |
|
102 +-------------------+---------------+--------------------------------+ |
|
103 | :attr:`%i` | int | Exactly equivalent to | |
|
104 | | | ``printf("%i")``. | |
|
105 +-------------------+---------------+--------------------------------+ |
|
106 | :attr:`%x` | int | Exactly equivalent to | |
|
107 | | | ``printf("%x")``. | |
|
108 +-------------------+---------------+--------------------------------+ |
|
109 | :attr:`%s` | char\* | A null-terminated C character | |
|
110 | | | array. | |
|
111 +-------------------+---------------+--------------------------------+ |
|
112 | :attr:`%p` | void\* | The hex representation of a C | |
|
113 | | | pointer. Mostly equivalent to | |
|
114 | | | ``printf("%p")`` except that | |
|
115 | | | it is guaranteed to start with | |
|
116 | | | the literal ``0x`` regardless | |
|
117 | | | of what the platform's | |
|
118 | | | ``printf`` yields. | |
|
119 +-------------------+---------------+--------------------------------+ |
|
120 |
|
121 An unrecognized format character causes all the rest of the format string to be |
|
122 copied as-is to the result string, and any extra arguments discarded. |
|
123 |
|
124 |
|
125 .. cfunction:: PyObject* PyString_FromFormatV(const char *format, va_list vargs) |
|
126 |
|
127 Identical to :cfunc:`PyString_FromFormat` except that it takes exactly two |
|
128 arguments. |
|
129 |
|
130 |
|
131 .. cfunction:: Py_ssize_t PyString_Size(PyObject *string) |
|
132 |
|
133 Return the length of the string in string object *string*. |
|
134 |
|
135 |
|
136 .. cfunction:: Py_ssize_t PyString_GET_SIZE(PyObject *string) |
|
137 |
|
138 Macro form of :cfunc:`PyString_Size` but without error checking. |
|
139 |
|
140 |
|
141 .. cfunction:: char* PyString_AsString(PyObject *string) |
|
142 |
|
143 Return a NUL-terminated representation of the contents of *string*. The pointer |
|
144 refers to the internal buffer of *string*, not a copy. The data must not be |
|
145 modified in any way, unless the string was just created using |
|
146 ``PyString_FromStringAndSize(NULL, size)``. It must not be deallocated. If |
|
147 *string* is a Unicode object, this function computes the default encoding of |
|
148 *string* and operates on that. If *string* is not a string object at all, |
|
149 :cfunc:`PyString_AsString` returns *NULL* and raises :exc:`TypeError`. |
|
150 |
|
151 |
|
152 .. cfunction:: char* PyString_AS_STRING(PyObject *string) |
|
153 |
|
154 Macro form of :cfunc:`PyString_AsString` but without error checking. Only |
|
155 string objects are supported; no Unicode objects should be passed. |
|
156 |
|
157 |
|
158 .. cfunction:: int PyString_AsStringAndSize(PyObject *obj, char **buffer, Py_ssize_t *length) |
|
159 |
|
160 Return a NUL-terminated representation of the contents of the object *obj* |
|
161 through the output variables *buffer* and *length*. |
|
162 |
|
163 The function accepts both string and Unicode objects as input. For Unicode |
|
164 objects it returns the default encoded version of the object. If *length* is |
|
165 *NULL*, the resulting buffer may not contain NUL characters; if it does, the |
|
166 function returns ``-1`` and a :exc:`TypeError` is raised. |
|
167 |
|
168 The buffer refers to an internal string buffer of *obj*, not a copy. The data |
|
169 must not be modified in any way, unless the string was just created using |
|
170 ``PyString_FromStringAndSize(NULL, size)``. It must not be deallocated. If |
|
171 *string* is a Unicode object, this function computes the default encoding of |
|
172 *string* and operates on that. If *string* is not a string object at all, |
|
173 :cfunc:`PyString_AsStringAndSize` returns ``-1`` and raises :exc:`TypeError`. |
|
174 |
|
175 |
|
176 .. cfunction:: void PyString_Concat(PyObject **string, PyObject *newpart) |
|
177 |
|
178 Create a new string object in *\*string* containing the contents of *newpart* |
|
179 appended to *string*; the caller will own the new reference. The reference to |
|
180 the old value of *string* will be stolen. If the new string cannot be created, |
|
181 the old reference to *string* will still be discarded and the value of |
|
182 *\*string* will be set to *NULL*; the appropriate exception will be set. |
|
183 |
|
184 |
|
185 .. cfunction:: void PyString_ConcatAndDel(PyObject **string, PyObject *newpart) |
|
186 |
|
187 Create a new string object in *\*string* containing the contents of *newpart* |
|
188 appended to *string*. This version decrements the reference count of *newpart*. |
|
189 |
|
190 |
|
191 .. cfunction:: int _PyString_Resize(PyObject **string, Py_ssize_t newsize) |
|
192 |
|
193 A way to resize a string object even though it is "immutable". Only use this to |
|
194 build up a brand new string object; don't use this if the string may already be |
|
195 known in other parts of the code. It is an error to call this function if the |
|
196 refcount on the input string object is not one. Pass the address of an existing |
|
197 string object as an lvalue (it may be written into), and the new size desired. |
|
198 On success, *\*string* holds the resized string object and ``0`` is returned; |
|
199 the address in *\*string* may differ from its input value. If the reallocation |
|
200 fails, the original string object at *\*string* is deallocated, *\*string* is |
|
201 set to *NULL*, a memory exception is set, and ``-1`` is returned. |
|
202 |
|
203 |
|
204 .. cfunction:: PyObject* PyString_Format(PyObject *format, PyObject *args) |
|
205 |
|
206 Return a new string object from *format* and *args*. Analogous to ``format % |
|
207 args``. The *args* argument must be a tuple. |
|
208 |
|
209 |
|
210 .. cfunction:: void PyString_InternInPlace(PyObject **string) |
|
211 |
|
212 Intern the argument *\*string* in place. The argument must be the address of a |
|
213 pointer variable pointing to a Python string object. If there is an existing |
|
214 interned string that is the same as *\*string*, it sets *\*string* to it |
|
215 (decrementing the reference count of the old string object and incrementing the |
|
216 reference count of the interned string object), otherwise it leaves *\*string* |
|
217 alone and interns it (incrementing its reference count). (Clarification: even |
|
218 though there is a lot of talk about reference counts, think of this function as |
|
219 reference-count-neutral; you own the object after the call if and only if you |
|
220 owned it before the call.) |
|
221 |
|
222 |
|
223 .. cfunction:: PyObject* PyString_InternFromString(const char *v) |
|
224 |
|
225 A combination of :cfunc:`PyString_FromString` and |
|
226 :cfunc:`PyString_InternInPlace`, returning either a new string object that has |
|
227 been interned, or a new ("owned") reference to an earlier interned string object |
|
228 with the same value. |
|
229 |
|
230 |
|
231 .. cfunction:: PyObject* PyString_Decode(const char *s, Py_ssize_t size, const char *encoding, const char *errors) |
|
232 |
|
233 Create an object by decoding *size* bytes of the encoded buffer *s* using the |
|
234 codec registered for *encoding*. *encoding* and *errors* have the same meaning |
|
235 as the parameters of the same name in the :func:`unicode` built-in function. |
|
236 The codec to be used is looked up using the Python codec registry. Return |
|
237 *NULL* if an exception was raised by the codec. |
|
238 |
|
239 |
|
240 .. cfunction:: PyObject* PyString_AsDecodedObject(PyObject *str, const char *encoding, const char *errors) |
|
241 |
|
242 Decode a string object by passing it to the codec registered for *encoding* and |
|
243 return the result as Python object. *encoding* and *errors* have the same |
|
244 meaning as the parameters of the same name in the string :meth:`encode` method. |
|
245 The codec to be used is looked up using the Python codec registry. Return *NULL* |
|
246 if an exception was raised by the codec. |
|
247 |
|
248 |
|
249 .. cfunction:: PyObject* PyString_Encode(const char *s, Py_ssize_t size, const char *encoding, const char *errors) |
|
250 |
|
251 Encode the :ctype:`char` buffer of the given size by passing it to the codec |
|
252 registered for *encoding* and return a Python object. *encoding* and *errors* |
|
253 have the same meaning as the parameters of the same name in the string |
|
254 :meth:`encode` method. The codec to be used is looked up using the Python codec |
|
255 registry. Return *NULL* if an exception was raised by the codec. |
|
256 |
|
257 |
|
258 .. cfunction:: PyObject* PyString_AsEncodedObject(PyObject *str, const char *encoding, const char *errors) |
|
259 |
|
260 Encode a string object using the codec registered for *encoding* and return the |
|
261 result as Python object. *encoding* and *errors* have the same meaning as the |
|
262 parameters of the same name in the string :meth:`encode` method. The codec to be |
|
263 used is looked up using the Python codec registry. Return *NULL* if an exception |
|
264 was raised by the codec. |