Utilities

This document is better viewed at https://docs.openzeppelin.com/community-contracts/utils

Miscellaneous contracts and libraries containing utility functions you can use to improve security, work with new data types, or safely use low-level primitives.

Structs

EnumerableSetExtended 

import "@openzeppelin/community-contracts/utils/structs/EnumerableSetExtended.sol";

Library for managing sets of non-value types.

Sets have the following properties:

  • Elements are added, removed, and checked for existence in constant time (O(1)).

  • Elements are enumerated in O(n). No guarantees are made on the ordering.

  • Set can be cleared (all elements removed) in O(n).

contract Example {
    // Add the library methods
    using EnumerableSetExtended for EnumerableSetExtended.StringSet;

    // Declare a set state variable
    EnumerableSetExtended.StringSet private mySet;
}

Sets of type string (StringSet), bytes (BytesSet) and bytes32[2] (Bytes32x2Set) are supported.

Trying to delete such a structure from storage will likely result in data corruption, rendering the structure unusable. See ethereum/solidity#11843 for more info.

In order to clean an EnumerableSet, you can either remove all elements one by one or create a fresh instance using an array of EnumerableSet.
This is an extension of openzeppelin/contracts/utils/struct/EnumerableSet.sol.
Functions

  • add(self, value)

  • remove(self, value)

  • clear(set)

  • contains(self, value)

  • length(self)

  • at(self, index)

  • values(self)

  • values(set, start, end)

  • add(self, value)

  • remove(self, value)

  • clear(set)

  • contains(self, value)

  • length(self)

  • at(self, index)

  • values(self)

  • values(set, start, end)

  • add(self, value)

  • remove(self, value)

  • clear(self)

  • contains(self, value)

  • length(self)

  • at(self, index)

  • values(self)

  • values(set, start, end)

add(struct EnumerableSetExtended.StringSet self, string value) → bool internal

Add a value to a set. O(1).

Returns true if the value was added to the set, that is if it was not already present.

remove(struct EnumerableSetExtended.StringSet self, string value) → bool internal

Removes a value from a set. O(1).

Returns true if the value was removed from the set, that is if it was present.

clear(struct EnumerableSetExtended.StringSet set) internal

Removes all the values from a set. O(n).

Developers should keep in mind that this function has an unbounded cost and using it may render the function uncallable if the set grows to the point where clearing it consumes too much gas to fit in a block.

contains(struct EnumerableSetExtended.StringSet self, string value) → bool internal

Returns true if the value is in the set. O(1).

length(struct EnumerableSetExtended.StringSet self) → uint256 internal

Returns the number of values on the set. O(1).

at(struct EnumerableSetExtended.StringSet self, uint256 index) → string internal

Returns the value stored at position index in the set. O(1).

Note that there are no guarantees on the ordering of values inside the array, and it may change when more values are added or removed.

Requirements:

  • index must be strictly less than length.

values(struct EnumerableSetExtended.StringSet self) → string[] internal

Return the entire set in an array

This operation will copy the entire storage to memory, which can be quite expensive. This is designed to mostly be used by view accessors that are queried without any gas fees. Developers should keep in mind that this function has an unbounded cost, and using it as part of a state-changing function may render the function uncallable if the set grows to a point where copying to memory consumes too much gas to fit in a block.

values(struct EnumerableSetExtended.StringSet set, uint256 start, uint256 end) → string[] internal

Return a slice of the set in an array

This operation will copy the entire storage to memory, which can be quite expensive. This is designed to mostly be used by view accessors that are queried without any gas fees. Developers should keep in mind that this function has an unbounded cost, and using it as part of a state-changing function may render the function uncallable if the set grows to a point where copying to memory consumes too much gas to fit in a block.

add(struct EnumerableSetExtended.BytesSet self, bytes value) → bool internal

Add a value to a set. O(1).

Returns true if the value was added to the set, that is if it was not already present.

remove(struct EnumerableSetExtended.BytesSet self, bytes value) → bool internal

Removes a value from a set. O(1).

Returns true if the value was removed from the set, that is if it was present.

