:right-sidebar: True Bytes =================================================================== .. currentmodule:: gi.repository.GLib .. versionadded:: 2.32 .. class:: Bytes(**kwargs) :no-contents-entry: :Constructors: :: new(data:list=None) -> GLib.Bytes new_take(data:list=None) -> GLib.Bytes Constructors ------------ .. rst-class:: interim-class .. class:: Bytes :no-index: .. classmethod:: new(data: ~typing.Sequence[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: ~typing.Sequence[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() -> bytes | 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) -> 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