Guido van Rossum | f70e43a | 1991-02-19 12:39:46 +0000 | [diff] [blame] | 1 | |
Guido van Rossum | 85a5fbb | 1990-10-14 12:07:46 +0000 | [diff] [blame] | 2 | /* String object interface */ |
| 3 | |
Fred Drake | 3cf4d2b | 2000-07-09 00:55:06 +0000 | [diff] [blame] | 4 | #ifndef Py_STRINGOBJECT_H |
| 5 | #define Py_STRINGOBJECT_H |
| 6 | #ifdef __cplusplus |
| 7 | extern "C" { |
| 8 | #endif |
| 9 | |
Guido van Rossum | 85a5fbb | 1990-10-14 12:07:46 +0000 | [diff] [blame] | 10 | /* |
Guido van Rossum | caa6380 | 1995-01-12 11:45:45 +0000 | [diff] [blame] | 11 | Type PyStringObject represents a character string. An extra zero byte is |
Guido van Rossum | 85a5fbb | 1990-10-14 12:07:46 +0000 | [diff] [blame] | 12 | reserved at the end to ensure it is zero-terminated, but a size is |
| 13 | present so strings with null bytes in them can be represented. This |
| 14 | is an immutable object type. |
| 15 | |
| 16 | There are functions to create new string objects, to test |
| 17 | an object for string-ness, and to get the |
| 18 | string value. The latter function returns a null pointer |
| 19 | if the object is not of the proper type. |
| 20 | There is a variant that takes an explicit size as well as a |
| 21 | variant that assumes a zero-terminated string. Note that none of the |
| 22 | functions should be applied to nil objects. |
| 23 | */ |
| 24 | |
Guido van Rossum | 1e6e9a2 | 1997-01-18 07:53:23 +0000 | [diff] [blame] | 25 | /* Two speedup hacks. Caching the hash saves recalculation of a |
| 26 | string's hash value. Interning strings (which requires hash |
| 27 | caching) tries to ensure that only one string object with a given |
| 28 | value exists, so equality tests are one pointer comparison. |
| 29 | Together, these can speed the interpreter up by as much as 20%. |
| 30 | Each costs the size of a long or pointer per string object. In |
| 31 | addition, interned strings live until the end of times. If you are |
| 32 | concerned about memory footprint, simply comment the #define out |
| 33 | here (and rebuild everything!). */ |
Guido van Rossum | fdebf25 | 1996-07-30 16:42:03 +0000 | [diff] [blame] | 34 | #define CACHE_HASH |
Guido van Rossum | 1e6e9a2 | 1997-01-18 07:53:23 +0000 | [diff] [blame] | 35 | #ifdef CACHE_HASH |
| 36 | #define INTERN_STRINGS |
| 37 | #endif |
Guido van Rossum | fdebf25 | 1996-07-30 16:42:03 +0000 | [diff] [blame] | 38 | |
Guido van Rossum | 85a5fbb | 1990-10-14 12:07:46 +0000 | [diff] [blame] | 39 | typedef struct { |
Fred Drake | 3cf4d2b | 2000-07-09 00:55:06 +0000 | [diff] [blame] | 40 | PyObject_VAR_HEAD |
Sjoerd Mullender | 3bb8a05 | 1993-10-22 12:04:32 +0000 | [diff] [blame] | 41 | #ifdef CACHE_HASH |
Fred Drake | 3cf4d2b | 2000-07-09 00:55:06 +0000 | [diff] [blame] | 42 | long ob_shash; |
Sjoerd Mullender | 3bb8a05 | 1993-10-22 12:04:32 +0000 | [diff] [blame] | 43 | #endif |
Guido van Rossum | 1e6e9a2 | 1997-01-18 07:53:23 +0000 | [diff] [blame] | 44 | #ifdef INTERN_STRINGS |
Fred Drake | 3cf4d2b | 2000-07-09 00:55:06 +0000 | [diff] [blame] | 45 | PyObject *ob_sinterned; |
Guido van Rossum | 1e6e9a2 | 1997-01-18 07:53:23 +0000 | [diff] [blame] | 46 | #endif |
Fred Drake | 3cf4d2b | 2000-07-09 00:55:06 +0000 | [diff] [blame] | 47 | char ob_sval[1]; |
Guido van Rossum | caa6380 | 1995-01-12 11:45:45 +0000 | [diff] [blame] | 48 | } PyStringObject; |
Guido van Rossum | 85a5fbb | 1990-10-14 12:07:46 +0000 | [diff] [blame] | 49 | |
Guido van Rossum | 051ab12 | 1995-02-27 10:17:52 +0000 | [diff] [blame] | 50 | extern DL_IMPORT(PyTypeObject) PyString_Type; |
Guido van Rossum | 85a5fbb | 1990-10-14 12:07:46 +0000 | [diff] [blame] | 51 | |
Guido van Rossum | caa6380 | 1995-01-12 11:45:45 +0000 | [diff] [blame] | 52 | #define PyString_Check(op) ((op)->ob_type == &PyString_Type) |
Guido van Rossum | 85a5fbb | 1990-10-14 12:07:46 +0000 | [diff] [blame] | 53 | |
Fred Drake | 3cf4d2b | 2000-07-09 00:55:06 +0000 | [diff] [blame] | 54 | extern DL_IMPORT(PyObject *) PyString_FromStringAndSize(const char *, int); |
| 55 | extern DL_IMPORT(PyObject *) PyString_FromString(const char *); |
| 56 | extern DL_IMPORT(int) PyString_Size(PyObject *); |
| 57 | extern DL_IMPORT(char *) PyString_AsString(PyObject *); |
| 58 | extern DL_IMPORT(void) PyString_Concat(PyObject **, PyObject *); |
| 59 | extern DL_IMPORT(void) PyString_ConcatAndDel(PyObject **, PyObject *); |
| 60 | extern DL_IMPORT(int) _PyString_Resize(PyObject **, int); |
Martin v. Löwis | cd35306 | 2001-05-24 16:56:35 +0000 | [diff] [blame^] | 61 | extern DL_IMPORT(int) _PyString_Eq(PyObject *, PyObject*); |
Fred Drake | 3cf4d2b | 2000-07-09 00:55:06 +0000 | [diff] [blame] | 62 | extern DL_IMPORT(PyObject *) PyString_Format(PyObject *, PyObject *); |
Tim Peters | 38fd5b6 | 2000-09-21 05:43:11 +0000 | [diff] [blame] | 63 | extern DL_IMPORT(PyObject *) _PyString_FormatLong(PyObject*, int, int, |
| 64 | int, char**, int*); |
Guido van Rossum | 85a5fbb | 1990-10-14 12:07:46 +0000 | [diff] [blame] | 65 | |
Guido van Rossum | 1e6e9a2 | 1997-01-18 07:53:23 +0000 | [diff] [blame] | 66 | #ifdef INTERN_STRINGS |
Fred Drake | 3cf4d2b | 2000-07-09 00:55:06 +0000 | [diff] [blame] | 67 | extern DL_IMPORT(void) PyString_InternInPlace(PyObject **); |
| 68 | extern DL_IMPORT(PyObject *) PyString_InternFromString(const char *); |
Barry Warsaw | a903ad98 | 2001-02-23 16:40:48 +0000 | [diff] [blame] | 69 | extern DL_IMPORT(void) _Py_ReleaseInternedStrings(void); |
Guido van Rossum | 1e6e9a2 | 1997-01-18 07:53:23 +0000 | [diff] [blame] | 70 | #else |
| 71 | #define PyString_InternInPlace(p) |
| 72 | #define PyString_InternFromString(cp) PyString_FromString(cp) |
Barry Warsaw | a903ad98 | 2001-02-23 16:40:48 +0000 | [diff] [blame] | 73 | #define _Py_ReleaseInternedStrings() |
Guido van Rossum | 1e6e9a2 | 1997-01-18 07:53:23 +0000 | [diff] [blame] | 74 | #endif |
| 75 | |
Guido van Rossum | 85a5fbb | 1990-10-14 12:07:46 +0000 | [diff] [blame] | 76 | /* Macro, trading safety for speed */ |
Barry Warsaw | accfb84 | 1997-01-06 22:42:50 +0000 | [diff] [blame] | 77 | #define PyString_AS_STRING(op) (((PyStringObject *)(op))->ob_sval) |
| 78 | #define PyString_GET_SIZE(op) (((PyStringObject *)(op))->ob_size) |
Guido van Rossum | a330996 | 1993-07-28 09:05:47 +0000 | [diff] [blame] | 79 | |
Marc-André Lemburg | 3d1a1d7 | 2000-07-06 11:25:40 +0000 | [diff] [blame] | 80 | /* --- Generic Codecs ----------------------------------------------------- */ |
| 81 | |
Marc-André Lemburg | 2d92041 | 2001-05-15 12:00:02 +0000 | [diff] [blame] | 82 | /* Create an object by decoding the encoded string s of the |
Marc-André Lemburg | 3d1a1d7 | 2000-07-06 11:25:40 +0000 | [diff] [blame] | 83 | given size. */ |
| 84 | |
| 85 | extern DL_IMPORT(PyObject*) PyString_Decode( |
| 86 | const char *s, /* encoded string */ |
| 87 | int size, /* size of buffer */ |
| 88 | const char *encoding, /* encoding */ |
| 89 | const char *errors /* error handling */ |
| 90 | ); |
| 91 | |
| 92 | /* Encodes a char buffer of the given size and returns a |
Marc-André Lemburg | 2d92041 | 2001-05-15 12:00:02 +0000 | [diff] [blame] | 93 | Python object. */ |
Marc-André Lemburg | 3d1a1d7 | 2000-07-06 11:25:40 +0000 | [diff] [blame] | 94 | |
| 95 | extern DL_IMPORT(PyObject*) PyString_Encode( |
| 96 | const char *s, /* string char buffer */ |
| 97 | int size, /* number of chars to encode */ |
| 98 | const char *encoding, /* encoding */ |
| 99 | const char *errors /* error handling */ |
| 100 | ); |
| 101 | |
Marc-André Lemburg | 2d92041 | 2001-05-15 12:00:02 +0000 | [diff] [blame] | 102 | /* Encodes a string object and returns the result as Python |
Marc-André Lemburg | 3d1a1d7 | 2000-07-06 11:25:40 +0000 | [diff] [blame] | 103 | object. */ |
| 104 | |
Marc-André Lemburg | 2d92041 | 2001-05-15 12:00:02 +0000 | [diff] [blame] | 105 | extern DL_IMPORT(PyObject*) PyString_AsEncodedObject( |
| 106 | PyObject *str, /* string object */ |
| 107 | const char *encoding, /* encoding */ |
| 108 | const char *errors /* error handling */ |
| 109 | ); |
| 110 | |
| 111 | /* Encodes a string object and returns the result as Python string |
| 112 | object. |
| 113 | |
| 114 | If the codec returns an Unicode object, the object is converted |
| 115 | back to a string using the default encoding. |
| 116 | |
| 117 | DEPRECATED - use PyString_AsEncodedObject() instead. */ |
| 118 | |
Marc-André Lemburg | 3d1a1d7 | 2000-07-06 11:25:40 +0000 | [diff] [blame] | 119 | extern DL_IMPORT(PyObject*) PyString_AsEncodedString( |
| 120 | PyObject *str, /* string object */ |
| 121 | const char *encoding, /* encoding */ |
| 122 | const char *errors /* error handling */ |
| 123 | ); |
| 124 | |
Marc-André Lemburg | 2d92041 | 2001-05-15 12:00:02 +0000 | [diff] [blame] | 125 | /* Decodes a string object and returns the result as Python |
| 126 | object. */ |
| 127 | |
| 128 | extern DL_IMPORT(PyObject*) PyString_AsDecodedObject( |
| 129 | PyObject *str, /* string object */ |
| 130 | const char *encoding, /* encoding */ |
| 131 | const char *errors /* error handling */ |
| 132 | ); |
| 133 | |
| 134 | /* Decodes a string object and returns the result as Python string |
| 135 | object. |
| 136 | |
| 137 | If the codec returns an Unicode object, the object is converted |
| 138 | back to a string using the default encoding. |
| 139 | |
| 140 | DEPRECATED - use PyString_AsDecodedObject() instead. */ |
| 141 | |
| 142 | extern DL_IMPORT(PyObject*) PyString_AsDecodedString( |
| 143 | PyObject *str, /* string object */ |
| 144 | const char *encoding, /* encoding */ |
| 145 | const char *errors /* error handling */ |
| 146 | ); |
| 147 | |
Marc-André Lemburg | d1ba443 | 2000-09-19 21:04:18 +0000 | [diff] [blame] | 148 | /* Provides access to the internal data buffer and size of a string |
| 149 | object or the default encoded version of an Unicode object. Passing |
| 150 | NULL as *len parameter will force the string buffer to be |
| 151 | 0-terminated (passing a string with embedded NULL characters will |
| 152 | cause an exception). */ |
| 153 | |
| 154 | extern DL_IMPORT(int) PyString_AsStringAndSize( |
| 155 | register PyObject *obj, /* string or Unicode object */ |
| 156 | register char **s, /* pointer to buffer variable */ |
| 157 | register int *len /* pointer to length variable or NULL |
| 158 | (only possible for 0-terminated |
| 159 | strings) */ |
| 160 | ); |
| 161 | |
| 162 | |
Guido van Rossum | a330996 | 1993-07-28 09:05:47 +0000 | [diff] [blame] | 163 | #ifdef __cplusplus |
| 164 | } |
| 165 | #endif |
| 166 | #endif /* !Py_STRINGOBJECT_H */ |