Positioning functions

Auto position

libtree has a feature called auto position which is turned on by default and makes sure that whenever you insert, move or delete a node its siblings stay correctly ordered.

Let’s assume you have a node sequence like this:

position | 0 | 1
node     | A | B

If you now insert a new node without any further arguments, auto position will insert it at the end of the sequence:

position | 0 | 1 | 2
node     | A | B | C

But if you insert the node at a certain position (1 in this example), auto position will free the desired spot and shift the following siblings to the right like this:

position | 0 | 1 | 2
node     | A | C | B

Likewise, if you want to delete the node at position 1, auto position will left-shift all following nodes, so you end up with the same sequence as at the beginning again.

This is default behaviour because most users expect a tree implementation to behave like this.

Disable auto position

If you’re working on a dataset in which you know the final positions of your nodes before feeding them into libtree, you can disable auto position altogether. This means lesser queries to the database and thus, faster insert speeds. On the other hand this means that no constraint checks are being made and you could end up with non-continuative position sequences, multiple nodes at the same position or no position at all. Don’t worry - libtree supports those cases perfectly well - but it might be confusing in the end.

To disable auto position you must pass auto_position=False to any function that manipulates the tree (see Tree functions).


Related: libtree.query.get_node_at_position()

ensure_free_position(cur, node, position)

Move siblings away to have a free slot at position in the children of node.

  • node (Node or uuid4) –
  • position (int) –
find_highest_position(cur, node)

Return highest, not occupied position in the children of node.

Parameters:node (Node or uuid4) –
set_position(cur, node, position, auto_position=True)

Set position for node.

  • node (Node or uuid4) –
  • position (int) – Position in between siblings. If 0, the node will be inserted at the beginning of the parents children. If -1, the node will be inserted the the end of the parents children. If auto_position is disabled, this is just a value.
  • auto_position (bool) – See Positioning functions
shift_positions(cur, node, position, offset)

Shift all children of node at position by offset.

  • node (Node or uuid4) –
  • position (int) –
  • offset (int) – Positive value for right shift, negative value for left shift
swap_node_positions(cur, node1, node2)

Swap positions of node1 and node2.

  • node1 (Node or uuid4) –
  • node2 (Node or uuid4) –