MemViewLib
Library for operations with the memory views. Forked from https://github.com/summa-tx/memview-sol with several breaking changes:
- The codebase is ported to Solidity 0.8
- Custom errors are added
- The runtime type checking is replaced with compile-time check provided by User-Defined Value Types https://docs.soliditylang.org/en/latest/types.html#user-defined-value-types
- uint256 is used as the underlying type for the "memory view" instead of bytes29. It is wrapped into MemView custom type in order not to be confused with actual integers.
- Therefore the "type" field is discarded, allowing to allocate 16 bytes for both view location and length
- The documentation is expanded
- Library functions unused by the rest of the codebase are removed
Attach library functions to MemView
Functions
build
Stack layout for uint256 (from highest bits to lowest) (32 .. 16] loc 16 bytes Memory address of underlying bytes (16 .. 00] len 16 bytes Length of underlying bytes
Instantiate a new untyped memory view. This should generally not be called directly.
Prefer ref wherever possible.
function build(uint256 loc_, uint256 len_) internal pure returns (MemView);
Parameters
| Name | Type | Description |
|---|---|---|
loc_ | uint256 | The memory address |
len_ | uint256 | The length |
Returns
| Name | Type | Description |
|---|---|---|
<none> | MemView | The new view with the specified location and length |
ref
Instantiate a memory view from a byte array.
Note that due to Solidity memory representation, it is not possible to
implement a deref, as the bytes type stores its len in memory.
function ref(bytes memory arr) internal pure returns (MemView);
Parameters
| Name | Type | Description |
|---|---|---|
arr | bytes | The byte array |
Returns
| Name | Type | Description |
|---|---|---|
<none> | MemView | The memory view over the provided byte array |
clone
Copies the referenced memory to a new loc in memory, returning a bytes pointing to the new memory.
function clone(MemView memView) internal view returns (bytes memory arr);
Parameters
| Name | Type | Description |
|---|---|---|
memView | MemView | The memory view |
Returns
| Name | Type | Description |
|---|---|---|
arr | bytes | The cloned byte array |
join
Copies all views, joins them into a new bytearray.
function join(MemView[] memory memViews) internal view returns (bytes memory arr);
Parameters
| Name | Type | Description |
|---|---|---|
memViews | MemView[] | The memory views |
Returns
| Name | Type | Description |
|---|---|---|
arr | bytes | The new byte array with joined data behind the given views |
loc
Returns the memory address of the underlying bytes.
function loc(MemView memView) internal pure returns (uint256 loc_);
Parameters
| Name | Type | Description |
|---|---|---|
memView | MemView | The memory view |
Returns
| Name | Type | Description |
|---|---|---|
loc_ | uint256 | The memory address |
len
Returns the number of bytes of the view.
function len(MemView memView) internal pure returns (uint256 len_);
Parameters
| Name | Type | Description |
|---|---|---|
memView | MemView | The memory view |
Returns
| Name | Type | Description |
|---|---|---|
len_ | uint256 | The length of the view |
end
Returns the endpoint of memView.
function end(MemView memView) internal pure returns (uint256 end_);
Parameters
| Name | Type | Description |
|---|---|---|
memView | MemView | The memory view |
Returns
| Name | Type | Description |
|---|---|---|
end_ | uint256 | The endpoint of memView |
words
Returns the number of memory words this memory view occupies, rounded up.
function words(MemView memView) internal pure returns (uint256 words_);
Parameters
| Name | Type | Description |
|---|---|---|
memView | MemView | The memory view |
Returns
| Name | Type | Description |
|---|---|---|
words_ | uint256 | The number of memory words |
footprint
Returns the in-memory footprint of a fresh copy of the view.
function footprint(MemView memView) internal pure returns (uint256 footprint_);
Parameters
| Name | Type | Description |
|---|---|---|
memView | MemView | The memory view |
Returns
| Name | Type | Description |
|---|---|---|
footprint_ | uint256 | The in-memory footprint of a fresh copy of the view. |
keccak
Returns the keccak256 hash of the underlying memory
function keccak(MemView memView) internal pure returns (bytes32 digest);
Parameters
| Name | Type | Description |
|---|---|---|
memView | MemView | The memory view |
Returns
| Name | Type | Description |
|---|---|---|
digest | bytes32 | The keccak256 hash of the underlying memory |
keccakSalted
Adds a salt to the keccak256 hash of the underlying data and returns the keccak256 hash of the resulting data.
function keccakSalted(MemView memView, bytes32 salt) internal pure returns (bytes32 digestSalted);
Parameters
| Name | Type | Description |
|---|---|---|
memView | MemView | The memory view |
salt | bytes32 |
Returns
| Name | Type | Description |
|---|---|---|
digestSalted | bytes32 | keccak256(salt, keccak256(memView)) |
slice
Safe slicing without memory modification.
function slice(MemView memView, uint256 index_, uint256 len_) internal pure returns (MemView);
Parameters
| Name | Type | Description |
|---|---|---|
memView | MemView | The memory view |
index_ | uint256 | The start index |
len_ | uint256 | The length |
Returns
| Name | Type | Description |
|---|---|---|
<none> | MemView | The new view for the slice of the given length starting from the given index |
sliceFrom
Shortcut to slice. Gets a view representing bytes from index to end(memView).
function sliceFrom(MemView memView, uint256 index_) internal pure returns (MemView);
Parameters
| Name | Type | Description |
|---|---|---|
memView | MemView | The memory view |
index_ | uint256 | The start index |
Returns
| Name | Type | Description |
|---|---|---|
<none> | MemView | The new view for the slice starting from the given index until the initial view endpoint |
prefix
Shortcut to slice. Gets a view representing the first len bytes.
function prefix(MemView memView, uint256 len_) internal pure returns (MemView);
Parameters
| Name | Type | Description |
|---|---|---|
memView | MemView | The memory view |
len_ | uint256 | The length |
Returns
| Name | Type | Description |
|---|---|---|
<none> | MemView | The new view for the slice of the given length starting from the initial view beginning |
postfix
Shortcut to slice. Gets a view representing the last len byte.
function postfix(MemView memView, uint256 len_) internal pure returns (MemView);
Parameters
| Name | Type | Description |
|---|---|---|
memView | MemView | The memory view |
len_ | uint256 | The length |
Returns
| Name | Type | Description |
|---|---|---|
<none> | MemView | The new view for the slice of the given length until the initial view endpoint |
index
Load up to 32 bytes from the view onto the stack.
Returns a bytes32 with only the bytes_ HIGHEST bytes set.
This can be immediately cast to a smaller fixed-length byte array.
To automatically cast to an integer, use indexUint.
function index(MemView memView, uint256 index_, uint256 bytes_) internal pure returns (bytes32 result);
Parameters
| Name | Type | Description |
|---|---|---|
memView | MemView | The memory view |
index_ | uint256 | The index |
bytes_ | uint256 | The amount of bytes to load onto the stack |
Returns
| Name | Type | Description |
|---|---|---|
result | bytes32 | The 32 byte result having only bytes_ highest bytes set |
indexUint
Parse an unsigned integer from the view at index.
Requires that the view have >= bytes_ bytes following that index.
function indexUint(MemView memView, uint256 index_, uint256 bytes_) internal pure returns (uint256);
Parameters
| Name | Type | Description |
|---|---|---|
memView | MemView | The memory view |
index_ | uint256 | The index |
bytes_ | uint256 | The amount of bytes to load onto the stack |
Returns
| Name | Type | Description |
|---|---|---|
<none> | uint256 | The unsigned integer |
indexAddress
Parse an address from the view at index.
Requires that the view have >= 20 bytes following that index.
function indexAddress(MemView memView, uint256 index_) internal pure returns (address);
Parameters
| Name | Type | Description |
|---|---|---|
memView | MemView | The memory view |
index_ | uint256 | The index |
Returns
| Name | Type | Description |
|---|---|---|
<none> | address | The address |
_unsafeBuildUnchecked
Returns a memory view over the specified memory location without checking if it points to unallocated memory.
function _unsafeBuildUnchecked(uint256 loc_, uint256 len_) private pure returns (MemView);
_unsafeCopyTo
Copy the view to a location, return an unsafe memory reference
Super Dangerous direct memory access. This reference can be overwritten if anything else modifies memory (!!!). As such it MUST be consumed IMMEDIATELY. Update the free memory pointer to ensure the copied data is not overwritten. This function is private to prevent unsafe usage by callers.
function _unsafeCopyTo(MemView memView, uint256 newLoc) private view returns (MemView);
Parameters
| Name | Type | Description |
|---|---|---|
memView | MemView | The memory view |
newLoc | uint256 | The new location to copy the underlying view data |
Returns
| Name | Type | Description |
|---|---|---|
<none> | MemView | The memory view over the unsafe memory with the copied underlying data |
_unsafeJoin
Join the views in memory, return an unsafe reference to the memory.
Super Dangerous direct memory access. This reference can be overwritten if anything else modifies memory (!!!). As such it MUST be consumed IMMEDIATELY. Update the free memory pointer to ensure the copied data is not overwritten. This function is private to prevent unsafe usage by callers.
function _unsafeJoin(MemView[] memory memViews, uint256 location) private view returns (MemView);
Parameters
| Name | Type | Description |
|---|---|---|
memViews | MemView[] | The memory views |
location | uint256 |
Returns
| Name | Type | Description |
|---|---|---|
<none> | MemView | The conjoined view pointing to the new memory |