clear(struct EnumerableSetExtended.BytesSet set) internal

Removes all the values from a set. O(n).

Developers should keep in mind that this function has an unbounded cost and using it may render the function uncallable if the set grows to the point where clearing it consumes too much gas to fit in a block.

contains(struct EnumerableSetExtended.BytesSet self, bytes value) → bool internal

Returns true if the value is in the set. O(1).

length(struct EnumerableSetExtended.BytesSet self) → uint256 internal

Returns the number of values on the set. O(1).

at(struct EnumerableSetExtended.BytesSet self, uint256 index) → bytes internal

Returns the value stored at position index in the set. O(1).

Note that there are no guarantees on the ordering of values inside the array, and it may change when more values are added or removed.

Requirements:

  • index must be strictly less than length.

values(struct EnumerableSetExtended.BytesSet self) → bytes[] internal

Return the entire set in an array

This operation will copy the entire storage to memory, which can be quite expensive. This is designed to mostly be used by view accessors that are queried without any gas fees. Developers should keep in mind that this function has an unbounded cost, and using it as part of a state-changing function may render the function uncallable if the set grows to a point where copying to memory consumes too much gas to fit in a block.

values(struct EnumerableSetExtended.BytesSet set, uint256 start, uint256 end) → bytes[] internal

Return a slice of the set in an array

This operation will copy the entire storage to memory, which can be quite expensive. This is designed to mostly be used by view accessors that are queried without any gas fees. Developers should keep in mind that this function has an unbounded cost, and using it as part of a state-changing function may render the function uncallable if the set grows to a point where copying to memory consumes too much gas to fit in a block.

add(struct EnumerableSetExtended.Bytes32x2Set self, bytes32[2] value) → bool internal

Add a value to a set. O(1).

Returns true if the value was added to the set, that is if it was not already present.

remove(struct EnumerableSetExtended.Bytes32x2Set self, bytes32[2] value) → bool internal

Removes a value from a set. O(1).

Returns true if the value was removed from the set, that is if it was present.

clear(struct EnumerableSetExtended.Bytes32x2Set self) internal

Removes all the values from a set. O(n).

Developers should keep in mind that this function has an unbounded cost and using it may render the function uncallable if the set grows to the point where clearing it consumes too much gas to fit in a block.

contains(struct EnumerableSetExtended.Bytes32x2Set self, bytes32[2] value) → bool internal

Returns true if the value is in the set. O(1).

length(struct EnumerableSetExtended.Bytes32x2Set self) → uint256 internal

Returns the number of values on the set. O(1).

at(struct EnumerableSetExtended.Bytes32x2Set self, uint256 index) → bytes32[2] internal

Returns the value stored at position index in the set. O(1).

Note that there are no guarantees on the ordering of values inside the array, and it may change when more values are added or removed.

Requirements:

  • index must be strictly less than length.

values(struct EnumerableSetExtended.Bytes32x2Set self) → bytes32[2][] internal

Return the entire set in an array

This operation will copy the entire storage to memory, which can be quite expensive. This is designed to mostly be used by view accessors that are queried without any gas fees. Developers should keep in mind that this function has an unbounded cost, and using it as part of a state-changing function may render the function uncallable if the set grows to a point where copying to memory consumes too much gas to fit in a block.

values(struct EnumerableSetExtended.Bytes32x2Set set, uint256 start, uint256 end) → bytes32[2][] internal

Return a slice of the set in an array

This operation will copy the entire storage to memory, which can be quite expensive. This is designed to mostly be used by view accessors that are queried without any gas fees. Developers should keep in mind that this function has an unbounded cost, and using it as part of a state-changing function may render the function uncallable if the set grows to a point where copying to memory consumes too much gas to fit in a block.

EnumerableMapExtended 

import "@openzeppelin/community-contracts/utils/structs/EnumerableMapExtended.sol";

Library for managing an enumerable variant of Solidity’s mapping type for non-value types as keys.

