Commit | Line | Data |
---|---|---|
920dae64 AT |
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 *, int); | |
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(int) 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 **, int); | |
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 *, int, | |
78 | const char *, int, | |
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 | int 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 | int 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 int *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 */ |