:py:mod:`dissect.btrfs.tree`
============================

.. py:module:: dissect.btrfs.tree


Module Contents
---------------

Classes
~~~~~~~

.. autoapisummary::

   dissect.btrfs.tree.BTree
   dissect.btrfs.tree.Cursor




.. py:class:: BTree(btrfs: dissect.btrfs.btrfs.Btrfs, root_item: Optional[dissect.btrfs.c_btrfs.c_btrfs.btrfs_root_item] = None, root_offset: Optional[int] = None)


   Represent a Btrfs B-tree.

   One of ``root_item`` or ``root_offset`` must be given.

   :param btrfs: The filesystem this B-tree belongs to.
   :param root_item: Optional ``btrfs_root_item`` to open the B-tree from.
   :param root_offset: Optional offset to open the B-tree from.

   .. py:method:: cursor() -> Cursor

      Return a new cursor into the B-tree.


   .. py:method:: find(objectid: Optional[int] = None, type: Optional[int] = None, offset: Optional[int] = None) -> tuple[dissect.btrfs.c_btrfs.c_btrfs.btrfs_item, memoryview]

      Search for a single item in the B-tree.

      :param objectid: Optional object ID to search for.
      :param type: Optional type to search for.
      :param offset: Optional offset to search for.



.. py:class:: Cursor(btree: BTree)


   A basic cursor implementation for interacting with a :class:`BTree`.

   :param btree: The :class:`BTree` to open a cursor on.

   .. py:method:: reset() -> None

      Reset the cursor.


   .. py:method:: push(address: int, initial_index: int = 0) -> None

      Push the cursor down a node.

      :param address: The address of the node to push down to.
      :param initial_index: The initial index to seek to in the new node. ``-1`` means the last item.


   .. py:method:: pop() -> None

      Pop up a node.


   .. py:method:: next() -> None

      Traverse to the next leaf item.

      Will move up and down the tree to find the next leaf item.


   .. py:method:: next_node() -> None

      Traverse to the next node.

      Will move up and down the tree to find the next node.


   .. py:method:: prev() -> None

      Traverse to the previous leaf item.

      Will move up and down the tree to find the previous leaf item.


   .. py:method:: prev_node() -> None

      Traverse to the previous leaf item.

      Will move up and down the tree to find the previous leaf item.


   .. py:method:: first() -> None

      Move the cursor to the first leaf item.


   .. py:method:: last() -> None

      Move the cursor to the last leaf item.


   .. py:method:: get() -> tuple[dissect.btrfs.c_btrfs.c_btrfs.btrfs_item, memoryview]

      Retrieve the leaf item and the associated data at the current cursor position.

      Cursor must be positioned at a leaf item.


   .. py:method:: item() -> Union[dissect.btrfs.c_btrfs.c_btrfs.btrfs_key_ptr, dissect.btrfs.c_btrfs.c_btrfs.btrfs_item]

      Retrieve a leaf or branch item.

      Cursor can be positioned at a branch or leaf item.


   .. py:method:: items() -> Iterator[Union[dissect.btrfs.c_btrfs.c_btrfs.btrfs_key_ptr, dissect.btrfs.c_btrfs.c_btrfs.btrfs_item]]

      Iterate over all items in the current node.


   .. py:method:: data() -> memoryview

      Return the associated data of the current leaf item.


   .. py:method:: iter(objectid: Optional[int] = None, type: Optional[int] = None, offset: Optional[int] = None, ignore_offset: bool = False) -> Iterator[tuple[dissect.btrfs.c_btrfs.c_btrfs.btrfs_item, memoryview]]

      Search and iterate the B-tree for the specified key.

      Stop iterating if the current item no longer matches the given parameters.

      :param objectid: Optional object ID to search for.
      :param type: Optional type to search for.
      :param offset: Optional offset to search for.
      :param ignore_offset: Only use the ``offset`` argument for the initial positioning of the cursor,
                            but ignore it for future iterations. This is useful for e.g. iterating file extents.


   .. py:method:: walk(objectid: Optional[int] = None, type: Optional[int] = None, offset: Optional[int] = None) -> Iterator[tuple[dissect.btrfs.c_btrfs.c_btrfs.btrfs_item, memoryview]]

      Walk all leaf items of the B-tree and yield all matching leafs.

      :param objectid: Optional object ID to yield items of.
      :param type: Optional type to yield items of.
      :param offset: Optional offset to yield items of.


   .. py:method:: search(objectid: Optional[int] = None, type: Optional[int] = None, offset: Optional[int] = None) -> bool

      Perform a binary search on the current node for the key with the given parameters.

      Puts the cursor at the index of the matching item, or just before a "greater" item if no exact match is found.
      ``True`` is returned if this is the case, else ``False`` is returned and the cursor position is reset.

      :param objectid: Optional object ID to search for.
      :param type: Optional type to search for.
      :param offset: Optional offset to search for.