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 181 /* Using the current locale, insert the thousands grouping 182 into the string pointed to by buffer. For the argument descriptions, 183 see Objects/stringlib/localeutil.h */ 184 PyAPI_FUNC(Py_ssize_t) _PyString_InsertThousandsGroupingLocale(char *buffer, 185 Py_ssize_t n_buffer, 186 char *digits, 187 Py_ssize_t n_digits, 188 Py_ssize_t min_width); 189 190 /* Using explicit passed-in values, insert the thousands grouping 191 into the string pointed to by buffer. For the argument descriptions, 192 see Objects/stringlib/localeutil.h */ 193 PyAPI_FUNC(Py_ssize_t) _PyString_InsertThousandsGrouping(char *buffer, 194 Py_ssize_t n_buffer, 195 char *digits, 196 Py_ssize_t n_digits, 197 Py_ssize_t min_width, 198 const char *grouping, 199 const char *thousands_sep); 200 201 /* Format the object based on the format_spec, as defined in PEP 3101 202 (Advanced String Formatting). */ 203 PyAPI_FUNC(PyObject *) _PyBytes_FormatAdvanced(PyObject *obj, 204 char *format_spec, 205 Py_ssize_t format_spec_len); 206 207 #ifdef __cplusplus 208 } 209 #endif 210 #endif /* !Py_STRINGOBJECT_H */ 211