:right-sidebar: True Bytes =================================================================== .. currentmodule:: gi.repository.GLib .. versionadded:: 2.32 .. class:: Bytes(**kwargs) :no-contents-entry: A simple refcounted data type representing an immutable sequence of zero or more bytes from an unspecified origin. The purpose of a :obj:`~gi.repository.GLib.Bytes` is to keep the memory region that it holds alive for as long as anyone holds a reference to the bytes. When the last reference count is dropped, the memory is released. Multiple unrelated callers can use byte data in the :obj:`~gi.repository.GLib.Bytes` without coordinating their activities, resting assured that the byte data will not change or move while they hold a reference. A :obj:`~gi.repository.GLib.Bytes` can come from many different origins that may have different procedures for freeing the memory region. Examples are memory from :func:`~gi.repository.GLib.malloc`, from memory slices, from a :obj:`~gi.repository.GLib.MappedFile` or memory from other allocators. :obj:`~gi.repository.GLib.Bytes` work well as keys in :obj:`~gi.repository.GLib.HashTable`\. Use :func:`~gi.repository.GLib.Bytes.equal` and :func:`~gi.repository.GLib.Bytes.hash` as parameters to :func:`~gi.repository.GLib.HashTable.new` or :func:`~gi.repository.GLib.HashTable.new_full`. :obj:`~gi.repository.GLib.Bytes` can also be used as keys in a :obj:`~gi.repository.GLib.Tree` by passing the :func:`~gi.repository.GLib.Bytes.compare` function to :func:`~gi.repository.GLib.Tree.new`. The data pointed to by this bytes must not be modified. For a mutable array of bytes see ``GByteArray``. Use :func:`~gi.repository.GLib.Bytes.unref_to_array` to create a mutable array for a :obj:`~gi.repository.GLib.Bytes` sequence. To create an immutable :obj:`~gi.repository.GLib.Bytes` from a mutable ``GByteArray``, use the :func:`~gi.repository.GLib.ByteArray.free_to_bytes` function. Constructors ------------ .. rst-class:: interim-class .. class:: Bytes :no-index: .. classmethod:: new(data: list[int] | None = None) -> ~gi.repository.GLib.Bytes Creates a new :obj:`~gi.repository.GLib.Bytes` from ``data``\. ``data`` is copied. If ``size`` is 0, ``data`` may be :const:`None`. .. versionadded:: 2.32 :param data: the data to be used for the bytes .. classmethod:: new_take(data: list[int] | None = None) -> ~gi.repository.GLib.Bytes Creates a new :obj:`~gi.repository.GLib.Bytes` from ``data``\. After this call, ``data`` belongs to the :obj:`~gi.repository.GLib.Bytes` and may no longer be modified by the caller. The memory of ``data`` has to be dynamically allocated and will eventually be freed with :func:`~gi.repository.GLib.free`. For creating :obj:`~gi.repository.GLib.Bytes` with memory from other allocators, see :func:`~gi.repository.GLib.Bytes.new_with_free_func`. ``data`` may be :const:`None` if ``size`` is 0. .. versionadded:: 2.32 :param data: the data to be used for the bytes Methods ------- .. rst-class:: interim-class .. class:: Bytes :no-index: .. method:: compare(bytes2: ~gi.repository.GLib.Bytes) -> int Compares the two :obj:`~gi.repository.GLib.Bytes` values. This function can be used to sort GBytes instances in lexicographical order. If ``bytes1`` and ``bytes2`` have different length but the shorter one is a prefix of the longer one then the shorter one is considered to be less than the longer one. Otherwise the first byte where both differ is used for comparison. If ``bytes1`` has a smaller value at that position it is considered less, otherwise greater than ``bytes2``\. .. versionadded:: 2.32 :param bytes2: a pointer to a :obj:`~gi.repository.GLib.Bytes` to compare with ``bytes1`` .. method:: equal(bytes2: ~gi.repository.GLib.Bytes) -> bool Compares the two :obj:`~gi.repository.GLib.Bytes` values being pointed to and returns :const:`True` if they are equal. This function can be passed to :func:`~gi.repository.GLib.HashTable.new` as the ``key_equal_func`` parameter, when using non-:const:`None` :obj:`~gi.repository.GLib.Bytes` pointers as keys in a :obj:`~gi.repository.GLib.HashTable`\. .. versionadded:: 2.32 :param bytes2: a pointer to a :obj:`~gi.repository.GLib.Bytes` to compare with ``bytes1`` .. method:: get_data() -> list[int] | None Get the byte data in the :obj:`~gi.repository.GLib.Bytes`\. This data should not be modified. This function will always return the same pointer for a given :obj:`~gi.repository.GLib.Bytes`\. :const:`None` may be returned if ``size`` is 0. This is not guaranteed, as the :obj:`~gi.repository.GLib.Bytes` may represent an empty string with ``data`` non-:const:`None` and ``size`` as 0. :const:`None` will not be returned if ``size`` is non-zero. .. versionadded:: 2.32 .. method:: get_region(element_size: int, offset: int, n_elements: int) -> ~typing.Any | None Gets a pointer to a region in ``bytes``\. The region starts at ``offset`` many bytes from the start of the data and contains ``n_elements`` many elements of ``element_size`` size. ``n_elements`` may be zero, but ``element_size`` must always be non-zero. Ideally, ``element_size`` is a static constant (eg: sizeof a struct). This function does careful bounds checking (including checking for arithmetic overflows) and returns a non-:const:`None` pointer if the specified region lies entirely within the ``bytes``\. If the region is in some way out of range, or if an overflow has occurred, then :const:`None` is returned. Note: it is possible to have a valid zero-size region. In this case, the returned pointer will be equal to the base pointer of the data of ``bytes``\, plus ``offset``\. This will be non-:const:`None` except for the case where ``bytes`` itself was a zero-sized region. Since it is unlikely that you will be using this function to check for a zero-sized region in a zero-sized ``bytes``\, :const:`None` effectively always means "error". .. versionadded:: 2.70 :param element_size: a non-zero element size :param offset: an offset to the start of the region within the ``bytes`` :param n_elements: the number of elements in the region .. method:: get_size() -> int Get the size of the byte data in the :obj:`~gi.repository.GLib.Bytes`\. This function will always return the same value for a given :obj:`~gi.repository.GLib.Bytes`\. .. versionadded:: 2.32 .. method:: hash() -> int Creates an integer hash code for the byte data in the :obj:`~gi.repository.GLib.Bytes`\. This function can be passed to :func:`~gi.repository.GLib.HashTable.new` as the ``key_hash_func`` parameter, when using non-:const:`None` :obj:`~gi.repository.GLib.Bytes` pointers as keys in a :obj:`~gi.repository.GLib.HashTable`\. .. versionadded:: 2.32 .. method:: new_from_bytes(offset: int, length: int) -> ~gi.repository.GLib.Bytes Creates a :obj:`~gi.repository.GLib.Bytes` which is a subsection of another :obj:`~gi.repository.GLib.Bytes`\. The ``offset`` + ``length`` may not be longer than the size of ``bytes``\. A reference to ``bytes`` will be held by the newly created :obj:`~gi.repository.GLib.Bytes` until the byte data is no longer needed. Since 2.56, if ``offset`` is 0 and ``length`` matches the size of ``bytes``\, then ``bytes`` will be returned with the reference count incremented by 1. If ``bytes`` is a slice of another :obj:`~gi.repository.GLib.Bytes`\, then the resulting :obj:`~gi.repository.GLib.Bytes` will reference the same :obj:`~gi.repository.GLib.Bytes` instead of ``bytes``\. This allows consumers to simplify the usage of :obj:`~gi.repository.GLib.Bytes` when asynchronously writing to streams. .. versionadded:: 2.32 :param offset: offset which subsection starts at :param length: length of subsection