Mercurial > repos > rliterman > csp2

annotate CSP2/CSP2_env/env-d9b9114564458d9d-741b3de822f2aaca6c6caa4325c4afce/include/python3.8/bytesobject.h @ 69:33d812a61356

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