| 1 |
.. highlight:: c |
| 2 |
|
| 3 |
.. _bytearrayobjects: |
| 4 |
|
| 5 |
Byte Array Objects |
| 6 |
------------------ |
| 7 |
|
| 8 |
.. index:: pair: object; bytearray |
| 9 |
|
| 10 |
|
| 11 |
.. c:type:: PyByteArrayObject |
| 12 |
|
| 13 |
This subtype of :c:type:`PyObject` represents a Python bytearray object. |
| 14 |
|
| 15 |
|
| 16 |
.. c:var:: PyTypeObject PyByteArray_Type |
| 17 |
|
| 18 |
This instance of :c:type:`PyTypeObject` represents the Python bytearray type; |
| 19 |
it is the same object as :class:`bytearray` in the Python layer. |
| 20 |
|
| 21 |
|
| 22 |
Type check macros |
| 23 |
^^^^^^^^^^^^^^^^^ |
| 24 |
|
| 25 |
.. c:function:: int PyByteArray_Check(PyObject *o) |
| 26 |
|
| 27 |
Return true if the object *o* is a bytearray object or an instance of a |
| 28 |
subtype of the bytearray type. This function always succeeds. |
| 29 |
|
| 30 |
|
| 31 |
.. c:function:: int PyByteArray_CheckExact(PyObject *o) |
| 32 |
|
| 33 |
Return true if the object *o* is a bytearray object, but not an instance of a |
| 34 |
subtype of the bytearray type. This function always succeeds. |
| 35 |
|
| 36 |
|
| 37 |
Direct API functions |
| 38 |
^^^^^^^^^^^^^^^^^^^^ |
| 39 |
|
| 40 |
.. c:function:: PyObject* PyByteArray_FromObject(PyObject *o) |
| 41 |
|
| 42 |
Return a new bytearray object from any object, *o*, that implements the |
| 43 |
:ref:`buffer protocol <bufferobjects>`. |
| 44 |
|
| 45 |
On failure, return ``NULL`` with an exception set. |
| 46 |
|
| 47 |
.. note:: |
| 48 |
If the object implements the buffer protocol, then the buffer |
| 49 |
must not be mutated while the bytearray object is being created. |
| 50 |
|
| 51 |
|
| 52 |
.. c:function:: PyObject* PyByteArray_FromStringAndSize(const char *string, Py_ssize_t len) |
| 53 |
|
| 54 |
Create a new bytearray object from *string* and its length, *len*. |
| 55 |
|
| 56 |
On failure, return ``NULL`` with an exception set. |
| 57 |
|
| 58 |
|
| 59 |
.. c:function:: PyObject* PyByteArray_Concat(PyObject *a, PyObject *b) |
| 60 |
|
| 61 |
Concat bytearrays *a* and *b* and return a new bytearray with the result. |
| 62 |
|
| 63 |
On failure, return ``NULL`` with an exception set. |
| 64 |
|
| 65 |
.. note:: |
| 66 |
If the object implements the buffer protocol, then the buffer |
| 67 |
must not be mutated while the bytearray object is being created. |
| 68 |
|
| 69 |
|
| 70 |
.. c:function:: Py_ssize_t PyByteArray_Size(PyObject *bytearray) |
| 71 |
|
| 72 |
Return the size of *bytearray* after checking for a ``NULL`` pointer. |
| 73 |
|
| 74 |
|
| 75 |
.. c:function:: char* PyByteArray_AsString(PyObject *bytearray) |
| 76 |
|
| 77 |
Return the contents of *bytearray* as a char array after checking for a |
| 78 |
``NULL`` pointer. The returned array always has an extra |
| 79 |
null byte appended. |
| 80 |
|
| 81 |
.. note:: |
| 82 |
It is not thread-safe to mutate the bytearray object while using the returned char array. |
| 83 |
|
| 84 |
|
| 85 |
.. c:function:: int PyByteArray_Resize(PyObject *bytearray, Py_ssize_t len) |
| 86 |
|
| 87 |
Resize the internal buffer of *bytearray* to *len*. |
| 88 |
Failure is a ``-1`` return with an exception set. |
| 89 |
|
| 90 |
.. versionchanged:: 3.14 |
| 91 |
A negative *len* will now result in an exception being set and -1 returned. |
| 92 |
|
| 93 |
|
| 94 |
Macros |
| 95 |
^^^^^^ |
| 96 |
|
| 97 |
These macros trade safety for speed and they don't check pointers. |
| 98 |
|
| 99 |
.. c:function:: char* PyByteArray_AS_STRING(PyObject *bytearray) |
| 100 |
|
| 101 |
Similar to :c:func:`PyByteArray_AsString`, but without error checking. |
| 102 |
|
| 103 |
.. note:: |
| 104 |
It is not thread-safe to mutate the bytearray object while using the returned char array. |
| 105 |
|
| 106 |
|
| 107 |
.. c:function:: Py_ssize_t PyByteArray_GET_SIZE(PyObject *bytearray) |
| 108 |
|
| 109 |
Similar to :c:func:`PyByteArray_Size`, but without error checking. |