# Об’єкти Bytes

Ці функції викликають `TypeError`, коли очікується параметр bytes і викликаються з параметром, який не є байтом.

type PyBytesObject

  Цей підтип `PyObject` представляє об’єкт Python bytes.

PyTypeObject PyBytes_Type
  Part of the Stable ABI.

  Цей екземпляр `PyTypeObject` представляє тип Python bytes; це той самий об’єкт, що й `bytes` на рівні Python.

int PyBytes_Check(PyObject *o)

  Повертає true, якщо об’єкт o є об’єктом bytes або екземпляром підтипу типу bytes. Ця функція завжди успішна.

int PyBytes_CheckExact(PyObject *o)

  Повертає true, якщо об’єкт o є об’єктом bytes, але не екземпляром підтипу типу bytes. Ця функція завжди успішна.

PyObject *PyBytes_FromString(const char *v)
  Return value: New reference. Part of the Stable ABI. Thread safety: Atomic.

  Повертає новий об’єкт bytes із копією рядка v як значення в разі успіху та `NULL` у разі помилки. Параметр v не має бути `NULL`; перевірятися не буде.

PyObject *PyBytes_FromStringAndSize(const char *v, Py_ssize_t len)
  Return value: New reference. Part of the Stable ABI. Thread safety: Atomic.

  Повертає новий об’єкт bytes із копією рядка v як значення та довжиною len у разі успіху та `NULL` у разі помилки. Якщо v має значення `NULL`, вміст об’єкта bytes не ініціалізується.

  Soft deprecated since version 3.15: Use the `PyBytesWriter` API instead of `PyBytes_FromStringAndSize(NULL, len)`.

PyObject *PyBytes_FromFormat(const char *format, ...)
  Return value: New reference. Part of the Stable ABI. Thread safety: Atomic.

  Візьміть рядок format у стилі C `printf()`і змінну кількість аргументів, обчисліть розмір результуючого об’єкта Python bytes і поверніть об’єкт bytes із відформатованими значеннями. Змінні аргументи мають бути типу C і точно відповідати символам формату в рядку format. Дозволяються такі символи формату:

  Формат символів | Тип | коментар
  --- | --- | ---
  `%%` | немає | Літеральний символ %.
  `%c` | внутр | Один байт, представлений як C int.
  `%d` | внутр | Еквівалент `printf("%d")`. [1]
  `%u` | unsigned int | Еквівалент `printf("%u")`. [1]
  `%ld` | довгота | Еквівалент `printf("%ld")`. [1]
  `%lu` | беззнаковий довгий | Еквівалент `printf("%lu")`. [1]
  `%zd` | `Py_ssize_t` | Еквівалент `printf("%zd")`. [1]
  `%zu` | size_t | Еквівалент `printf("%zu")`. [1]
  `%i` | внутр | Еквівалент `printf("%i")`. [1]
  `%x` | внутр | Еквівалент `printf("%x")`. [1]
  `%s` | const char* | Масив символів C із закінченням нулем.
  `%p` | const void* | Шістнадцяткове представлення покажчика C. Здебільшого еквівалентний `printf("%p")` за винятком того, що він гарантовано починається з літералу `0x` незалежно від того, що дає `printf` платформи.

  Нерозпізнаний символ формату спричиняє копіювання всієї решти рядка формату в об’єкт результату як є, а будь-які додаткові аргументи відкидаються.

  [1] (1,2,3,4,5,6,7,8)

  Для цілочисельних специфікаторів (d, u, ld, lu, zd, zu, i, x): прапор 0-конверсії діє, навіть якщо задано точність.

PyObject *PyBytes_FromFormatV(const char *format, va_list vargs)
  Return value: New reference. Part of the Stable ABI. Thread safety: Atomic.

  Ідентичний `PyBytes_FromFormat()` за винятком того, що він приймає рівно два аргументи.

PyObject *PyBytes_FromObject(PyObject *o)
  Return value: New reference. Part of the Stable ABI. Thread safety: Safe for concurrent use on the same object.

  Повертає представлення байтів об’єкта o, який реалізує протокол буфера.

  Примітка

  If the object implements the buffer protocol, then the buffer must not be mutated while the bytes object is being created.

Py_ssize_t PyBytes_Size(PyObject *o)
  Part of the Stable ABI. Thread safety: Atomic.

  Повертає довжину байтів у байтах об’єкт o.

Py_ssize_t PyBytes_GET_SIZE(PyObject *o)
  Thread safety: Atomic.

  Similar to `PyBytes_Size()`, but without error checking.

char *PyBytes_AsString(PyObject *o)
  Part of the Stable ABI. Thread safety: Safe to call from multiple threads with external synchronization only.

  Повернути вказівник на вміст o. Покажчик посилається на внутрішній буфер o, який складається з `len(o) + 1` байтів. Останній байт у буфері завжди нульовий, незалежно від того, чи є інші нульові байти. Дані не можна змінювати жодним чином, якщо об’єкт не було щойно створено за допомогою `PyBytes_FromStringAndSize(NULL, size)`. Його не можна звільняти. Якщо o взагалі не є об’єктом bytes, `PyBytes_AsString()` повертає `NULL` і викликає `TypeError`.

