|
1 |
|
2 /* String 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) PyObject_TypeCheck(op, &PyString_Type) |
|
59 #define PyString_CheckExact(op) ((op)->ob_type == &PyString_Type) |
|
60 |
|
61 PyAPI_FUNC(PyObject *) PyString_FromStringAndSize(const char *, Py_ssize_t); |
|
62 PyAPI_FUNC(PyObject *) PyString_FromString(const char *); |
|
63 PyAPI_FUNC(PyObject *) PyString_FromFormatV(const char*, va_list) |
|
64 Py_GCC_ATTRIBUTE((format(printf, 1, 0))); |
|
65 PyAPI_FUNC(PyObject *) PyString_FromFormat(const char*, ...) |
|
66 Py_GCC_ATTRIBUTE((format(printf, 1, 2))); |
|
67 PyAPI_FUNC(Py_ssize_t) PyString_Size(PyObject *); |
|
68 PyAPI_FUNC(char *) PyString_AsString(PyObject *); |
|
69 PyAPI_FUNC(PyObject *) PyString_Repr(PyObject *, int); |
|
70 PyAPI_FUNC(void) PyString_Concat(PyObject **, PyObject *); |
|
71 PyAPI_FUNC(void) PyString_ConcatAndDel(PyObject **, PyObject *); |
|
72 PyAPI_FUNC(int) _PyString_Resize(PyObject **, Py_ssize_t); |
|
73 PyAPI_FUNC(int) _PyString_Eq(PyObject *, PyObject*); |
|
74 PyAPI_FUNC(PyObject *) PyString_Format(PyObject *, PyObject *); |
|
75 PyAPI_FUNC(PyObject *) _PyString_FormatLong(PyObject*, int, int, |
|
76 int, char**, int*); |
|
77 PyAPI_FUNC(PyObject *) PyString_DecodeEscape(const char *, Py_ssize_t, |
|
78 const char *, Py_ssize_t, |
|
79 const char *); |
|
80 |
|
81 PyAPI_FUNC(void) PyString_InternInPlace(PyObject **); |
|
82 PyAPI_FUNC(void) PyString_InternImmortal(PyObject **); |
|
83 PyAPI_FUNC(PyObject *) PyString_InternFromString(const char *); |
|
84 PyAPI_FUNC(void) _Py_ReleaseInternedStrings(void); |
|
85 |
|
86 /* Use only if you know it's a string */ |
|
87 #define PyString_CHECK_INTERNED(op) (((PyStringObject *)(op))->ob_sstate) |
|
88 |
|
89 /* Macro, trading safety for speed */ |
|
90 #define PyString_AS_STRING(op) (((PyStringObject *)(op))->ob_sval) |
|
91 #define PyString_GET_SIZE(op) (((PyStringObject *)(op))->ob_size) |
|
92 |
|
93 /* _PyString_Join(sep, x) is like sep.join(x). sep must be PyStringObject*, |
|
94 x must be an iterable object. */ |
|
95 PyAPI_FUNC(PyObject *) _PyString_Join(PyObject *sep, PyObject *x); |
|
96 |
|
97 /* --- Generic Codecs ----------------------------------------------------- */ |
|
98 |
|
99 /* Create an object by decoding the encoded string s of the |
|
100 given size. */ |
|
101 |
|
102 PyAPI_FUNC(PyObject*) PyString_Decode( |
|
103 const char *s, /* encoded string */ |
|
104 Py_ssize_t size, /* size of buffer */ |
|
105 const char *encoding, /* encoding */ |
|
106 const char *errors /* error handling */ |
|
107 ); |
|
108 |
|
109 /* Encodes a char buffer of the given size and returns a |
|
110 Python object. */ |
|
111 |
|
112 PyAPI_FUNC(PyObject*) PyString_Encode( |
|
113 const char *s, /* string char buffer */ |
|
114 Py_ssize_t size, /* number of chars to encode */ |
|
115 const char *encoding, /* encoding */ |
|
116 const char *errors /* error handling */ |
|
117 ); |
|
118 |
|
119 /* Encodes a string object and returns the result as Python |
|
120 object. */ |
|
121 |
|
122 PyAPI_FUNC(PyObject*) PyString_AsEncodedObject( |
|
123 PyObject *str, /* string object */ |
|
124 const char *encoding, /* encoding */ |
|
125 const char *errors /* error handling */ |
|
126 ); |
|
127 |
|
128 /* Encodes a string object and returns the result as Python string |
|
129 object. |
|
130 |
|
131 If the codec returns an Unicode object, the object is converted |
|
132 back to a string using the default encoding. |
|
133 |
|
134 DEPRECATED - use PyString_AsEncodedObject() instead. */ |
|
135 |
|
136 PyAPI_FUNC(PyObject*) PyString_AsEncodedString( |
|
137 PyObject *str, /* string object */ |
|
138 const char *encoding, /* encoding */ |
|
139 const char *errors /* error handling */ |
|
140 ); |
|
141 |
|
142 /* Decodes a string object and returns the result as Python |
|
143 object. */ |
|
144 |
|
145 PyAPI_FUNC(PyObject*) PyString_AsDecodedObject( |
|
146 PyObject *str, /* string object */ |
|
147 const char *encoding, /* encoding */ |
|
148 const char *errors /* error handling */ |
|
149 ); |
|
150 |
|
151 /* Decodes a string object and returns the result as Python string |
|
152 object. |
|
153 |
|
154 If the codec returns an Unicode object, the object is converted |
|
155 back to a string using the default encoding. |
|
156 |
|
157 DEPRECATED - use PyString_AsDecodedObject() instead. */ |
|
158 |
|
159 PyAPI_FUNC(PyObject*) PyString_AsDecodedString( |
|
160 PyObject *str, /* string object */ |
|
161 const char *encoding, /* encoding */ |
|
162 const char *errors /* error handling */ |
|
163 ); |
|
164 |
|
165 /* Provides access to the internal data buffer and size of a string |
|
166 object or the default encoded version of an Unicode object. Passing |
|
167 NULL as *len parameter will force the string buffer to be |
|
168 0-terminated (passing a string with embedded NULL characters will |
|
169 cause an exception). */ |
|
170 |
|
171 PyAPI_FUNC(int) PyString_AsStringAndSize( |
|
172 register PyObject *obj, /* string or Unicode object */ |
|
173 register char **s, /* pointer to buffer variable */ |
|
174 register Py_ssize_t *len /* pointer to length variable or NULL |
|
175 (only possible for 0-terminated |
|
176 strings) */ |
|
177 ); |
|
178 |
|
179 |
|
180 #ifdef __cplusplus |
|
181 } |
|
182 #endif |
|
183 #endif /* !Py_STRINGOBJECT_H */ |