Maps have the following properties:

  • Entries are added, removed, and checked for existence in constant time (O(1)).

  • Entries are enumerated in O(n). No guarantees are made on the ordering.

  • Map can be cleared (all entries removed) in O(n).

contract Example {
    // Add the library methods
    using EnumerableMapExtended for EnumerableMapExtended.BytesToUintMap;

    // Declare a set state variable
    EnumerableMapExtended.BytesToUintMap private myMap;
}

The following map types are supported:

  • bytes → uint256 (BytesToUintMap)

  • string → string (StringToStringMap)

Trying to delete such a structure from storage will likely result in data corruption, rendering the structure unusable. See ethereum/solidity#11843 for more info.

In order to clean an EnumerableMap, you can either remove all elements one by one or create a fresh instance using an array of EnumerableMap.
Extensions of openzeppelin/contracts/utils/struct/EnumerableMap.sol.
Functions

  • set(map, key, value)

  • remove(map, key)

  • clear(map)

  • contains(map, key)

  • length(map)

  • at(map, index)

  • tryGet(map, key)

  • get(map, key)

  • keys(map)

  • keys(map, start, end)

  • set(map, key, value)

  • remove(map, key)

  • clear(map)

  • contains(map, key)

  • length(map)

  • at(map, index)

  • tryGet(map, key)

  • get(map, key)

  • keys(map)

  • keys(map, start, end)

Errors

  • EnumerableMapNonexistentBytesKey(key)

  • EnumerableMapNonexistentStringKey(key)

set(struct EnumerableMapExtended.BytesToUintMap map, bytes key, uint256 value) → bool internal

Adds a key-value pair to a map, or updates the value for an existing key. O(1).

Returns true if the key was added to the map, that is if it was not already present.

remove(struct EnumerableMapExtended.BytesToUintMap map, bytes key) → bool internal

Removes a key-value pair from a map. O(1).

Returns true if the key was removed from the map, that is if it was present.

clear(struct EnumerableMapExtended.BytesToUintMap map) internal

Removes all the entries from a map. O(n).

Developers should keep in mind that this function has an unbounded cost and using it may render the function uncallable if the map grows to the point where clearing it consumes too much gas to fit in a block.

contains(struct EnumerableMapExtended.BytesToUintMap map, bytes key) → bool internal

Returns true if the key is in the map. O(1).

length(struct EnumerableMapExtended.BytesToUintMap map) → uint256 internal

Returns the number of key-value pairs in the map. O(1).

at(struct EnumerableMapExtended.BytesToUintMap map, uint256 index) → bytes key, uint256 value internal

Returns the key-value pair stored at position index in the map. O(1).

Note that there are no guarantees on the ordering of entries inside the array, and it may change when more entries are added or removed.

Requirements:

  • index must be strictly less than length.

tryGet(struct EnumerableMapExtended.BytesToUintMap map, bytes key) → bool exists, uint256 value internal

Tries to returns the value associated with key. O(1). Does not revert if key is not in the map.

get(struct EnumerableMapExtended.BytesToUintMap map, bytes key) → uint256 value internal

Returns the value associated with key. O(1).

Requirements:

  • key must be in the map.

keys(struct EnumerableMapExtended.BytesToUintMap map) → bytes[] internal

Returns an array containing all the keys

This operation will copy the entire storage to memory, which can be quite expensive. This is designed to mostly be used by view accessors that are queried without any gas fees. Developers should keep in mind that this function has an unbounded cost, and using it as part of a state-changing function may render the function uncallable if the map grows to a point where copying to memory consumes too much gas to fit in a block.

keys(struct EnumerableMapExtended.BytesToUintMap map, uint256 start, uint256 end) → bytes[] internal

Returns an array containing a slice of the keys

This operation will copy the entire storage to memory, which can be quite expensive. This is designed to mostly be used by view accessors that are queried without any gas fees. Developers should keep in mind that this function has an unbounded cost, and using it as part of a state-changing function may render the function uncallable if the map grows to a point where copying to memory consumes too much gas to fit in a block.

set(struct EnumerableMapExtended.StringToStringMap map, string key, string value) → bool internal

