|
1 | 1 | // SPDX-License-Identifier: MIT |
2 | 2 |
|
3 | | -pragma solidity ^0.8.20; |
| 3 | +pragma solidity ^0.8.24; |
| 4 | + |
| 5 | +import {Panic} from "./Panic.sol"; |
| 6 | +import {Math} from "./math/Math.sol"; |
4 | 7 |
|
5 | 8 | /** |
6 | 9 | * @dev Utilities to manipulate memory. |
7 | 10 | * |
8 | 11 | * Memory is a contiguous and dynamic byte array in which Solidity stores non-primitive types. |
9 | | - * This library provides functions to manipulate pointers to this dynamic array. |
| 12 | + * This library provides functions to manipulate pointers to this dynamic array and work with slices of it. |
| 13 | + * |
| 14 | + * Slices provide a view into a portion of memory without copying data, enabling efficient substring operations. |
10 | 15 | * |
11 | | - * WARNING: When manipulating memory, make sure to follow the Solidity documentation |
| 16 | + * WARNING: When manipulating memory pointers or slices, make sure to follow the Solidity documentation |
12 | 17 | * guidelines for https://docs.soliditylang.org/en/v0.8.20/assembly.html#memory-safety[Memory Safety]. |
13 | 18 | */ |
14 | 19 | library Memory { |
@@ -41,4 +46,89 @@ library Memory { |
41 | 46 | function asPointer(bytes32 value) internal pure returns (Pointer) { |
42 | 47 | return Pointer.wrap(value); |
43 | 48 | } |
| 49 | + |
| 50 | + /// @dev Move a pointer forward by a given offset. |
| 51 | + function forward(Pointer ptr, uint256 offset) internal pure returns (Pointer) { |
| 52 | + return Pointer.wrap(bytes32(uint256(Pointer.unwrap(ptr)) + offset)); |
| 53 | + } |
| 54 | + |
| 55 | + /// @dev Equality comparator for memory pointers. |
| 56 | + function equal(Pointer ptr1, Pointer ptr2) internal pure returns (bool) { |
| 57 | + return Pointer.unwrap(ptr1) == Pointer.unwrap(ptr2); |
| 58 | + } |
| 59 | + |
| 60 | + type Slice is bytes32; |
| 61 | + |
| 62 | + /// @dev Get a slice representation of a bytes object in memory |
| 63 | + function asSlice(bytes memory self) internal pure returns (Slice result) { |
| 64 | + assembly ("memory-safe") { |
| 65 | + result := or(shl(128, mload(self)), add(self, 0x20)) |
| 66 | + } |
| 67 | + } |
| 68 | + |
| 69 | + /// @dev Returns the length of a given slice (equiv to self.length for calldata slices) |
| 70 | + function length(Slice self) internal pure returns (uint256 result) { |
| 71 | + assembly ("memory-safe") { |
| 72 | + result := shr(128, self) |
| 73 | + } |
| 74 | + } |
| 75 | + |
| 76 | + /// @dev Offset a memory slice (equivalent to self[start:] for calldata slices) |
| 77 | + function slice(Slice self, uint256 offset) internal pure returns (Slice) { |
| 78 | + if (offset > length(self)) Panic.panic(Panic.ARRAY_OUT_OF_BOUNDS); |
| 79 | + return _asSlice(length(self) - offset, forward(_pointer(self), offset)); |
| 80 | + } |
| 81 | + |
| 82 | + /// @dev Offset and cut a Slice (equivalent to self[start:start+length] for calldata slices) |
| 83 | + function slice(Slice self, uint256 offset, uint256 len) internal pure returns (Slice) { |
| 84 | + if (offset + len > length(self)) Panic.panic(Panic.ARRAY_OUT_OF_BOUNDS); |
| 85 | + return _asSlice(len, forward(_pointer(self), offset)); |
| 86 | + } |
| 87 | + |
| 88 | + /** |
| 89 | + * @dev Read a bytes32 buffer from a given Slice at a specific offset |
| 90 | + * |
| 91 | + * NOTE: If offset > length(slice) - 0x20, part of the return value will be out of bound of the slice. These bytes are zeroed. |
| 92 | + */ |
| 93 | + function load(Slice self, uint256 offset) internal pure returns (bytes32 value) { |
| 94 | + uint256 outOfBoundBytes = Math.saturatingSub(0x20 + offset, length(self)); |
| 95 | + if (outOfBoundBytes > 0x1f) Panic.panic(Panic.ARRAY_OUT_OF_BOUNDS); |
| 96 | + |
| 97 | + assembly ("memory-safe") { |
| 98 | + value := and(mload(add(and(self, shr(128, not(0))), offset)), shl(mul(8, outOfBoundBytes), not(0))) |
| 99 | + } |
| 100 | + } |
| 101 | + |
| 102 | + /// @dev Extract the data corresponding to a Slice (allocate new memory) |
| 103 | + function toBytes(Slice self) internal pure returns (bytes memory result) { |
| 104 | + uint256 len = length(self); |
| 105 | + Memory.Pointer ptr = _pointer(self); |
| 106 | + assembly ("memory-safe") { |
| 107 | + result := mload(0x40) |
| 108 | + mstore(result, len) |
| 109 | + mcopy(add(result, 0x20), ptr, len) |
| 110 | + mstore(0x40, add(add(result, len), 0x20)) |
| 111 | + } |
| 112 | + } |
| 113 | + |
| 114 | + /** |
| 115 | + * @dev Private helper: create a slice from raw values (length and pointer) |
| 116 | + * |
| 117 | + * NOTE: this function MUST NOT be called with `len` or `ptr` that exceed `2**128-1`. This should never be |
| 118 | + * the case of slices produced by `asSlice(bytes)`, and function that reduce the scope of slices |
| 119 | + * (`slice(Slice,uint256)` and `slice(Slice,uint256, uint256)`) should not cause this issue if the parent slice is |
| 120 | + * correct. |
| 121 | + */ |
| 122 | + function _asSlice(uint256 len, Memory.Pointer ptr) private pure returns (Slice result) { |
| 123 | + assembly ("memory-safe") { |
| 124 | + result := or(shl(128, len), ptr) |
| 125 | + } |
| 126 | + } |
| 127 | + |
| 128 | + /// @dev Returns the memory location of a given slice (equiv to self.offset for calldata slices) |
| 129 | + function _pointer(Slice self) private pure returns (Memory.Pointer result) { |
| 130 | + assembly ("memory-safe") { |
| 131 | + result := and(self, shr(128, not(0))) |
| 132 | + } |
| 133 | + } |
44 | 134 | } |
0 commit comments