char *PyBytes_AS_STRING(PyObject *string)
  Thread safety: Safe to call from multiple threads with external synchronization only.

  Similar to `PyBytes_AsString()`, but without error checking.

int PyBytes_AsStringAndSize(PyObject *obj, char **buffer, Py_ssize_t *length)
  Part of the Stable ABI. Thread safety: Safe to call from multiple threads with external synchronization only.

  Return the null-terminated contents of the object obj through the output variables buffer and length. Returns `0` on success.

  Якщо length дорівнює `NULL`, об’єкт bytes може не містити вбудованих нульових байтів; якщо це так, функція повертає `-1` і викликає `ValueError`.

  Буфер відноситься до внутрішнього буфера obj, який містить додатковий нульовий байт у кінці (не враховується в довжині). Дані не можна змінювати жодним чином, якщо об’єкт не було щойно створено за допомогою `PyBytes_FromStringAndSize(NULL, size)`. Його не можна звільняти. Якщо obj взагалі не є об’єктом bytes, `PyBytes_AsStringAndSize()` повертає `-1` і викликає `TypeError`.

  Змінено в версії 3.5: Раніше `TypeError` виникало, коли в об’єкті bytes зустрічалися вбудовані нульові байти.

void PyBytes_Concat(PyObject **bytes, PyObject *newpart)
  Part of the Stable ABI. Thread safety: Safe for concurrent use on the same object.

  Створіть новий об’єкт bytes у *bytes, що містить вміст newpart, доданий до bytes; абонент буде володіти новим посиланням. Посилання на старе значення bytes буде викрадено. Якщо новий об’єкт неможливо створити, старе посилання на bytes все одно буде відкинуто, а значення *bytes буде встановлено на `NULL`; буде встановлено відповідний виняток.

  Примітка

  If newpart implements the buffer protocol, then the buffer must not be mutated while the new bytes object is being created.

void PyBytes_ConcatAndDel(PyObject **bytes, PyObject *newpart)
  Part of the Stable ABI. Thread safety: Safe for concurrent use on the same object.

  Create a new bytes object in *bytes containing the contents of newpart appended to bytes. This version releases the strong reference to newpart (i.e. decrements its reference count).

  Примітка

  If newpart implements the buffer protocol, then the buffer must not be mutated while the new bytes object is being created.

PyObject *PyBytes_Join(PyObject *sep, PyObject *iterable)
  Thread safety: Safe for concurrent use on the same object.

  Similar to `sep.join(iterable)` in Python.

  sep must be Python `bytes` object. (Note that `PyUnicode_Join()` accepts `NULL` separator and treats it as a space, whereas `PyBytes_Join()` doesn’t accept `NULL` separator.)

  iterable must be an iterable object yielding objects that implement the buffer protocol.

  On success, return a new `bytes` object. On error, set an exception and return `NULL`.

  Added in version 3.14.

  Примітка

  If iterable objects implement the buffer protocol, then the buffers must not be mutated while the new bytes object is being created.

int _PyBytes_Resize(PyObject **bytes, Py_ssize_t newsize)
  Thread safety: Safe to call without external synchronization on distinct objects.

  Resize a bytes object. newsize will be the new length of the bytes object. You can think of it as creating a new bytes object and destroying the old one, only more efficiently. Pass the address of an existing bytes object as an lvalue (it may be written into), and the new size desired. On success, *bytes holds the resized bytes object and `0` is returned; the address in *bytes may differ from its input value. If the reallocation fails, the original bytes object at *bytes is deallocated, *bytes is set to `NULL`, `MemoryError` is set, and `-1` is returned.

  Soft deprecated since version 3.15: Use the `PyBytesWriter` API instead.

PyObject *PyBytes_Repr(PyObject *bytes, int smartquotes)
  Part of the Stable ABI. Thread safety: Atomic.

  Get the string representation of bytes. This function is currently used to implement `bytes.__repr__()` in Python.

  This function does not do type checking; it is undefined behavior to pass bytes as a non-bytes object or `NULL`.

  If smartquotes is true, the representation will use a double-quoted string instead of single-quoted string when single-quotes are present in bytes. For example, the byte string `'Python'` would be represented as `b"'Python'"` when smartquotes is true, or `b'\'Python\''` when it is false.

  On success, this function returns a strong reference to a `str` object containing the representation. On failure, this returns `NULL` with an exception set.

PyObject *PyBytes_DecodeEscape(const char *s, Py_ssize_t len, const char *errors, Py_ssize_t unicode, const char *recode_encoding)
  Part of the Stable ABI. Thread safety: Atomic.

  Unescape a backslash-escaped string s. s must not be `NULL`. len must be the size of s.

  errors must be one of `"strict"`, `"replace"`, or `"ignore"`. If errors is `NULL`, then `"strict"` is used by default.

  On success, this function returns a strong reference to a Python `bytes` object containing the unescaped string. On failure, this function returns `NULL` with an exception set.

  Змінено в версії 3.9: unicode and recode_encoding are now unused.

