Set
Author: Euler Labs (https://www.eulerlabs.com/)
This library provides functions for managing sets of addresses.
The maximum number of elements in the set is defined by the constant SET_MAX_ELEMENTS.
State Variables
EMPTY_ELEMENT_OFFSET
uint8 internal constant EMPTY_ELEMENT_OFFSET = 1;
DUMMY_STAMP
uint8 internal constant DUMMY_STAMP = 1;
Functions
initialize
Initializes the set by setting the stamp field of the SetStorage and the stamp field of elements to DUMMY_STAMP.
The stamp field is used to keep the storage slot non-zero when the element is removed. It allows for cheaper SSTORE when an element is inserted.
function initialize(SetStorage storage setStorage) internal;
Parameters
| Name | Type | Description |
|---|---|---|
setStorage | SetStorage | The set storage whose stamp fields will be initialized. |
insert
Inserts an element and returns information whether the element was inserted or not.
Reverts if the set is full but the element is not in the set storage.
function insert(SetStorage storage setStorage, address element) internal returns (bool);
Parameters
| Name | Type | Description |
|---|---|---|
setStorage | SetStorage | The set storage to which the element will be inserted. |
element | address | The element to be inserted. |
Returns
| Name | Type | Description |
|---|---|---|
<none> | bool | A boolean value that indicates whether the element was inserted or not. If the element was already in the set storage, it returns false. |
remove
Removes an element and returns information whether the element was removed or not.
This operation may affect the order of elements in the array of elements obtained using get() function.
function remove(SetStorage storage setStorage, address element) internal returns (bool);
Parameters
| Name | Type | Description |
|---|---|---|
setStorage | SetStorage | The set storage from which the element will be removed. |
element | address | The element to be removed. |
Returns
| Name | Type | Description |
|---|---|---|
<none> | bool | A boolean value that indicates whether the element was removed or not. If the element was not in the set storage, it returns false. |
reorder
Swaps the position of two elements so that they appear switched in the array of elements obtained using get() function.
The first index must not be greater than or equal to the second index. Indices must not be out of bounds. The function will revert if the indices are invalid.
function reorder(SetStorage storage setStorage, uint8 index1, uint8 index2) internal;
Parameters
| Name | Type | Description |
|---|---|---|
setStorage | SetStorage | The set storage for which the elements will be swapped. |
index1 | uint8 | The index of the first element to be swapped. |
index2 | uint8 | The index of the second element to be swapped. |
setMetadata
Sets the metadata for the set storage.
function setMetadata(SetStorage storage setStorage, uint80 metadata) internal;
Parameters
| Name | Type | Description |
|---|---|---|
setStorage | SetStorage | The storage structure where metadata will be set. |
metadata | uint80 | The metadata value to set. |
get
Returns an array of elements contained in the storage.
The order of the elements in the array may be affected by performing operations on the set.
function get(SetStorage storage setStorage) internal view returns (address[] memory);
Parameters
| Name | Type | Description |
|---|---|---|
setStorage | SetStorage | The set storage to be processed. |
Returns
| Name | Type | Description |
|---|---|---|
<none> | address[] | An array that contains the same elements as the set storage. |
getMetadata
Retrieves the metadata from the set storage.
function getMetadata(SetStorage storage setStorage) internal view returns (uint80);
Parameters
| Name | Type | Description |
|---|---|---|
setStorage | SetStorage | The storage structure from which metadata is retrieved. |
Returns
| Name | Type | Description |
|---|---|---|
<none> | uint80 | The metadata value. |
contains
Checks if the set storage contains a given element and returns a boolean value that indicates the result.
function contains(SetStorage storage setStorage, address element) internal view returns (bool);
Parameters
| Name | Type | Description |
|---|---|---|
setStorage | SetStorage | The set storage to be searched. |
element | address | The element to be searched for. |
Returns
| Name | Type | Description |
|---|---|---|
<none> | bool | A boolean value that indicates whether the set storage includes the element or not. |
forEachAndClear
Iterates over each element in the set and applies the callback function to it.
The set is cleared as a result of this call. Considering that this function does not follow the Checks-Effects-Interactions pattern, the function using it must prevent re-entrancy.
function forEachAndClear(SetStorage storage setStorage, function(address) callback) internal;
Parameters
| Name | Type | Description |
|---|---|---|
setStorage | SetStorage | The set storage to be processed. |
callback | function (address) | The function to be applied to each element. |
forEachAndClearWithResult
Iterates over each element in the set and applies the callback function to it, returning the array of callback results.
The set is cleared as a result of this call. Considering that this function does not follow the Checks-Effects-Interactions pattern, the function using it must prevent re-entrancy.
function forEachAndClearWithResult(
SetStorage storage setStorage,
function(address) returns (bool, bytes memory) callback
) internal returns (bytes[] memory);
Parameters
| Name | Type | Description |
|---|---|---|
setStorage | SetStorage | The set storage to be processed. |
callback | function (address) returns (bool, bytes memory) | The function to be applied to each element. |
Returns
| Name | Type | Description |
|---|---|---|
<none> | bytes[] | result An array of encoded bytes that are the addresses passed to the callback function and results of calling it. |
Errors
TooManyElements
error TooManyElements();
InvalidIndex
error InvalidIndex();