|
1 |
|
2 /* String (str/bytes) object interface */ |
|
3 |
|
4 #ifndef Py_STRINGOBJECT_H |
|
5 #define Py_STRINGOBJECT_H |
|
6 #ifdef __cplusplus |
|
7 extern "C" { |
|
8 #endif |
|
9 |
|
10 #include <stdarg.h> |
|
11 |
|
12 /* |
|
13 Type PyStringObject represents a character string. An extra zero byte is |
|
14 reserved at the end to ensure it is zero-terminated, but a size is |
|
15 present so strings with null bytes in them can be represented. This |
|
16 is an immutable object type. |
|
17 |
|
18 There are functions to create new string objects, to test |
|
19 an object for string-ness, and to get the |
|
20 string value. The latter function returns a null pointer |
|
21 if the object is not of the proper type. |
|
22 There is a variant that takes an explicit size as well as a |
|
23 variant that assumes a zero-terminated string. Note that none of the |
|
24 functions should be applied to nil objects. |
|
25 */ |
|
26 |
|
27 /* Caching the hash (ob_shash) saves recalculation of a string's hash value. |
|
28 Interning strings (ob_sstate) tries to ensure that only one string |
|
29 object with a given value exists, so equality tests can be one pointer |
|
30 comparison. This is generally restricted to strings that "look like" |
|
31 Python identifiers, although the intern() builtin can be used to force |
|
32 interning of any string. |
|
33 Together, these sped the interpreter by up to 20%. */ |
|
34 |
|
35 typedef struct { |
|
36 PyObject_VAR_HEAD |
|
37 long ob_shash; |
|
38 int ob_sstate; |
|
39 char ob_sval[1]; |
|
40 |
|
41 /* Invariants: |
|
42 * ob_sval contains space for 'ob_size+1' elements. |
|
43 * ob_sval[ob_size] == 0. |
|
44 * ob_shash is the hash of the string or -1 if not computed yet. |
|
45 * ob_sstate != 0 iff the string object is in stringobject.c's |
|
46 * 'interned' dictionary; in this case the two references |
|
47 * from 'interned' to this object are *not counted* in ob_refcnt. |
|
48 */ |
|
49 } PyStringObject; |
|
50 |
|
51 #define SSTATE_NOT_INTERNED 0 |
|
52 #define SSTATE_INTERNED_MORTAL 1 |
|
53 #define SSTATE_INTERNED_IMMORTAL 2 |
|
54 |
|
55 PyAPI_DATA(PyTypeObject) PyBaseString_Type; |
|
56 PyAPI_DATA(PyTypeObject) PyString_Type; |
|
57 |
|
58 #define PyString_Check(op) \ |
|
59 PyType_FastSubclass(Py_TYPE(op), Py_TPFLAGS_STRING_SUBCLASS) |
|
60 #define PyString_CheckExact(op) (Py_TYPE(op) == &PyString_Type) |
|
61 |
|
62 PyAPI_FUNC(PyObject *) PyString_FromStringAndSize(const char *, Py_ssize_t); |
|
63 PyAPI_FUNC(PyObject *) PyString_FromString(const char *); |
|
64 PyAPI_FUNC(PyObject *) PyString_FromFormatV(const char*, va_list) |
|
65 Py_GCC_ATTRIBUTE((format(printf, 1, 0))); |
|
66 PyAPI_FUNC(PyObject *) PyString_FromFormat(const char*, ...) |
|
67 Py_GCC_ATTRIBUTE((format(printf, 1, 2))); |
|
68 PyAPI_FUNC(Py_ssize_t) PyString_Size(PyObject *); |
|
69 PyAPI_FUNC(char *) PyString_AsString(PyObject *); |
|
70 PyAPI_FUNC(PyObject *) PyString_Repr(PyObject *, int); |
|
71 PyAPI_FUNC(void) PyString_Concat(PyObject **, PyObject *); |
|
72 PyAPI_FUNC(void) PyString_ConcatAndDel(PyObject **, PyObject *); |
|
73 PyAPI_FUNC(int) _PyString_Resize(PyObject **, Py_ssize_t); |
|
74 PyAPI_FUNC(int) _PyString_Eq(PyObject *, PyObject*); |
|
75 PyAPI_FUNC(PyObject *) PyString_Format(PyObject *, PyObject *); |
|
76 PyAPI_FUNC(PyObject *) _PyString_FormatLong(PyObject*, int, int, |
|
77 int, char**, int*); |
|
78 PyAPI_FUNC(PyObject *) PyString_DecodeEscape(const char *, Py_ssize_t, |
|
79 const char *, Py_ssize_t, |
|
80 const char *); |
|
81 |
|
82 PyAPI_FUNC(void) PyString_InternInPlace(PyObject **); |
|
83 PyAPI_FUNC(void) PyString_InternImmortal(PyObject **); |
|
84 PyAPI_FUNC(PyObject *) PyString_InternFromString(const char *); |
|
85 PyAPI_FUNC(void) _Py_ReleaseInternedStrings(void); |
|
86 |
|
87 /* Use only if you know it's a string */ |
|
88 #define PyString_CHECK_INTERNED(op) (((PyStringObject *)(op))->ob_sstate) |
|
89 |
|
90 /* Macro, trading safety for speed */ |
|
91 #define PyString_AS_STRING(op) (((PyStringObject *)(op))->ob_sval) |
|
92 #define PyString_GET_SIZE(op) Py_SIZE(op) |
|
93 |
|
94 /* _PyString_Join(sep, x) is like sep.join(x). sep must be PyStringObject*, |
|
95 x must be an iterable object. */ |
|
96 PyAPI_FUNC(PyObject *) _PyString_Join(PyObject *sep, PyObject *x); |
|
97 |
|
98 /* --- Generic Codecs ----------------------------------------------------- */ |
|
99 |
|
100 /* Create an object by decoding the encoded string s of the |
|
101 given size. */ |
|
102 |
|
103 PyAPI_FUNC(PyObject*) PyString_Decode( |
|
104 const char *s, /* encoded string */ |
|
105 Py_ssize_t size, /* size of buffer */ |
|
106 const char *encoding, /* encoding */ |
|
107 const char *errors /* error handling */ |
|
108 ); |
|
109 |
|
110 /* Encodes a char buffer of the given size and returns a |
|
111 Python object. */ |
|
112 |
|
113 PyAPI_FUNC(PyObject*) PyString_Encode( |
|
114 const char *s, /* string char buffer */ |
|
115 Py_ssize_t size, /* number of chars to encode */ |
|
116 const char *encoding, /* encoding */ |
|
117 const char *errors /* error handling */ |
|
118 ); |
|
119 |
|
120 /* Encodes a string object and returns the result as Python |
|
121 object. */ |
|
122 |
|
123 PyAPI_FUNC(PyObject*) PyString_AsEncodedObject( |
|
124 PyObject *str, /* string object */ |
|
125 const char *encoding, /* encoding */ |
|
126 const char *errors /* error handling */ |
|
127 ); |
|
128 |
|
129 /* Encodes a string object and returns the result as Python string |
|
130 object. |
|
131 |
|
132 If the codec returns an Unicode object, the object is converted |
|
133 back to a string using the default encoding. |
|
134 |
|
135 DEPRECATED - use PyString_AsEncodedObject() instead. */ |
|
136 |
|
137 PyAPI_FUNC(PyObject*) PyString_AsEncodedString( |
|
138 PyObject *str, /* string object */ |
|
139 const char *encoding, /* encoding */ |
|
140 const char *errors /* error handling */ |
|
141 ); |
|
142 |
|
143 /* Decodes a string object and returns the result as Python |
|
144 object. */ |
|
145 |
|
146 PyAPI_FUNC(PyObject*) PyString_AsDecodedObject( |
|
147 PyObject *str, /* string object */ |
|
148 const char *encoding, /* encoding */ |
|
149 const char *errors /* error handling */ |
|
150 ); |
|
151 |
|
152 /* Decodes a string object and returns the result as Python string |
|
153 object. |
|
154 |
|
155 If the codec returns an Unicode object, the object is converted |
|
156 back to a string using the default encoding. |
|
157 |
|
158 DEPRECATED - use PyString_AsDecodedObject() instead. */ |
|
159 |
|
160 PyAPI_FUNC(PyObject*) PyString_AsDecodedString( |
|
161 PyObject *str, /* string object */ |
|
162 const char *encoding, /* encoding */ |
|
163 const char *errors /* error handling */ |
|
164 ); |
|
165 |
|
166 /* Provides access to the internal data buffer and size of a string |
|
167 object or the default encoded version of an Unicode object. Passing |
|
168 NULL as *len parameter will force the string buffer to be |
|
169 0-terminated (passing a string with embedded NULL characters will |
|
170 cause an exception). */ |
|
171 |
|
172 PyAPI_FUNC(int) PyString_AsStringAndSize( |
|
173 register PyObject *obj, /* string or Unicode object */ |
|
174 register char **s, /* pointer to buffer variable */ |
|
175 register Py_ssize_t *len /* pointer to length variable or NULL |
|
176 (only possible for 0-terminated |
|
177 strings) */ |
|
178 ); |
|
179 |
|
180 /* Using the current locale, insert the thousands grouping |
|
181 into the string pointed to by buffer. For the argument descriptions, |
|
182 see Objects/stringlib/localeutil.h */ |
|
183 |
|
184 PyAPI_FUNC(int) _PyString_InsertThousandsGrouping(char *buffer, |
|
185 Py_ssize_t n_buffer, |
|
186 Py_ssize_t n_digits, |
|
187 Py_ssize_t buf_size, |
|
188 Py_ssize_t *count, |
|
189 int append_zero_char); |
|
190 |
|
191 /* Format the object based on the format_spec, as defined in PEP 3101 |
|
192 (Advanced String Formatting). */ |
|
193 PyAPI_FUNC(PyObject *) _PyBytes_FormatAdvanced(PyObject *obj, |
|
194 char *format_spec, |
|
195 Py_ssize_t format_spec_len); |
|
196 |
|
197 #ifdef __cplusplus |
|
198 } |
|
199 #endif |
|
200 #endif /* !Py_STRINGOBJECT_H */ |