|
| 1 | + |
| 2 | +/* Bytes (String) object interface */ |
| 3 | + |
| 4 | +#ifndef Py_BYTESOBJECT_H |
| 5 | +#define Py_BYTESOBJECT_H |
| 6 | +#ifdef __cplusplus |
| 7 | +extern "C" { |
| 8 | +#endif |
| 9 | + |
| 10 | +#include <stdarg.h> |
| 11 | + |
| 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. |
| 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 | + This significantly speeds up dict lookups. */ |
| 29 | + |
| 30 | +#ifndef Py_LIMITED_API |
| 31 | +typedef struct { |
| 32 | + PyObject_VAR_HEAD |
| 33 | + Py_hash_t ob_shash; |
| 34 | + char ob_sval[1]; |
| 35 | + |
| 36 | + /* Invariants: |
| 37 | + * ob_sval contains space for 'ob_size+1' elements. |
| 38 | + * ob_sval[ob_size] == 0. |
| 39 | + * ob_shash is the hash of the string or -1 if not computed yet. |
| 40 | + */ |
| 41 | +} PyBytesObject; |
| 42 | +#endif |
| 43 | + |
| 44 | +PyAPI_DATA(PyTypeObject) PyBytes_Type; |
| 45 | +PyAPI_DATA(PyTypeObject) PyBytesIter_Type; |
| 46 | + |
| 47 | +#define PyBytes_Check(op) \ |
| 48 | + PyType_FastSubclass(Py_TYPE(op), Py_TPFLAGS_BYTES_SUBCLASS) |
| 49 | +#define PyBytes_CheckExact(op) (Py_TYPE(op) == &PyBytes_Type) |
| 50 | + |
| 51 | +PyAPI_FUNC(PyObject *) PyBytes_FromStringAndSize(const char *, Py_ssize_t); |
| 52 | +PyAPI_FUNC(PyObject *) PyBytes_FromString(const char *); |
| 53 | +PyAPI_FUNC(PyObject *) PyBytes_FromObject(PyObject *); |
| 54 | +PyAPI_FUNC(PyObject *) PyBytes_FromFormatV(const char*, va_list) |
| 55 | + Py_GCC_ATTRIBUTE((format(printf, 1, 0))); |
| 56 | +PyAPI_FUNC(PyObject *) PyBytes_FromFormat(const char*, ...) |
| 57 | + Py_GCC_ATTRIBUTE((format(printf, 1, 2))); |
| 58 | +PyAPI_FUNC(Py_ssize_t) PyBytes_Size(PyObject *); |
| 59 | +PyAPI_FUNC(char *) PyBytes_AsString(PyObject *); |
| 60 | +PyAPI_FUNC(PyObject *) PyBytes_Repr(PyObject *, int); |
| 61 | +PyAPI_FUNC(void) PyBytes_Concat(PyObject **, PyObject *); |
| 62 | +PyAPI_FUNC(void) PyBytes_ConcatAndDel(PyObject **, PyObject *); |
| 63 | +#ifndef Py_LIMITED_API |
| 64 | +PyAPI_FUNC(int) _PyBytes_Resize(PyObject **, Py_ssize_t); |
| 65 | +PyAPI_FUNC(PyObject*) _PyBytes_FormatEx( |
| 66 | + const char *format, |
| 67 | + Py_ssize_t format_len, |
| 68 | + PyObject *args, |
| 69 | + int use_bytearray); |
| 70 | +PyAPI_FUNC(PyObject*) _PyBytes_FromHex( |
| 71 | + PyObject *string, |
| 72 | + int use_bytearray); |
| 73 | +#endif |
| 74 | +PyAPI_FUNC(PyObject *) PyBytes_DecodeEscape(const char *, Py_ssize_t, |
| 75 | + const char *, Py_ssize_t, |
| 76 | + const char *); |
| 77 | +#ifndef Py_LIMITED_API |
| 78 | +/* Helper for PyBytes_DecodeEscape that detects invalid escape chars. */ |
| 79 | +PyAPI_FUNC(PyObject *) _PyBytes_DecodeEscape(const char *, Py_ssize_t, |
| 80 | + const char *, Py_ssize_t, |
| 81 | + const char *, |
| 82 | + const char **); |
| 83 | +#endif |
| 84 | + |
| 85 | +/* Macro, trading safety for speed */ |
| 86 | +#ifndef Py_LIMITED_API |
| 87 | +#define PyBytes_AS_STRING(op) (assert(PyBytes_Check(op)), \ |
| 88 | + (((PyBytesObject *)(op))->ob_sval)) |
| 89 | +#define PyBytes_GET_SIZE(op) (assert(PyBytes_Check(op)),Py_SIZE(op)) |
| 90 | +#endif |
| 91 | + |
| 92 | +/* _PyBytes_Join(sep, x) is like sep.join(x). sep must be PyBytesObject*, |
| 93 | + x must be an iterable object. */ |
| 94 | +#ifndef Py_LIMITED_API |
| 95 | +PyAPI_FUNC(PyObject *) _PyBytes_Join(PyObject *sep, PyObject *x); |
| 96 | +#endif |
| 97 | + |
| 98 | +/* Provides access to the internal data buffer and size of a string |
| 99 | + object or the default encoded version of a Unicode object. Passing |
| 100 | + NULL as *len parameter will force the string buffer to be |
| 101 | + 0-terminated (passing a string with embedded NULL characters will |
| 102 | + cause an exception). */ |
| 103 | +PyAPI_FUNC(int) PyBytes_AsStringAndSize( |
| 104 | + PyObject *obj, /* string or Unicode object */ |
| 105 | + char **s, /* pointer to buffer variable */ |
| 106 | + Py_ssize_t *len /* pointer to length variable or NULL |
| 107 | + (only possible for 0-terminated |
| 108 | + strings) */ |
| 109 | + ); |
| 110 | + |
| 111 | +/* Using the current locale, insert the thousands grouping |
| 112 | + into the string pointed to by buffer. For the argument descriptions, |
| 113 | + see Objects/stringlib/localeutil.h */ |
| 114 | +#ifndef Py_LIMITED_API |
| 115 | +PyAPI_FUNC(Py_ssize_t) _PyBytes_InsertThousandsGroupingLocale(char *buffer, |
| 116 | + Py_ssize_t n_buffer, |
| 117 | + char *digits, |
| 118 | + Py_ssize_t n_digits, |
| 119 | + Py_ssize_t min_width); |
| 120 | + |
| 121 | +/* Using explicit passed-in values, insert the thousands grouping |
| 122 | + into the string pointed to by buffer. For the argument descriptions, |
| 123 | + see Objects/stringlib/localeutil.h */ |
| 124 | +PyAPI_FUNC(Py_ssize_t) _PyBytes_InsertThousandsGrouping(char *buffer, |
| 125 | + Py_ssize_t n_buffer, |
| 126 | + char *digits, |
| 127 | + Py_ssize_t n_digits, |
| 128 | + Py_ssize_t min_width, |
| 129 | + const char *grouping, |
| 130 | + const char *thousands_sep); |
| 131 | +#endif |
| 132 | + |
| 133 | +/* Flags used by string formatting */ |
| 134 | +#define F_LJUST (1<<0) |
| 135 | +#define F_SIGN (1<<1) |
| 136 | +#define F_BLANK (1<<2) |
| 137 | +#define F_ALT (1<<3) |
| 138 | +#define F_ZERO (1<<4) |
| 139 | + |
| 140 | +#ifndef Py_LIMITED_API |
| 141 | +/* The _PyBytesWriter structure is big: it contains an embedded "stack buffer". |
| 142 | + A _PyBytesWriter variable must be declared at the end of variables in a |
| 143 | + function to optimize the memory allocation on the stack. */ |
| 144 | +typedef struct { |
| 145 | + /* bytes, bytearray or NULL (when the small buffer is used) */ |
| 146 | + PyObject *buffer; |
| 147 | + |
| 148 | + /* Number of allocated size. */ |
| 149 | + Py_ssize_t allocated; |
| 150 | + |
| 151 | + /* Minimum number of allocated bytes, |
| 152 | + incremented by _PyBytesWriter_Prepare() */ |
| 153 | + Py_ssize_t min_size; |
| 154 | + |
| 155 | + /* If non-zero, use a bytearray instead of a bytes object for buffer. */ |
| 156 | + int use_bytearray; |
| 157 | + |
| 158 | + /* If non-zero, overallocate the buffer (default: 0). |
| 159 | + This flag must be zero if use_bytearray is non-zero. */ |
| 160 | + int overallocate; |
| 161 | + |
| 162 | + /* Stack buffer */ |
| 163 | + int use_small_buffer; |
| 164 | + char small_buffer[512]; |
| 165 | +} _PyBytesWriter; |
| 166 | + |
| 167 | +/* Initialize a bytes writer |
| 168 | +
|
| 169 | + By default, the overallocation is disabled. Set the overallocate attribute |
| 170 | + to control the allocation of the buffer. */ |
| 171 | +PyAPI_FUNC(void) _PyBytesWriter_Init(_PyBytesWriter *writer); |
| 172 | + |
| 173 | +/* Get the buffer content and reset the writer. |
| 174 | + Return a bytes object, or a bytearray object if use_bytearray is non-zero. |
| 175 | + Raise an exception and return NULL on error. */ |
| 176 | +PyAPI_FUNC(PyObject *) _PyBytesWriter_Finish(_PyBytesWriter *writer, |
| 177 | + void *str); |
| 178 | + |
| 179 | +/* Deallocate memory of a writer (clear its internal buffer). */ |
| 180 | +PyAPI_FUNC(void) _PyBytesWriter_Dealloc(_PyBytesWriter *writer); |
| 181 | + |
| 182 | +/* Allocate the buffer to write size bytes. |
| 183 | + Return the pointer to the beginning of buffer data. |
| 184 | + Raise an exception and return NULL on error. */ |
| 185 | +PyAPI_FUNC(void*) _PyBytesWriter_Alloc(_PyBytesWriter *writer, |
| 186 | + Py_ssize_t size); |
| 187 | + |
| 188 | +/* Ensure that the buffer is large enough to write *size* bytes. |
| 189 | + Add size to the writer minimum size (min_size attribute). |
| 190 | +
|
| 191 | + str is the current pointer inside the buffer. |
| 192 | + Return the updated current pointer inside the buffer. |
| 193 | + Raise an exception and return NULL on error. */ |
| 194 | +PyAPI_FUNC(void*) _PyBytesWriter_Prepare(_PyBytesWriter *writer, |
| 195 | + void *str, |
| 196 | + Py_ssize_t size); |
| 197 | + |
| 198 | +/* Resize the buffer to make it larger. |
| 199 | + The new buffer may be larger than size bytes because of overallocation. |
| 200 | + Return the updated current pointer inside the buffer. |
| 201 | + Raise an exception and return NULL on error. |
| 202 | +
|
| 203 | + Note: size must be greater than the number of allocated bytes in the writer. |
| 204 | +
|
| 205 | + This function doesn't use the writer minimum size (min_size attribute). |
| 206 | +
|
| 207 | + See also _PyBytesWriter_Prepare(). |
| 208 | + */ |
| 209 | +PyAPI_FUNC(void*) _PyBytesWriter_Resize(_PyBytesWriter *writer, |
| 210 | + void *str, |
| 211 | + Py_ssize_t size); |
| 212 | + |
| 213 | +/* Write bytes. |
| 214 | + Raise an exception and return NULL on error. */ |
| 215 | +PyAPI_FUNC(void*) _PyBytesWriter_WriteBytes(_PyBytesWriter *writer, |
| 216 | + void *str, |
| 217 | + const void *bytes, |
| 218 | + Py_ssize_t size); |
| 219 | +#endif /* Py_LIMITED_API */ |
| 220 | + |
| 221 | +#ifdef __cplusplus |
| 222 | +} |
| 223 | +#endif |
| 224 | +#endif /* !Py_BYTESOBJECT_H */ |
0 commit comments