Adds a key-value pair to a map, or updates the value for an existing key. O(1).

Returns true if the key was added to the map, that is if it was not already present.

remove(struct EnumerableMapExtended.StringToStringMap map, string key) → bool internal

Removes a key-value pair from a map. O(1).

Returns true if the key was removed from the map, that is if it was present.

clear(struct EnumerableMapExtended.StringToStringMap map) internal

Removes all the entries from a map. O(n).

Developers should keep in mind that this function has an unbounded cost and using it may render the function uncallable if the map grows to the point where clearing it consumes too much gas to fit in a block.

contains(struct EnumerableMapExtended.StringToStringMap map, string key) → bool internal

Returns true if the key is in the map. O(1).

length(struct EnumerableMapExtended.StringToStringMap map) → uint256 internal

Returns the number of key-value pairs in the map. O(1).

at(struct EnumerableMapExtended.StringToStringMap map, uint256 index) → string key, string value internal

Returns the key-value pair stored at position index in the map. O(1).

Note that there are no guarantees on the ordering of entries inside the array, and it may change when more entries are added or removed.

Requirements:

  • index must be strictly less than length.

tryGet(struct EnumerableMapExtended.StringToStringMap map, string key) → bool exists, string value internal

Tries to returns the value associated with key. O(1). Does not revert if key is not in the map.

get(struct EnumerableMapExtended.StringToStringMap map, string key) → string value internal

Returns the value associated with key. O(1).

Requirements:

  • key must be in the map.

keys(struct EnumerableMapExtended.StringToStringMap map) → string[] internal

Returns an array containing all the keys

This operation will copy the entire storage to memory, which can be quite expensive. This is designed to mostly be used by view accessors that are queried without any gas fees. Developers should keep in mind that this function has an unbounded cost, and using it as part of a state-changing function may render the function uncallable if the map grows to a point where copying to memory consumes too much gas to fit in a block.

keys(struct EnumerableMapExtended.StringToStringMap map, uint256 start, uint256 end) → string[] internal

Returns an array containing a slice of the keys

This operation will copy the entire storage to memory, which can be quite expensive. This is designed to mostly be used by view accessors that are queried without any gas fees. Developers should keep in mind that this function has an unbounded cost, and using it as part of a state-changing function may render the function uncallable if the map grows to a point where copying to memory consumes too much gas to fit in a block.

EnumerableMapNonexistentBytesKey(bytes key) error

Query for a nonexistent map key.

EnumerableMapNonexistentStringKey(string key) error

Query for a nonexistent map key.

Libraries

Masks 

import "@openzeppelin/community-contracts/utils/Masks.sol";

Library for handling bit masks

Functions

  • toMask(group)

  • toMask(groups)

  • get(self, group)

  • isEmpty(self)

  • complement(m1)

  • union(m1, m2)

  • intersection(m1, m2)

  • difference(m1, m2)

  • symmetricDifference(m1, m2)

toMask(uint8 group) → Masks.Mask internal

Returns a new mask with the bit at group index set to 1.

toMask(uint8[] groups) → Masks.Mask internal

Returns a new mask with the bits at groups indices set to 1.

get(Masks.Mask self, uint8 group) → bool internal

Get value of the mask at group index

isEmpty(Masks.Mask self) → bool internal

Whether the mask is bytes32(0)

complement(Masks.Mask m1) → Masks.Mask internal

Invert the bits of a mask

union(Masks.Mask m1, Masks.Mask m2) → Masks.Mask internal

Perform a bitwise OR operation on two masks

intersection(Masks.Mask m1, Masks.Mask m2) → Masks.Mask internal

Perform a bitwise AND operation on two masks

difference(Masks.Mask m1, Masks.Mask m2) → Masks.Mask internal

Perform a bitwise difference operation on two masks (m1 - m2)

symmetricDifference(Masks.Mask m1, Masks.Mask m2) → Masks.Mask internal

Returns the symmetric difference (∆) of two masks, also known as disjunctive union or exclusive OR (XOR)

← Token
Cryptography →