Guido van Rossum | f70e43a | 1991-02-19 12:39:46 +0000 | [diff] [blame] | 1 | /*********************************************************** |
Guido van Rossum | fd71b9e | 2000-06-30 23:50:40 +0000 | [diff] [blame] | 2 | Copyright (c) 2000, BeOpen.com. |
| 3 | Copyright (c) 1995-2000, Corporation for National Research Initiatives. |
| 4 | Copyright (c) 1990-1995, Stichting Mathematisch Centrum. |
| 5 | All rights reserved. |
Guido van Rossum | f70e43a | 1991-02-19 12:39:46 +0000 | [diff] [blame] | 6 | |
Guido van Rossum | fd71b9e | 2000-06-30 23:50:40 +0000 | [diff] [blame] | 7 | See the file "Misc/COPYRIGHT" for information on usage and |
| 8 | redistribution of this file, and for a DISCLAIMER OF ALL WARRANTIES. |
Guido van Rossum | f70e43a | 1991-02-19 12:39:46 +0000 | [diff] [blame] | 9 | ******************************************************************/ |
| 10 | |
Guido van Rossum | 85a5fbb | 1990-10-14 12:07:46 +0000 | [diff] [blame] | 11 | /* String object interface */ |
| 12 | |
Fred Drake | 3cf4d2b | 2000-07-09 00:55:06 +0000 | [diff] [blame^] | 13 | #ifndef Py_STRINGOBJECT_H |
| 14 | #define Py_STRINGOBJECT_H |
| 15 | #ifdef __cplusplus |
| 16 | extern "C" { |
| 17 | #endif |
| 18 | |
Guido van Rossum | 85a5fbb | 1990-10-14 12:07:46 +0000 | [diff] [blame] | 19 | /* |
Guido van Rossum | caa6380 | 1995-01-12 11:45:45 +0000 | [diff] [blame] | 20 | Type PyStringObject represents a character string. An extra zero byte is |
Guido van Rossum | 85a5fbb | 1990-10-14 12:07:46 +0000 | [diff] [blame] | 21 | reserved at the end to ensure it is zero-terminated, but a size is |
| 22 | present so strings with null bytes in them can be represented. This |
| 23 | is an immutable object type. |
| 24 | |
| 25 | There are functions to create new string objects, to test |
| 26 | an object for string-ness, and to get the |
| 27 | string value. The latter function returns a null pointer |
| 28 | if the object is not of the proper type. |
| 29 | There is a variant that takes an explicit size as well as a |
| 30 | variant that assumes a zero-terminated string. Note that none of the |
| 31 | functions should be applied to nil objects. |
| 32 | */ |
| 33 | |
Guido van Rossum | 1e6e9a2 | 1997-01-18 07:53:23 +0000 | [diff] [blame] | 34 | /* Two speedup hacks. Caching the hash saves recalculation of a |
| 35 | string's hash value. Interning strings (which requires hash |
| 36 | caching) tries to ensure that only one string object with a given |
| 37 | value exists, so equality tests are one pointer comparison. |
| 38 | Together, these can speed the interpreter up by as much as 20%. |
| 39 | Each costs the size of a long or pointer per string object. In |
| 40 | addition, interned strings live until the end of times. If you are |
| 41 | concerned about memory footprint, simply comment the #define out |
| 42 | here (and rebuild everything!). */ |
Guido van Rossum | fdebf25 | 1996-07-30 16:42:03 +0000 | [diff] [blame] | 43 | #define CACHE_HASH |
Guido van Rossum | 1e6e9a2 | 1997-01-18 07:53:23 +0000 | [diff] [blame] | 44 | #ifdef CACHE_HASH |
| 45 | #define INTERN_STRINGS |
| 46 | #endif |
Guido van Rossum | fdebf25 | 1996-07-30 16:42:03 +0000 | [diff] [blame] | 47 | |
Guido van Rossum | 85a5fbb | 1990-10-14 12:07:46 +0000 | [diff] [blame] | 48 | typedef struct { |
Fred Drake | 3cf4d2b | 2000-07-09 00:55:06 +0000 | [diff] [blame^] | 49 | PyObject_VAR_HEAD |
Sjoerd Mullender | 3bb8a05 | 1993-10-22 12:04:32 +0000 | [diff] [blame] | 50 | #ifdef CACHE_HASH |
Fred Drake | 3cf4d2b | 2000-07-09 00:55:06 +0000 | [diff] [blame^] | 51 | long ob_shash; |
Sjoerd Mullender | 3bb8a05 | 1993-10-22 12:04:32 +0000 | [diff] [blame] | 52 | #endif |
Guido van Rossum | 1e6e9a2 | 1997-01-18 07:53:23 +0000 | [diff] [blame] | 53 | #ifdef INTERN_STRINGS |
Fred Drake | 3cf4d2b | 2000-07-09 00:55:06 +0000 | [diff] [blame^] | 54 | PyObject *ob_sinterned; |
Guido van Rossum | 1e6e9a2 | 1997-01-18 07:53:23 +0000 | [diff] [blame] | 55 | #endif |
Fred Drake | 3cf4d2b | 2000-07-09 00:55:06 +0000 | [diff] [blame^] | 56 | char ob_sval[1]; |
Guido van Rossum | caa6380 | 1995-01-12 11:45:45 +0000 | [diff] [blame] | 57 | } PyStringObject; |
Guido van Rossum | 85a5fbb | 1990-10-14 12:07:46 +0000 | [diff] [blame] | 58 | |
Guido van Rossum | 051ab12 | 1995-02-27 10:17:52 +0000 | [diff] [blame] | 59 | extern DL_IMPORT(PyTypeObject) PyString_Type; |
Guido van Rossum | 85a5fbb | 1990-10-14 12:07:46 +0000 | [diff] [blame] | 60 | |
Guido van Rossum | caa6380 | 1995-01-12 11:45:45 +0000 | [diff] [blame] | 61 | #define PyString_Check(op) ((op)->ob_type == &PyString_Type) |
Guido van Rossum | 85a5fbb | 1990-10-14 12:07:46 +0000 | [diff] [blame] | 62 | |
Fred Drake | 3cf4d2b | 2000-07-09 00:55:06 +0000 | [diff] [blame^] | 63 | extern DL_IMPORT(PyObject *) PyString_FromStringAndSize(const char *, int); |
| 64 | extern DL_IMPORT(PyObject *) PyString_FromString(const char *); |
| 65 | extern DL_IMPORT(int) PyString_Size(PyObject *); |
| 66 | extern DL_IMPORT(char *) PyString_AsString(PyObject *); |
| 67 | extern DL_IMPORT(void) PyString_Concat(PyObject **, PyObject *); |
| 68 | extern DL_IMPORT(void) PyString_ConcatAndDel(PyObject **, PyObject *); |
| 69 | extern DL_IMPORT(int) _PyString_Resize(PyObject **, int); |
| 70 | extern DL_IMPORT(PyObject *) PyString_Format(PyObject *, PyObject *); |
Guido van Rossum | 85a5fbb | 1990-10-14 12:07:46 +0000 | [diff] [blame] | 71 | |
Guido van Rossum | 1e6e9a2 | 1997-01-18 07:53:23 +0000 | [diff] [blame] | 72 | #ifdef INTERN_STRINGS |
Fred Drake | 3cf4d2b | 2000-07-09 00:55:06 +0000 | [diff] [blame^] | 73 | extern DL_IMPORT(void) PyString_InternInPlace(PyObject **); |
| 74 | extern DL_IMPORT(PyObject *) PyString_InternFromString(const char *); |
Guido van Rossum | 1e6e9a2 | 1997-01-18 07:53:23 +0000 | [diff] [blame] | 75 | #else |
| 76 | #define PyString_InternInPlace(p) |
| 77 | #define PyString_InternFromString(cp) PyString_FromString(cp) |
| 78 | #endif |
| 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 | |
Marc-André Lemburg | 3d1a1d7 | 2000-07-06 11:25:40 +0000 | [diff] [blame] | 84 | /* --- Generic Codecs ----------------------------------------------------- */ |
| 85 | |
| 86 | /* Create a string object by decoding the encoded string s of the |
| 87 | given size. */ |
| 88 | |
| 89 | extern DL_IMPORT(PyObject*) PyString_Decode( |
| 90 | const char *s, /* encoded string */ |
| 91 | int size, /* size of buffer */ |
| 92 | const char *encoding, /* encoding */ |
| 93 | const char *errors /* error handling */ |
| 94 | ); |
| 95 | |
| 96 | /* Encodes a char buffer of the given size and returns a |
| 97 | Python string object. */ |
| 98 | |
| 99 | extern DL_IMPORT(PyObject*) PyString_Encode( |
| 100 | const char *s, /* string char buffer */ |
| 101 | int size, /* number of chars to encode */ |
| 102 | const char *encoding, /* encoding */ |
| 103 | const char *errors /* error handling */ |
| 104 | ); |
| 105 | |
| 106 | /* Encodes a string object and returns the result as Python string |
| 107 | object. */ |
| 108 | |
| 109 | extern DL_IMPORT(PyObject*) PyString_AsEncodedString( |
| 110 | PyObject *str, /* string object */ |
| 111 | const char *encoding, /* encoding */ |
| 112 | const char *errors /* error handling */ |
| 113 | ); |
| 114 | |
Guido van Rossum | a330996 | 1993-07-28 09:05:47 +0000 | [diff] [blame] | 115 | #ifdef __cplusplus |
| 116 | } |
| 117 | #endif |
| 118 | #endif /* !Py_STRINGOBJECT_H */ |