Line data    Source code

       1             : #ifndef Py_CPYTHON_BYTESOBJECT_H
       2             : #  error "this header file must not be included directly"
       3             : #endif
       4             : 
       5             : typedef struct {
       6             :     PyObject_VAR_HEAD
       7             :     Py_DEPRECATED(3.11) Py_hash_t ob_shash;
       8             :     char ob_sval[1];
       9             : 
      10             :     /* Invariants:
      11             :      *     ob_sval contains space for 'ob_size+1' elements.
      12             :      *     ob_sval[ob_size] == 0.
      13             :      *     ob_shash is the hash of the byte string or -1 if not computed yet.
      14             :      */
      15             : } PyBytesObject;
      16             : 
      17             : PyAPI_FUNC(int) _PyBytes_Resize(PyObject **, Py_ssize_t);
      18             : PyAPI_FUNC(PyObject*) _PyBytes_FormatEx(
      19             :     const char *format,
      20             :     Py_ssize_t format_len,
      21             :     PyObject *args,
      22             :     int use_bytearray);
      23             : PyAPI_FUNC(PyObject*) _PyBytes_FromHex(
      24             :     PyObject *string,
      25             :     int use_bytearray);
      26             : 
      27             : /* Helper for PyBytes_DecodeEscape that detects invalid escape chars. */
      28             : PyAPI_FUNC(PyObject *) _PyBytes_DecodeEscape(const char *, Py_ssize_t,
      29             :                                              const char *, const char **);
      30             : 
      31             : /* Macros and static inline functions, trading safety for speed */
      32             : #define _PyBytes_CAST(op) \
      33             :     (assert(PyBytes_Check(op)), _Py_CAST(PyBytesObject*, op))
      34             : 
      35         137 : static inline char* PyBytes_AS_STRING(PyObject *op)
      36             : {
      37         137 :     return _PyBytes_CAST(op)->ob_sval;
      38             : }
      39             : #if !defined(Py_LIMITED_API) || Py_LIMITED_API+0 < 0x030b0000
      40             : #  define PyBytes_AS_STRING(op) PyBytes_AS_STRING(_PyObject_CAST(op))
      41             : #endif
      42             : 
      43             : static inline Py_ssize_t PyBytes_GET_SIZE(PyObject *op) {
      44             :     PyBytesObject *self = _PyBytes_CAST(op);
      45             :     return Py_SIZE(self);
      46             : }
      47             : #if !defined(Py_LIMITED_API) || Py_LIMITED_API+0 < 0x030b0000
      48             : #  define PyBytes_GET_SIZE(self) PyBytes_GET_SIZE(_PyObject_CAST(self))
      49             : #endif
      50             : 
      51             : /* _PyBytes_Join(sep, x) is like sep.join(x).  sep must be PyBytesObject*,
      52             :    x must be an iterable object. */
      53             : PyAPI_FUNC(PyObject *) _PyBytes_Join(PyObject *sep, PyObject *x);
      54             : 
      55             : 
      56             : /* The _PyBytesWriter structure is big: it contains an embedded "stack buffer".
      57             :    A _PyBytesWriter variable must be declared at the end of variables in a
      58             :    function to optimize the memory allocation on the stack. */
      59             : typedef struct {
      60             :     /* bytes, bytearray or NULL (when the small buffer is used) */
      61             :     PyObject *buffer;
      62             : 
      63             :     /* Number of allocated size. */
      64             :     Py_ssize_t allocated;
      65             : 
      66             :     /* Minimum number of allocated bytes,
      67             :        incremented by _PyBytesWriter_Prepare() */
      68             :     Py_ssize_t min_size;
      69             : 
      70             :     /* If non-zero, use a bytearray instead of a bytes object for buffer. */
      71             :     int use_bytearray;
      72             : 
      73             :     /* If non-zero, overallocate the buffer (default: 0).
      74             :        This flag must be zero if use_bytearray is non-zero. */
      75             :     int overallocate;
      76             : 
      77             :     /* Stack buffer */
      78             :     int use_small_buffer;
      79             :     char small_buffer[512];
      80             : } _PyBytesWriter;
      81             : 
      82             : /* Initialize a bytes writer
      83             : 
      84             :    By default, the overallocation is disabled. Set the overallocate attribute
      85             :    to control the allocation of the buffer. */
      86             : PyAPI_FUNC(void) _PyBytesWriter_Init(_PyBytesWriter *writer);
      87             : 
      88             : /* Get the buffer content and reset the writer.
      89             :    Return a bytes object, or a bytearray object if use_bytearray is non-zero.
      90             :    Raise an exception and return NULL on error. */
      91             : PyAPI_FUNC(PyObject *) _PyBytesWriter_Finish(_PyBytesWriter *writer,
      92             :     void *str);
      93             : 
      94             : /* Deallocate memory of a writer (clear its internal buffer). */
      95             : PyAPI_FUNC(void) _PyBytesWriter_Dealloc(_PyBytesWriter *writer);
      96             : 
      97             : /* Allocate the buffer to write size bytes.
      98             :    Return the pointer to the beginning of buffer data.
      99             :    Raise an exception and return NULL on error. */
     100             : PyAPI_FUNC(void*) _PyBytesWriter_Alloc(_PyBytesWriter *writer,
     101             :     Py_ssize_t size);
     102             : 
     103             : /* Ensure that the buffer is large enough to write *size* bytes.
     104             :    Add size to the writer minimum size (min_size attribute).
     105             : 
     106             :    str is the current pointer inside the buffer.
     107             :    Return the updated current pointer inside the buffer.
     108             :    Raise an exception and return NULL on error. */
     109             : PyAPI_FUNC(void*) _PyBytesWriter_Prepare(_PyBytesWriter *writer,
     110             :     void *str,
     111             :     Py_ssize_t size);
     112             : 
     113             : /* Resize the buffer to make it larger.
     114             :    The new buffer may be larger than size bytes because of overallocation.
     115             :    Return the updated current pointer inside the buffer.
     116             :    Raise an exception and return NULL on error.
     117             : 
     118             :    Note: size must be greater than the number of allocated bytes in the writer.
     119             : 
     120             :    This function doesn't use the writer minimum size (min_size attribute).
     121             : 
     122             :    See also _PyBytesWriter_Prepare().
     123             :    */
     124             : PyAPI_FUNC(void*) _PyBytesWriter_Resize(_PyBytesWriter *writer,
     125             :     void *str,
     126             :     Py_ssize_t size);
     127             : 
     128             : /* Write bytes.
     129             :    Raise an exception and return NULL on error. */
     130             : PyAPI_FUNC(void*) _PyBytesWriter_WriteBytes(_PyBytesWriter *writer,
     131             :     void *str,
     132             :     const void *bytes,
     133             :     Py_ssize_t size);