From 0644418d98c6cda3e43dea4f0a857f885777c729 Mon Sep 17 00:00:00 2001 From: Docs Syncer Date: Mon, 10 Jun 2024 09:59:52 +0000 Subject: [PATCH] CI: `d5a01b8` --- .../contracts/libs/data-structures/AvlTree.md | 778 ++++++++++++++++++ .../libs/data-structures/Traversal.md | 192 +++++ 2 files changed, 970 insertions(+) create mode 100644 docs/reference/contracts/libs/data-structures/AvlTree.md create mode 100644 docs/reference/contracts/libs/data-structures/Traversal.md diff --git a/docs/reference/contracts/libs/data-structures/AvlTree.md b/docs/reference/contracts/libs/data-structures/AvlTree.md new file mode 100644 index 0000000..bc2c71f --- /dev/null +++ b/docs/reference/contracts/libs/data-structures/AvlTree.md @@ -0,0 +1,778 @@ +# AvlTree + +## Overview + +#### License: MIT + +```solidity +library AvlTree +``` + +AVL Tree module + +This library provides implementation of three sets with dynamic `value` types: +`UintAVL`, `Bytes32AVL` and `AddressAVL`. + +Each element in the tree has a bytes32 `key` field to allow storing values +associated with different types of keys + +The implementation supports setting custom comparator function + +Gas usage for _insert and _remove functions (where count is the number of elements added to the tree): + +| Statistic | _insert | _remove | +| --------- | ------------ | ---------------- | +| count | 5000 | 5000 | +| mean | 222,578 gas | 115,744 gas | +| min | 110,520 gas | 34,461 gas | +| max | 263,275 gas | 171,815 gas | + +## Usage example: + +``` +using AvlTree for AvlTree.UintAVL; +using Traversal for Traversal.Iterator; + +AvlTree.UintAVL internal uintTree; + +................................................ + +uintTree.setComparator(comparatorFunction); + +uintTree.insert(bytes32(1), 1234); +uintTree.insert(bytes32(3), 100); + +uintTree.tryGet(bytes32(1)); + +uintTree.remove(bytes32(1)); + +................................................ + +Traversal.Iterator memory iterator_ = uintTree.first(); + +bytes32[] memory keys_ = new bytes32[](_uintTree.size()); +bytes32[] memory values_ = new bytes32[](_uintTree.size()); + +while (iterator_.isValid()) { + (keys_[i], values_[i]) = iterator_.value(); + iterator_.next(); +} +``` +## Structs info + +### UintAVL + +```solidity +struct UintAVL { + AvlTree.Tree _tree; +} +``` + +UintAVL * +### Bytes32AVL + +```solidity +struct Bytes32AVL { + AvlTree.Tree _tree; +} +``` + +Bytes32AVL * +### AddressAVL + +```solidity +struct AddressAVL { + AvlTree.Tree _tree; +} +``` + +AddressAVL * +### Node + +```solidity +struct Node { + bytes32 key; + bytes32 value; + uint64 height; + uint64 parent; + uint64 left; + uint64 right; +} +``` + +Internal Tree * +### Tree + +```solidity +struct Tree { + uint64 root; + uint64 totalCount; + uint64 removedCount; + bool isCustomComparatorSet; + mapping(uint64 => AvlTree.Node) tree; + function (bytes32,bytes32) view returns (int256) comparator; +} +``` + + +## Functions info + +### setComparator + +```solidity +function setComparator( + AvlTree.UintAVL storage tree, + function(bytes32, bytes32) view returns (int256) comparator_ +) internal +``` + +The function to set a custom comparator function, that will be used to build the uint256 tree. + + +Parameters: + +| Name | Type | Description | +| :---------- | :----------------------------------------------- | :------------------------------------------------------ | +| tree | struct AvlTree.UintAVL | self. | +| comparator_ | function (bytes32,bytes32) view returns (int256) | The function that accepts keys of the nodes to compare. | + +### insert + +```solidity +function insert( + AvlTree.UintAVL storage tree, + bytes32 key_, + uint256 value_ +) internal +``` + +The function to insert a node into the uint256 tree. +Complexity is O(log(n)), where n is the number of elements in the tree. + + + +Parameters: + +| Name | Type | Description | +| :----- | :--------------------- | :------------------- | +| tree | struct AvlTree.UintAVL | self. | +| key_ | bytes32 | the key to insert. | +| value_ | uint256 | the value to insert. | + +### remove + +```solidity +function remove(AvlTree.UintAVL storage tree, bytes32 key_) internal +``` + +The function to remove a node from the uint256 tree. +Complexity is O(log(n)), where n is the number of elements in the tree. + + + +Parameters: + +| Name | Type | Description | +| :--- | :--------------------- | :----------------------------- | +| tree | struct AvlTree.UintAVL | self. | +| key_ | bytes32 | the key of the node to remove. | + +### get + +```solidity +function get( + AvlTree.UintAVL storage tree, + bytes32 key_ +) internal view returns (uint256) +``` + +The function to retrieve the value associated with a key in the uint256 tree. +Complexity is O(log(n)), where n is the number of elements in the tree. + +Note: Reverts if the node with the specified key doesn't exist. + + + +Parameters: + +| Name | Type | Description | +| :--- | :--------------------- | :---------------------------------- | +| tree | struct AvlTree.UintAVL | self. | +| key_ | bytes32 | the key to retrieve the value for. | + + +Return values: + +| Name | Type | Description | +| :--- | :------ | :--------------------------------- | +| [0] | uint256 | The value associated with the key. | + +### tryGet + +```solidity +function tryGet( + AvlTree.UintAVL storage tree, + bytes32 key_ +) internal view returns (bool, uint256) +``` + +The function to try to retrieve the value associated with a key in the uint256 tree. +Complexity is O(log(n)), where n is the number of elements in the tree. + + +Does not revert if the node with the specified key doesn't exist. + + + +Parameters: + +| Name | Type | Description | +| :--- | :--------------------- | :----------------------------------------------------- | +| tree | struct AvlTree.UintAVL | self. | +| key_ | bytes32 | the key of the node to try to retrieve the value for. | + + +Return values: + +| Name | Type | Description | +| :--- | :------ | :---------------------------------------------------------------- | +| [0] | bool | True if the node with the specified key exists, false otherwise. | +| [1] | uint256 | The value associated with the key. | + +### size + +```solidity +function size(AvlTree.UintAVL storage tree) internal view returns (uint64) +``` + +The function to retrieve the size of the uint256 tree. + + +Parameters: + +| Name | Type | Description | +| :--- | :--------------------- | :---------- | +| tree | struct AvlTree.UintAVL | self. | + + +Return values: + +| Name | Type | Description | +| :--- | :----- | :-------------------- | +| [0] | uint64 | The size of the tree. | + +### first + +```solidity +function first( + AvlTree.UintAVL storage tree +) internal view returns (Traversal.Iterator memory) +``` + +The function to get the iterator pointing to the first (leftmost) node in the uint256 tree. + +The functions can be utilized for an in-order traversal of the tree. + + +Parameters: + +| Name | Type | Description | +| :--- | :--------------------- | :---------- | +| tree | struct AvlTree.UintAVL | self. | + + +Return values: + +| Name | Type | Description | +| :--- | :------------------------ | :--------------------------------------- | +| [0] | struct Traversal.Iterator | The iterator pointing to the first node. | + +### last + +```solidity +function last( + AvlTree.UintAVL storage tree +) internal view returns (Traversal.Iterator memory) +``` + +The function to get the iterator pointing to the last (rightmost) node in the uint256 tree. + +The functions can be utilized for an in-order backwards traversal of the tree. + + +Parameters: + +| Name | Type | Description | +| :--- | :--------------------- | :---------- | +| tree | struct AvlTree.UintAVL | self. | + + +Return values: + +| Name | Type | Description | +| :--- | :------------------------ | :-------------------------------------- | +| [0] | struct Traversal.Iterator | The iterator pointing to the last node. | + +### isCustomComparatorSet + +```solidity +function isCustomComparatorSet( + AvlTree.UintAVL storage tree +) internal view returns (bool) +``` + +The function to check whether the custom comparator function is set for the uint256 tree. + + +Parameters: + +| Name | Type | Description | +| :--- | :--------------------- | :---------- | +| tree | struct AvlTree.UintAVL | self. | + + +Return values: + +| Name | Type | Description | +| :--- | :--- | :-------------------------------------------------------------- | +| [0] | bool | True if the custom comparator function is set, false otherwise. | + +### setComparator + +```solidity +function setComparator( + AvlTree.Bytes32AVL storage tree, + function(bytes32, bytes32) view returns (int256) comparator_ +) internal +``` + +The function to set a custom comparator function, that will be used to build the bytes32 tree. + + +Parameters: + +| Name | Type | Description | +| :---------- | :----------------------------------------------- | :----------------------------------------------------------------- | +| tree | struct AvlTree.Bytes32AVL | self. | +| comparator_ | function (bytes32,bytes32) view returns (int256) | The function that accepts keys and values of the nodes to compare. | + +### insert + +```solidity +function insert( + AvlTree.Bytes32AVL storage tree, + bytes32 key_, + bytes32 value_ +) internal +``` + +The function to insert a node into the bytes32 tree. +Complexity is O(log(n)), where n is the number of elements in the tree. + + + +Parameters: + +| Name | Type | Description | +| :----- | :------------------------ | :------------------- | +| tree | struct AvlTree.Bytes32AVL | self. | +| key_ | bytes32 | the key to insert. | +| value_ | bytes32 | the value to insert. | + +### remove + +```solidity +function remove(AvlTree.Bytes32AVL storage tree, bytes32 key_) internal +``` + +The function to remove a node from the bytes32 tree. +Complexity is O(log(n)), where n is the number of elements in the tree. + + + +Parameters: + +| Name | Type | Description | +| :--- | :------------------------ | :----------------------------- | +| tree | struct AvlTree.Bytes32AVL | self. | +| key_ | bytes32 | the key of the node to remove. | + +### get + +```solidity +function get( + AvlTree.Bytes32AVL storage tree, + bytes32 key_ +) internal view returns (bytes32) +``` + +The function to retrieve the value associated with a key in the bytes32 tree. +Complexity is O(log(n)), where n is the number of elements in the tree. + +Note: Reverts if the node with the specified key doesn't exist. + + + +Parameters: + +| Name | Type | Description | +| :--- | :------------------------ | :---------------------------------- | +| tree | struct AvlTree.Bytes32AVL | self. | +| key_ | bytes32 | the key to retrieve the value for. | + + +Return values: + +| Name | Type | Description | +| :--- | :------ | :--------------------------------- | +| [0] | bytes32 | The value associated with the key. | + +### tryGet + +```solidity +function tryGet( + AvlTree.Bytes32AVL storage tree, + bytes32 key_ +) internal view returns (bool, bytes32) +``` + +The function to try to retrieve the value associated with a key in the bytes32 tree. +Complexity is O(log(n)), where n is the number of elements in the tree. + + +Does not revert if the node with the specified key doesn't exist. + + + +Parameters: + +| Name | Type | Description | +| :--- | :------------------------ | :----------------------------------------------------- | +| tree | struct AvlTree.Bytes32AVL | self. | +| key_ | bytes32 | the key of the node to try to retrieve the value for. | + + +Return values: + +| Name | Type | Description | +| :--- | :------ | :---------------------------------------------------------------- | +| [0] | bool | True if the node with the specified key exists, false otherwise. | +| [1] | bytes32 | The value associated with the key. | + +### size + +```solidity +function size(AvlTree.Bytes32AVL storage tree) internal view returns (uint64) +``` + +The function to retrieve the size of the bytes32 tree. + + +Parameters: + +| Name | Type | Description | +| :--- | :------------------------ | :---------- | +| tree | struct AvlTree.Bytes32AVL | self. | + + +Return values: + +| Name | Type | Description | +| :--- | :----- | :-------------------- | +| [0] | uint64 | The size of the tree. | + +### first + +```solidity +function first( + AvlTree.Bytes32AVL storage tree +) internal view returns (Traversal.Iterator memory) +``` + +The function to get the iterator pointing to the first (leftmost) node in the bytes32 tree. + +The functions can be utilized for an in-order traversal of the tree. + + +Parameters: + +| Name | Type | Description | +| :--- | :------------------------ | :---------- | +| tree | struct AvlTree.Bytes32AVL | self. | + + +Return values: + +| Name | Type | Description | +| :--- | :------------------------ | :--------------------------------------- | +| [0] | struct Traversal.Iterator | The iterator pointing to the first node. | + +### last + +```solidity +function last( + AvlTree.Bytes32AVL storage tree +) internal view returns (Traversal.Iterator memory) +``` + +The function to get the iterator pointing to the last (rightmost) node in the bytes32 tree. + +The functions can be utilized for an in-order backwards traversal of the tree. + + +Parameters: + +| Name | Type | Description | +| :--- | :------------------------ | :---------- | +| tree | struct AvlTree.Bytes32AVL | self. | + + +Return values: + +| Name | Type | Description | +| :--- | :------------------------ | :-------------------------------------- | +| [0] | struct Traversal.Iterator | The iterator pointing to the last node. | + +### isCustomComparatorSet + +```solidity +function isCustomComparatorSet( + AvlTree.Bytes32AVL storage tree +) internal view returns (bool) +``` + +The function to check whether the custom comparator function is set for the bytes32 tree. + + +Parameters: + +| Name | Type | Description | +| :--- | :------------------------ | :---------- | +| tree | struct AvlTree.Bytes32AVL | self. | + + +Return values: + +| Name | Type | Description | +| :--- | :--- | :-------------------------------------------------------------- | +| [0] | bool | True if the custom comparator function is set, false otherwise. | + +### setComparator + +```solidity +function setComparator( + AvlTree.AddressAVL storage tree, + function(bytes32, bytes32) view returns (int256) comparator_ +) internal +``` + +The function to set a custom comparator function, that will be used to build the address tree. + + +Parameters: + +| Name | Type | Description | +| :---------- | :----------------------------------------------- | :----------------------------------------------------------------- | +| tree | struct AvlTree.AddressAVL | self. | +| comparator_ | function (bytes32,bytes32) view returns (int256) | The function that accepts keys and values of the nodes to compare. | + +### insert + +```solidity +function insert( + AvlTree.AddressAVL storage tree, + bytes32 key_, + address value_ +) internal +``` + +The function to insert a node into the address tree. +Complexity is O(log(n)), where n is the number of elements in the tree. + + + +Parameters: + +| Name | Type | Description | +| :----- | :------------------------ | :------------------- | +| tree | struct AvlTree.AddressAVL | self. | +| key_ | bytes32 | The key to insert. | +| value_ | address | The value to insert. | + +### remove + +```solidity +function remove(AvlTree.AddressAVL storage tree, bytes32 key_) internal +``` + +The function to remove a node from the address tree. +Complexity is O(log(n)), where n is the number of elements in the tree. + + + +Parameters: + +| Name | Type | Description | +| :--- | :------------------------ | :----------------------------- | +| tree | struct AvlTree.AddressAVL | self. | +| key_ | bytes32 | the key of the node to remove. | + +### get + +```solidity +function get( + AvlTree.AddressAVL storage tree, + bytes32 key_ +) internal view returns (address) +``` + +The function to retrieve the value associated with a key in the address tree. +Complexity is O(log(n)), where n is the number of elements in the tree. + +Note: Reverts if the node with the specified key doesn't exist. + + + +Parameters: + +| Name | Type | Description | +| :--- | :------------------------ | :---------------------------------- | +| tree | struct AvlTree.AddressAVL | self. | +| key_ | bytes32 | the key to retrieve the value for. | + + +Return values: + +| Name | Type | Description | +| :--- | :------ | :--------------------------------- | +| [0] | address | The value associated with the key. | + +### tryGet + +```solidity +function tryGet( + AvlTree.AddressAVL storage tree, + bytes32 key_ +) internal view returns (bool, address) +``` + +The function to try to retrieve the value associated with a key in the address tree. +Complexity is O(log(n)), where n is the number of elements in the tree. + + +Does not revert if the node with the specified key doesn't exist. + + + +Parameters: + +| Name | Type | Description | +| :--- | :------------------------ | :----------------------------------------------------- | +| tree | struct AvlTree.AddressAVL | self. | +| key_ | bytes32 | the key of the node to try to retrieve the value for. | + + +Return values: + +| Name | Type | Description | +| :--- | :------ | :---------------------------------------------------------------- | +| [0] | bool | True if the node with the specified key exists, false otherwise. | +| [1] | address | The value associated with the key. | + +### size + +```solidity +function size(AvlTree.AddressAVL storage tree) internal view returns (uint64) +``` + +The function to retrieve the size of the address tree. + + +Parameters: + +| Name | Type | Description | +| :--- | :------------------------ | :---------- | +| tree | struct AvlTree.AddressAVL | self. | + + +Return values: + +| Name | Type | Description | +| :--- | :----- | :-------------------- | +| [0] | uint64 | The size of the tree. | + +### first + +```solidity +function first( + AvlTree.AddressAVL storage tree +) internal view returns (Traversal.Iterator memory) +``` + +The function to get the iterator pointing to the first (leftmost) node in the address tree. + +The functions can be utilized for an in-order traversal of the tree. + + +Parameters: + +| Name | Type | Description | +| :--- | :------------------------ | :---------- | +| tree | struct AvlTree.AddressAVL | self. | + + +Return values: + +| Name | Type | Description | +| :--- | :------------------------ | :--------------------------------------- | +| [0] | struct Traversal.Iterator | The iterator pointing to the first node. | + +### last + +```solidity +function last( + AvlTree.AddressAVL storage tree +) internal view returns (Traversal.Iterator memory) +``` + +The function to get the iterator pointing to the last (rightmost) node in the address tree. + +The functions can be utilized for an in-order backwards traversal of the tree. + + +Parameters: + +| Name | Type | Description | +| :--- | :------------------------ | :---------- | +| tree | struct AvlTree.AddressAVL | self. | + + +Return values: + +| Name | Type | Description | +| :--- | :------------------------ | :-------------------------------------- | +| [0] | struct Traversal.Iterator | The iterator pointing to the last node. | + +### isCustomComparatorSet + +```solidity +function isCustomComparatorSet( + AvlTree.AddressAVL storage tree +) internal view returns (bool) +``` + +The function to check whether the custom comparator function is set for the address tree. + + +Parameters: + +| Name | Type | Description | +| :--- | :------------------------ | :---------- | +| tree | struct AvlTree.AddressAVL | self. | + + +Return values: + +| Name | Type | Description | +| :--- | :--- | :-------------------------------------------------------------- | +| [0] | bool | True if the custom comparator function is set, false otherwise. | diff --git a/docs/reference/contracts/libs/data-structures/Traversal.md b/docs/reference/contracts/libs/data-structures/Traversal.md new file mode 100644 index 0000000..2eebbf7 --- /dev/null +++ b/docs/reference/contracts/libs/data-structures/Traversal.md @@ -0,0 +1,192 @@ +# Traversal + +## Overview + +#### License: MIT + +```solidity +library Traversal +``` + +Traversal module + +This library provides functions to perform an in-order traversal of the AVL Tree +## Structs info + +### Iterator + +```solidity +struct Iterator { + uint256 treeMappingSlot; + uint64 currentNode; +} +``` + +Iterator struct to keep track of the current position in the tree. + + +Parameters: + +| Name | Type | Description | +| :-------------- | :------ | :---------------------------------------------- | +| treeMappingSlot | uint256 | The storage slot of the tree mapping. | +| currentNode | uint64 | The index of the current node in the traversal. | + +## Functions info + +### isValid + +```solidity +function isValid( + Traversal.Iterator memory iterator_ +) internal pure returns (bool) +``` + +The function to check if the iterator is currently valid (has not reached the end of the traversal). + + +Parameters: + +| Name | Type | Description | +| :-------- | :------------------------ | :---------- | +| iterator_ | struct Traversal.Iterator | self. | + + +Return values: + +| Name | Type | Description | +| :--- | :--- | :---------------------------------------------- | +| [0] | bool | True if the iterator is valid, false otherwise. | + +### hasNext + +```solidity +function hasNext( + Traversal.Iterator memory iterator_ +) internal view returns (bool) +``` + +The function to check if there is a next node in the traversal. + + +Parameters: + +| Name | Type | Description | +| :-------- | :------------------------ | :---------- | +| iterator_ | struct Traversal.Iterator | self. | + + +Return values: + +| Name | Type | Description | +| :--- | :--- | :--------------------------------------------- | +| [0] | bool | True if there is a next node, false otherwise. | + +### hasPrev + +```solidity +function hasPrev( + Traversal.Iterator memory iterator_ +) internal view returns (bool) +``` + +The function to check if there is a previous node in the traversal. + + +Parameters: + +| Name | Type | Description | +| :-------- | :------------------------ | :---------- | +| iterator_ | struct Traversal.Iterator | self. | + + +Return values: + +| Name | Type | Description | +| :--- | :--- | :------------------------------------------------- | +| [0] | bool | True if there is a previous node, false otherwise. | + +### next + +```solidity +function next( + Traversal.Iterator memory iterator_ +) internal view returns (bytes32, bytes32) +``` + +The function to move the iterator to the next node and retrieve its key and value. + + +Parameters: + +| Name | Type | Description | +| :-------- | :------------------------ | :---------- | +| iterator_ | struct Traversal.Iterator | self. | + + +Return values: + +| Name | Type | Description | +| :--- | :------ | :-------------------------- | +| [0] | bytes32 | The key of the next node. | +| [1] | bytes32 | The value of the next node. | + +### prev + +```solidity +function prev( + Traversal.Iterator memory iterator_ +) internal view returns (bytes32, bytes32) +``` + +The function to move the iterator to the previous node and retrieve its key and value. + + +Parameters: + +| Name | Type | Description | +| :-------- | :------------------------ | :---------- | +| iterator_ | struct Traversal.Iterator | self. | + + +Return values: + +| Name | Type | Description | +| :--- | :------ | :------------------------------ | +| [0] | bytes32 | The key of the previous node. | +| [1] | bytes32 | The value of the previous node. | + +### value + +```solidity +function value( + Traversal.Iterator memory iterator_ +) internal view returns (bytes32, bytes32) +``` + +The function to retrieve the key and value of the current node. + + +Parameters: + +| Name | Type | Description | +| :-------- | :------------------------ | :---------- | +| iterator_ | struct Traversal.Iterator | self. | + + +Return values: + +| Name | Type | Description | +| :--- | :------ | :----------------------------- | +| [0] | bytes32 | The key of the current node. | +| [1] | bytes32 | The value of the current node. | + +### _moveToAdjacent + +```solidity +function _moveToAdjacent( + Traversal.Iterator memory iterator_, + bool next_ +) internal view returns (bytes32, bytes32) +``` +