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