python3.12/cpython/bytesobject.h

0001 #ifndef Py_CPYTHON_BYTESOBJECT_H
0002 #  error "this header file must not be included directly"
0003 #endif
0004
0005 typedef struct {
0006     PyObject_VAR_HEAD
0007     Py_DEPRECATED(3.11) Py_hash_t ob_shash;
0008     char ob_sval[1];
0009
0010     /* Invariants:
0011      *     ob_sval contains space for 'ob_size+1' elements.
0012      *     ob_sval[ob_size] == 0.
0013      *     ob_shash is the hash of the byte string or -1 if not computed yet.
0014      */
0015 } PyBytesObject;
0016
0017 PyAPI_FUNC(int) _PyBytes_Resize(PyObject **, Py_ssize_t);
0018 PyAPI_FUNC(PyObject*) _PyBytes_FormatEx(
0019     const char *format,
0020     Py_ssize_t format_len,
0021     PyObject *args,
0022     int use_bytearray);
0023 PyAPI_FUNC(PyObject*) _PyBytes_FromHex(
0024     PyObject *string,
0025     int use_bytearray);
0026
0027 /* Helper for PyBytes_DecodeEscape that detects invalid escape chars. */
0028 PyAPI_FUNC(PyObject *) _PyBytes_DecodeEscape(const char *, Py_ssize_t,
0029                                              const char *, const char **);
0030
0031 /* Macros and static inline functions, trading safety for speed */
0032 #define _PyBytes_CAST(op) \
0033     (assert(PyBytes_Check(op)), _Py_CAST(PyBytesObject*, op))
0034
0035 static inline char* PyBytes_AS_STRING(PyObject *op)
0036 {
0037     return _PyBytes_CAST(op)->ob_sval;
0038 }
0039 #define PyBytes_AS_STRING(op) PyBytes_AS_STRING(_PyObject_CAST(op))
0040
0041 static inline Py_ssize_t PyBytes_GET_SIZE(PyObject *op) {
0042     PyBytesObject *self = _PyBytes_CAST(op);
0043     return Py_SIZE(self);
0044 }
0045 #define PyBytes_GET_SIZE(self) PyBytes_GET_SIZE(_PyObject_CAST(self))
0046
0047 /* _PyBytes_Join(sep, x) is like sep.join(x).  sep must be PyBytesObject*,
0048    x must be an iterable object. */
0049 PyAPI_FUNC(PyObject *) _PyBytes_Join(PyObject *sep, PyObject *x);
0050
0051
0052 /* The _PyBytesWriter structure is big: it contains an embedded "stack buffer".
0053    A _PyBytesWriter variable must be declared at the end of variables in a
0054    function to optimize the memory allocation on the stack. */
0055 typedef struct {
0056     /* bytes, bytearray or NULL (when the small buffer is used) */
0057     PyObject *buffer;
0058
0059     /* Number of allocated size. */
0060     Py_ssize_t allocated;
0061
0062     /* Minimum number of allocated bytes,
0063        incremented by _PyBytesWriter_Prepare() */
0064     Py_ssize_t min_size;
0065
0066     /* If non-zero, use a bytearray instead of a bytes object for buffer. */
0067     int use_bytearray;
0068
0069     /* If non-zero, overallocate the buffer (default: 0).
0070        This flag must be zero if use_bytearray is non-zero. */
0071     int overallocate;
0072
0073     /* Stack buffer */
0074     int use_small_buffer;
0075     char small_buffer[512];
0076 } _PyBytesWriter;
0077
0078 /* Initialize a bytes writer
0079
0080    By default, the overallocation is disabled. Set the overallocate attribute
0081    to control the allocation of the buffer. */
0082 PyAPI_FUNC(void) _PyBytesWriter_Init(_PyBytesWriter *writer);
0083
0084 /* Get the buffer content and reset the writer.
0085    Return a bytes object, or a bytearray object if use_bytearray is non-zero.
0086    Raise an exception and return NULL on error. */
0087 PyAPI_FUNC(PyObject *) _PyBytesWriter_Finish(_PyBytesWriter *writer,
0088     void *str);
0089
0090 /* Deallocate memory of a writer (clear its internal buffer). */
0091 PyAPI_FUNC(void) _PyBytesWriter_Dealloc(_PyBytesWriter *writer);
0092
0093 /* Allocate the buffer to write size bytes.
0094    Return the pointer to the beginning of buffer data.
0095    Raise an exception and return NULL on error. */
0096 PyAPI_FUNC(void*) _PyBytesWriter_Alloc(_PyBytesWriter *writer,
0097     Py_ssize_t size);
0098
0099 /* Ensure that the buffer is large enough to write *size* bytes.
0100    Add size to the writer minimum size (min_size attribute).
0101
0102    str is the current pointer inside the buffer.
0103    Return the updated current pointer inside the buffer.
0104    Raise an exception and return NULL on error. */
0105 PyAPI_FUNC(void*) _PyBytesWriter_Prepare(_PyBytesWriter *writer,
0106     void *str,
0107     Py_ssize_t size);
0108
0109 /* Resize the buffer to make it larger.
0110    The new buffer may be larger than size bytes because of overallocation.
0111    Return the updated current pointer inside the buffer.
0112    Raise an exception and return NULL on error.
0113
0114    Note: size must be greater than the number of allocated bytes in the writer.
0115
0116    This function doesn't use the writer minimum size (min_size attribute).
0117
0118    See also _PyBytesWriter_Prepare().
0119    */
0120 PyAPI_FUNC(void*) _PyBytesWriter_Resize(_PyBytesWriter *writer,
0121     void *str,
0122     Py_ssize_t size);
0123
0124 /* Write bytes.
0125    Raise an exception and return NULL on error. */
0126 PyAPI_FUNC(void*) _PyBytesWriter_WriteBytes(_PyBytesWriter *writer,
0127     void *str,
0128     const void *bytes,
0129     Py_ssize_t size);