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 | |
Barry Warsaw | dadace0 | 2001-08-24 18:32:06 +0000 | [diff] [blame] | 10 | #include <stdarg.h> |
| 11 | |
Guido van Rossum | 85a5fbb | 1990-10-14 12:07:46 +0000 | [diff] [blame] | 12 | /* |
Guido van Rossum | caa6380 | 1995-01-12 11:45:45 +0000 | [diff] [blame] | 13 | Type PyStringObject represents a character string. An extra zero byte is |
Guido van Rossum | 85a5fbb | 1990-10-14 12:07:46 +0000 | [diff] [blame] | 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 | |
Tim Peters | 1f7df35 | 2002-03-29 03:29:08 +0000 | [diff] [blame] | 27 | /* Caching the hash (ob_shash) saves recalculation of a string's hash value. |
Guido van Rossum | 45ec02a | 2002-08-19 21:43:18 +0000 | [diff] [blame] | 28 | Interning strings (ob_sstate) tries to ensure that only one string |
Tim Peters | 1f7df35 | 2002-03-29 03:29:08 +0000 | [diff] [blame] | 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%. */ |
Guido van Rossum | fdebf25 | 1996-07-30 16:42:03 +0000 | [diff] [blame] | 34 | |
Guido van Rossum | 85a5fbb | 1990-10-14 12:07:46 +0000 | [diff] [blame] | 35 | typedef struct { |
Fred Drake | 3cf4d2b | 2000-07-09 00:55:06 +0000 | [diff] [blame] | 36 | PyObject_VAR_HEAD |
Fred Drake | 3cf4d2b | 2000-07-09 00:55:06 +0000 | [diff] [blame] | 37 | long ob_shash; |
Guido van Rossum | 45ec02a | 2002-08-19 21:43:18 +0000 | [diff] [blame] | 38 | int ob_sstate; |
Fred Drake | 3cf4d2b | 2000-07-09 00:55:06 +0000 | [diff] [blame] | 39 | char ob_sval[1]; |
Guido van Rossum | caa6380 | 1995-01-12 11:45:45 +0000 | [diff] [blame] | 40 | } PyStringObject; |
Guido van Rossum | 85a5fbb | 1990-10-14 12:07:46 +0000 | [diff] [blame] | 41 | |
Guido van Rossum | 45ec02a | 2002-08-19 21:43:18 +0000 | [diff] [blame] | 42 | #define SSTATE_NOT_INTERNED 0 |
| 43 | #define SSTATE_INTERNED_MORTAL 1 |
| 44 | #define SSTATE_INTERNED_IMMORTAL 2 |
| 45 | |
Mark Hammond | 91a681d | 2002-08-12 07:21:58 +0000 | [diff] [blame] | 46 | PyAPI_DATA(PyTypeObject) PyBaseString_Type; |
| 47 | PyAPI_DATA(PyTypeObject) PyString_Type; |
Guido van Rossum | 85a5fbb | 1990-10-14 12:07:46 +0000 | [diff] [blame] | 48 | |
Guido van Rossum | 5eef77a | 2001-08-30 03:08:07 +0000 | [diff] [blame] | 49 | #define PyString_Check(op) PyObject_TypeCheck(op, &PyString_Type) |
Tim Peters | 5a49ade | 2001-09-11 01:41:59 +0000 | [diff] [blame] | 50 | #define PyString_CheckExact(op) ((op)->ob_type == &PyString_Type) |
Guido van Rossum | 85a5fbb | 1990-10-14 12:07:46 +0000 | [diff] [blame] | 51 | |
Mark Hammond | 91a681d | 2002-08-12 07:21:58 +0000 | [diff] [blame] | 52 | PyAPI_FUNC(PyObject *) PyString_FromStringAndSize(const char *, int); |
| 53 | PyAPI_FUNC(PyObject *) PyString_FromString(const char *); |
| 54 | PyAPI_FUNC(PyObject *) PyString_FromFormatV(const char*, va_list) |
Neil Schemenauer | 90b6890 | 2001-10-23 02:21:22 +0000 | [diff] [blame] | 55 | __attribute__((format(printf, 1, 0))); |
Mark Hammond | 91a681d | 2002-08-12 07:21:58 +0000 | [diff] [blame] | 56 | PyAPI_FUNC(PyObject *) PyString_FromFormat(const char*, ...) |
Neil Schemenauer | 90b6890 | 2001-10-23 02:21:22 +0000 | [diff] [blame] | 57 | __attribute__((format(printf, 1, 2))); |
Mark Hammond | 91a681d | 2002-08-12 07:21:58 +0000 | [diff] [blame] | 58 | PyAPI_FUNC(int) PyString_Size(PyObject *); |
| 59 | PyAPI_FUNC(char *) PyString_AsString(PyObject *); |
Martin v. Löwis | 8a8da79 | 2002-08-14 07:46:28 +0000 | [diff] [blame] | 60 | PyAPI_FUNC(PyObject *) PyString_Repr(PyObject *, int); |
Mark Hammond | 91a681d | 2002-08-12 07:21:58 +0000 | [diff] [blame] | 61 | PyAPI_FUNC(void) PyString_Concat(PyObject **, PyObject *); |
| 62 | PyAPI_FUNC(void) PyString_ConcatAndDel(PyObject **, PyObject *); |
| 63 | PyAPI_FUNC(int) _PyString_Resize(PyObject **, int); |
| 64 | PyAPI_FUNC(int) _PyString_Eq(PyObject *, PyObject*); |
| 65 | PyAPI_FUNC(PyObject *) PyString_Format(PyObject *, PyObject *); |
| 66 | PyAPI_FUNC(PyObject *) _PyString_FormatLong(PyObject*, int, int, |
Tim Peters | 38fd5b6 | 2000-09-21 05:43:11 +0000 | [diff] [blame] | 67 | int, char**, int*); |
Martin v. Löwis | 8a8da79 | 2002-08-14 07:46:28 +0000 | [diff] [blame] | 68 | extern DL_IMPORT(PyObject *) PyString_DecodeEscape(const char *, int, |
| 69 | const char *, int, |
| 70 | const char *); |
Guido van Rossum | 85a5fbb | 1990-10-14 12:07:46 +0000 | [diff] [blame] | 71 | |
Mark Hammond | 91a681d | 2002-08-12 07:21:58 +0000 | [diff] [blame] | 72 | PyAPI_FUNC(void) PyString_InternInPlace(PyObject **); |
Guido van Rossum | 45ec02a | 2002-08-19 21:43:18 +0000 | [diff] [blame] | 73 | PyAPI_FUNC(void) PyString_InternImmortal(PyObject **); |
Mark Hammond | 91a681d | 2002-08-12 07:21:58 +0000 | [diff] [blame] | 74 | PyAPI_FUNC(PyObject *) PyString_InternFromString(const char *); |
| 75 | PyAPI_FUNC(void) _Py_ReleaseInternedStrings(void); |
Guido van Rossum | 1e6e9a2 | 1997-01-18 07:53:23 +0000 | [diff] [blame] | 76 | |
Guido van Rossum | 45ec02a | 2002-08-19 21:43:18 +0000 | [diff] [blame] | 77 | /* Use only if you know it's a string */ |
| 78 | #define PyString_CHECK_INTERNED(op) (((PyStringObject *)(op))->ob_sstate) |
| 79 | |
Guido van Rossum | 85a5fbb | 1990-10-14 12:07:46 +0000 | [diff] [blame] | 80 | /* Macro, trading safety for speed */ |
Barry Warsaw | accfb84 | 1997-01-06 22:42:50 +0000 | [diff] [blame] | 81 | #define PyString_AS_STRING(op) (((PyStringObject *)(op))->ob_sval) |
| 82 | #define PyString_GET_SIZE(op) (((PyStringObject *)(op))->ob_size) |
Guido van Rossum | a330996 | 1993-07-28 09:05:47 +0000 | [diff] [blame] | 83 | |
Tim Peters | a725959 | 2001-06-16 05:11:17 +0000 | [diff] [blame] | 84 | /* _PyString_Join(sep, x) is like sep.join(x). sep must be PyStringObject*, |
| 85 | x must be an iterable object. */ |
Mark Hammond | 91a681d | 2002-08-12 07:21:58 +0000 | [diff] [blame] | 86 | PyAPI_FUNC(PyObject *) _PyString_Join(PyObject *sep, PyObject *x); |
Tim Peters | a725959 | 2001-06-16 05:11:17 +0000 | [diff] [blame] | 87 | |
Marc-André Lemburg | 3d1a1d7 | 2000-07-06 11:25:40 +0000 | [diff] [blame] | 88 | /* --- Generic Codecs ----------------------------------------------------- */ |
| 89 | |
Marc-André Lemburg | 2d92041 | 2001-05-15 12:00:02 +0000 | [diff] [blame] | 90 | /* Create an object by decoding the encoded string s of the |
Marc-André Lemburg | 3d1a1d7 | 2000-07-06 11:25:40 +0000 | [diff] [blame] | 91 | given size. */ |
| 92 | |
Mark Hammond | 91a681d | 2002-08-12 07:21:58 +0000 | [diff] [blame] | 93 | PyAPI_FUNC(PyObject*) PyString_Decode( |
Marc-André Lemburg | 3d1a1d7 | 2000-07-06 11:25:40 +0000 | [diff] [blame] | 94 | const char *s, /* encoded string */ |
| 95 | int size, /* size of buffer */ |
| 96 | const char *encoding, /* encoding */ |
| 97 | const char *errors /* error handling */ |
| 98 | ); |
| 99 | |
| 100 | /* Encodes a char buffer of the given size and returns a |
Marc-André Lemburg | 2d92041 | 2001-05-15 12:00:02 +0000 | [diff] [blame] | 101 | Python object. */ |
Marc-André Lemburg | 3d1a1d7 | 2000-07-06 11:25:40 +0000 | [diff] [blame] | 102 | |
Mark Hammond | 91a681d | 2002-08-12 07:21:58 +0000 | [diff] [blame] | 103 | PyAPI_FUNC(PyObject*) PyString_Encode( |
Marc-André Lemburg | 3d1a1d7 | 2000-07-06 11:25:40 +0000 | [diff] [blame] | 104 | const char *s, /* string char buffer */ |
| 105 | int size, /* number of chars to encode */ |
| 106 | const char *encoding, /* encoding */ |
| 107 | const char *errors /* error handling */ |
| 108 | ); |
| 109 | |
Marc-André Lemburg | 2d92041 | 2001-05-15 12:00:02 +0000 | [diff] [blame] | 110 | /* Encodes a string object and returns the result as Python |
Marc-André Lemburg | 3d1a1d7 | 2000-07-06 11:25:40 +0000 | [diff] [blame] | 111 | object. */ |
| 112 | |
Mark Hammond | 91a681d | 2002-08-12 07:21:58 +0000 | [diff] [blame] | 113 | PyAPI_FUNC(PyObject*) PyString_AsEncodedObject( |
Marc-André Lemburg | 2d92041 | 2001-05-15 12:00:02 +0000 | [diff] [blame] | 114 | PyObject *str, /* string object */ |
| 115 | const char *encoding, /* encoding */ |
| 116 | const char *errors /* error handling */ |
| 117 | ); |
| 118 | |
| 119 | /* Encodes a string object and returns the result as Python string |
| 120 | object. |
| 121 | |
| 122 | If the codec returns an Unicode object, the object is converted |
| 123 | back to a string using the default encoding. |
| 124 | |
| 125 | DEPRECATED - use PyString_AsEncodedObject() instead. */ |
| 126 | |
Mark Hammond | 91a681d | 2002-08-12 07:21:58 +0000 | [diff] [blame] | 127 | PyAPI_FUNC(PyObject*) PyString_AsEncodedString( |
Marc-André Lemburg | 3d1a1d7 | 2000-07-06 11:25:40 +0000 | [diff] [blame] | 128 | PyObject *str, /* string object */ |
| 129 | const char *encoding, /* encoding */ |
| 130 | const char *errors /* error handling */ |
| 131 | ); |
| 132 | |
Marc-André Lemburg | 2d92041 | 2001-05-15 12:00:02 +0000 | [diff] [blame] | 133 | /* Decodes a string object and returns the result as Python |
| 134 | object. */ |
| 135 | |
Mark Hammond | 91a681d | 2002-08-12 07:21:58 +0000 | [diff] [blame] | 136 | PyAPI_FUNC(PyObject*) PyString_AsDecodedObject( |
Marc-André Lemburg | 2d92041 | 2001-05-15 12:00:02 +0000 | [diff] [blame] | 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 string |
| 143 | object. |
| 144 | |
| 145 | If the codec returns an Unicode object, the object is converted |
| 146 | back to a string using the default encoding. |
| 147 | |
| 148 | DEPRECATED - use PyString_AsDecodedObject() instead. */ |
| 149 | |
Mark Hammond | 91a681d | 2002-08-12 07:21:58 +0000 | [diff] [blame] | 150 | PyAPI_FUNC(PyObject*) PyString_AsDecodedString( |
Marc-André Lemburg | 2d92041 | 2001-05-15 12:00:02 +0000 | [diff] [blame] | 151 | PyObject *str, /* string object */ |
| 152 | const char *encoding, /* encoding */ |
| 153 | const char *errors /* error handling */ |
| 154 | ); |
| 155 | |
Marc-André Lemburg | d1ba443 | 2000-09-19 21:04:18 +0000 | [diff] [blame] | 156 | /* Provides access to the internal data buffer and size of a string |
| 157 | object or the default encoded version of an Unicode object. Passing |
| 158 | NULL as *len parameter will force the string buffer to be |
| 159 | 0-terminated (passing a string with embedded NULL characters will |
| 160 | cause an exception). */ |
| 161 | |
Mark Hammond | 91a681d | 2002-08-12 07:21:58 +0000 | [diff] [blame] | 162 | PyAPI_FUNC(int) PyString_AsStringAndSize( |
Marc-André Lemburg | d1ba443 | 2000-09-19 21:04:18 +0000 | [diff] [blame] | 163 | register PyObject *obj, /* string or Unicode object */ |
| 164 | register char **s, /* pointer to buffer variable */ |
| 165 | register int *len /* pointer to length variable or NULL |
| 166 | (only possible for 0-terminated |
| 167 | strings) */ |
| 168 | ); |
| 169 | |
| 170 | |
Guido van Rossum | a330996 | 1993-07-28 09:05:47 +0000 | [diff] [blame] | 171 | #ifdef __cplusplus |
| 172 | } |
| 173 | #endif |
| 174 | #endif /* !Py_STRINGOBJECT_H */ |