# PyBytesWriter

The `PyBytesWriter` API can be used to create a Python `bytes` object.

Added in version 3.15.

type PyBytesWriter

  A bytes writer instance.

  The API is not thread safe: a writer should only be used by a single thread at the same time.

  The instance must be destroyed by `PyBytesWriter_Finish()` on success, or `PyBytesWriter_Discard()` on error.

## Create, Finish, Discard

PyBytesWriter *PyBytesWriter_Create(Py_ssize_t size)

  Create a `PyBytesWriter` to write size bytes.

  If size is greater than zero, allocate size bytes, and set the writer size to size. The caller is responsible to write size bytes using `PyBytesWriter_GetData()`. This function does not overallocate.

  On error, set an exception and return `NULL`.

  size must be positive or zero.

PyObject *PyBytesWriter_Finish(PyBytesWriter *writer)

  Finish a `PyBytesWriter` created by `PyBytesWriter_Create()`.

  On success, return a Python `bytes` object. On error, set an exception and return `NULL`.

  The writer instance is invalid after the call in any case. No API can be called on the writer after `PyBytesWriter_Finish()`.

PyObject *PyBytesWriter_FinishWithSize(PyBytesWriter *writer, Py_ssize_t size)

  Similar to `PyBytesWriter_Finish()`, but resize the writer to size bytes before creating the `bytes` object.

PyObject *PyBytesWriter_FinishWithPointer(PyBytesWriter *writer, void *buf)

  Similar to `PyBytesWriter_Finish()`, but resize the writer using buf pointer before creating the `bytes` object.

  Set an exception and return `NULL` if buf pointer is outside the internal buffer bounds.

  Function pseudo-code:

      Py_ssize_t size = (char*)buf - (char*)PyBytesWriter_GetData(writer);
      return PyBytesWriter_FinishWithSize(writer, size);

void PyBytesWriter_Discard(PyBytesWriter *writer)

  Discard a `PyBytesWriter` created by `PyBytesWriter_Create()`.

  Do nothing if writer is `NULL`.

  The writer instance is invalid after the call. No API can be called on the writer after `PyBytesWriter_Discard()`.

## High-level API

int PyBytesWriter_WriteBytes(PyBytesWriter *writer, const void *bytes, Py_ssize_t size)

  Grow the writer internal buffer by size bytes, write size bytes of bytes at the writer end, and add size to the writer size.

  If size is equal to `-1`, call `strlen(bytes)` to get the string length.

  On success, return `0`. On error, set an exception and return `-1`.

int PyBytesWriter_Format(PyBytesWriter *writer, const char *format, ...)

  Similar to `PyBytes_FromFormat()`, but write the output directly at the writer end. Grow the writer internal buffer on demand. Then add the written size to the writer size.

  On success, return `0`. On error, set an exception and return `-1`.

## Getters

Py_ssize_t PyBytesWriter_GetSize(PyBytesWriter *writer)

  Get the writer size.

  The function cannot fail.

void *PyBytesWriter_GetData(PyBytesWriter *writer)

  Get the writer data: start of the internal buffer.

  The pointer is valid until `PyBytesWriter_Finish()` or `PyBytesWriter_Discard()` is called on writer.

  The function cannot fail.

## Low-level API

int PyBytesWriter_Resize(PyBytesWriter *writer, Py_ssize_t size)

  Resize the writer to size bytes. It can be used to enlarge or to shrink the writer. This function typically overallocates to achieve amortized performance when resizing multiple times.

  Newly allocated bytes are left uninitialized.

  On success, return `0`. On error, set an exception and return `-1`.

  size must be positive or zero.

int PyBytesWriter_Grow(PyBytesWriter *writer, Py_ssize_t grow)

  Resize the writer by adding grow bytes to the current writer size. This function typically overallocates to achieve amortized performance when resizing multiple times.

  Newly allocated bytes are left uninitialized.

  On success, return `0`. On error, set an exception and return `-1`.

  size can be negative to shrink the writer.

void *PyBytesWriter_GrowAndUpdatePointer(PyBytesWriter *writer, Py_ssize_t size, void *buf)

  Similar to `PyBytesWriter_Grow()`, but update also the buf pointer.

  The buf pointer is moved if the internal buffer is moved in memory. The buf relative position within the internal buffer is left unchanged.

  On error, set an exception and return `NULL`.

  buf must not be `NULL`.

  Function pseudo-code:

      Py_ssize_t pos = (char*)buf - (char*)PyBytesWriter_GetData(writer);
      if (PyBytesWriter_Grow(writer, size) < 0) {
          return NULL;
      }
      return (char*)PyBytesWriter_GetData(writer) + pos;