Guido van Rossum | 4dfe8a1 | 2006-04-22 23:28:04 +0000 | [diff] [blame] | 1 | |
Georg Brandl | 0c77a82 | 2008-06-10 16:37:50 +0000 | [diff] [blame] | 2 | /* Bytes (String) object interface */ |
Christian Heimes | 2c9c7a5 | 2008-05-26 13:42:13 +0000 | [diff] [blame] | 3 | |
Georg Brandl | 0c77a82 | 2008-06-10 16:37:50 +0000 | [diff] [blame] | 4 | #ifndef Py_BYTESOBJECT_H |
| 5 | #define Py_BYTESOBJECT_H |
Guido van Rossum | 4dfe8a1 | 2006-04-22 23:28:04 +0000 | [diff] [blame] | 6 | #ifdef __cplusplus |
| 7 | extern "C" { |
| 8 | #endif |
| 9 | |
| 10 | #include <stdarg.h> |
| 11 | |
Christian Heimes | 2c9c7a5 | 2008-05-26 13:42:13 +0000 | [diff] [blame] | 12 | /* |
| 13 | Type PyBytesObject 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. |
Guido van Rossum | 4dfe8a1 | 2006-04-22 23:28:04 +0000 | [diff] [blame] | 17 | |
Christian Heimes | 2c9c7a5 | 2008-05-26 13:42:13 +0000 | [diff] [blame] | 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 | This significantly speeds up dict lookups. */ |
| 29 | |
Guido van Rossum | 4dfe8a1 | 2006-04-22 23:28:04 +0000 | [diff] [blame] | 30 | typedef struct { |
| 31 | PyObject_VAR_HEAD |
Christian Heimes | 2c9c7a5 | 2008-05-26 13:42:13 +0000 | [diff] [blame] | 32 | long ob_shash; |
| 33 | char ob_sval[1]; |
Guido van Rossum | 4dfe8a1 | 2006-04-22 23:28:04 +0000 | [diff] [blame] | 34 | |
Christian Heimes | 2c9c7a5 | 2008-05-26 13:42:13 +0000 | [diff] [blame] | 35 | /* Invariants: |
| 36 | * ob_sval contains space for 'ob_size+1' elements. |
| 37 | * ob_sval[ob_size] == 0. |
| 38 | * ob_shash is the hash of the string or -1 if not computed yet. |
| 39 | */ |
| 40 | } PyBytesObject; |
Guido van Rossum | 4dfe8a1 | 2006-04-22 23:28:04 +0000 | [diff] [blame] | 41 | |
Christian Heimes | 2c9c7a5 | 2008-05-26 13:42:13 +0000 | [diff] [blame] | 42 | PyAPI_DATA(PyTypeObject) PyBytes_Type; |
| 43 | PyAPI_DATA(PyTypeObject) PyBytesIter_Type; |
Guido van Rossum | 4dfe8a1 | 2006-04-22 23:28:04 +0000 | [diff] [blame] | 44 | |
Christian Heimes | 2c9c7a5 | 2008-05-26 13:42:13 +0000 | [diff] [blame] | 45 | #define PyBytes_Check(op) \ |
| 46 | PyType_FastSubclass(Py_TYPE(op), Py_TPFLAGS_BYTES_SUBCLASS) |
| 47 | #define PyBytes_CheckExact(op) (Py_TYPE(op) == &PyBytes_Type) |
Guido van Rossum | 4dfe8a1 | 2006-04-22 23:28:04 +0000 | [diff] [blame] | 48 | |
Christian Heimes | 2c9c7a5 | 2008-05-26 13:42:13 +0000 | [diff] [blame] | 49 | PyAPI_FUNC(PyObject *) PyBytes_FromStringAndSize(const char *, Py_ssize_t); |
| 50 | PyAPI_FUNC(PyObject *) PyBytes_FromString(const char *); |
| 51 | PyAPI_FUNC(PyObject *) PyBytes_FromFormatV(const char*, va_list) |
| 52 | Py_GCC_ATTRIBUTE((format(printf, 1, 0))); |
| 53 | PyAPI_FUNC(PyObject *) PyBytes_FromFormat(const char*, ...) |
| 54 | Py_GCC_ATTRIBUTE((format(printf, 1, 2))); |
| 55 | PyAPI_FUNC(Py_ssize_t) PyBytes_Size(PyObject *); |
| 56 | PyAPI_FUNC(char *) PyBytes_AsString(PyObject *); |
| 57 | PyAPI_FUNC(PyObject *) PyBytes_Repr(PyObject *, int); |
| 58 | PyAPI_FUNC(void) PyBytes_Concat(PyObject **, PyObject *); |
| 59 | PyAPI_FUNC(void) PyBytes_ConcatAndDel(PyObject **, PyObject *); |
| 60 | PyAPI_FUNC(int) _PyBytes_Resize(PyObject **, Py_ssize_t); |
Christian Heimes | 2c9c7a5 | 2008-05-26 13:42:13 +0000 | [diff] [blame] | 61 | PyAPI_FUNC(PyObject *) _PyBytes_FormatLong(PyObject*, int, int, |
| 62 | int, char**, int*); |
| 63 | PyAPI_FUNC(PyObject *) PyBytes_DecodeEscape(const char *, Py_ssize_t, |
| 64 | const char *, Py_ssize_t, |
| 65 | const char *); |
| 66 | |
| 67 | /* Macro, trading safety for speed */ |
| 68 | #define PyBytes_AS_STRING(op) (assert(PyBytes_Check(op)), \ |
| 69 | (((PyBytesObject *)(op))->ob_sval)) |
| 70 | #define PyBytes_GET_SIZE(op) (assert(PyBytes_Check(op)),Py_SIZE(op)) |
| 71 | |
| 72 | /* _PyBytes_Join(sep, x) is like sep.join(x). sep must be PyBytesObject*, |
| 73 | x must be an iterable object. */ |
| 74 | PyAPI_FUNC(PyObject *) _PyBytes_Join(PyObject *sep, PyObject *x); |
| 75 | |
| 76 | /* Provides access to the internal data buffer and size of a string |
| 77 | object or the default encoded version of an Unicode object. Passing |
| 78 | NULL as *len parameter will force the string buffer to be |
| 79 | 0-terminated (passing a string with embedded NULL characters will |
| 80 | cause an exception). */ |
| 81 | PyAPI_FUNC(int) PyBytes_AsStringAndSize( |
| 82 | register PyObject *obj, /* string or Unicode object */ |
| 83 | register char **s, /* pointer to buffer variable */ |
| 84 | register Py_ssize_t *len /* pointer to length variable or NULL |
| 85 | (only possible for 0-terminated |
| 86 | strings) */ |
| 87 | ); |
| 88 | |
| 89 | /* Using the current locale, insert the thousands grouping |
| 90 | into the string pointed to by buffer. For the argument descriptions, |
| 91 | see Objects/stringlib/localeutil.h */ |
| 92 | |
| 93 | PyAPI_FUNC(int) _PyBytes_InsertThousandsGrouping(char *buffer, |
| 94 | Py_ssize_t len, |
| 95 | char *plast, |
| 96 | Py_ssize_t buf_size, |
| 97 | Py_ssize_t *count, |
| 98 | int append_zero_char); |
| 99 | |
| 100 | /* Flags used by string formatting */ |
| 101 | #define F_LJUST (1<<0) |
| 102 | #define F_SIGN (1<<1) |
| 103 | #define F_BLANK (1<<2) |
| 104 | #define F_ALT (1<<3) |
| 105 | #define F_ZERO (1<<4) |
Guido van Rossum | 4dfe8a1 | 2006-04-22 23:28:04 +0000 | [diff] [blame] | 106 | |
| 107 | #ifdef __cplusplus |
| 108 | } |
| 109 | #endif |
Georg Brandl | 0c77a82 | 2008-06-10 16:37:50 +0000 | [diff] [blame] | 110 | #endif /* !Py_BYTESOBJECT_H */ |