Sitelet https://github.com/Vectorized/solady/blob/main/docs/utils/libstring.md
Skip to content

libstring.md

Latest commit

 

History

History
830 lines (598 loc) · 18.2 KB

libstring.md

File metadata and controls

830 lines (598 loc) · 18.2 KB
Raw

LibString

Library for converting numbers into strings and other string operations.

Note:

For performance and bytecode compactness, most of the string operations are restricted to byte strings (7-bit ASCII), except where otherwise specified. Usage of byte string operations on charsets with runes spanning two or more bytes can lead to undefined behavior.

Structs

StringStorage

struct StringStorage {
    bytes32 _spacer;
}

Goated string storage struct that totally MOGs, no cap, fr.
Uses less gas and bytecode than Solidity's native string storage. It's meta af.
Packs length with the first 31 bytes if <255 bytes, so it’s mad tight.

Custom Errors

HexLengthInsufficient()

error HexLengthInsufficient()

The length of the output is too small to contain all the hex digits.

TooBigForSmallString()

error TooBigForSmallString()

The length of the string is more than 32 bytes.

StringNot7BitASCII()

error StringNot7BitASCII()

The input string must be a 7-bit ASCII.

Constants

NOT_FOUND

uint256 internal constant NOT_FOUND = type(uint256).max

The constant returned when the search is not found in the string.

ALPHANUMERIC_7_BIT_ASCII

uint128 internal constant ALPHANUMERIC_7_BIT_ASCII =
    0x7fffffe07fffffe03ff000000000000

Lookup for '0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ'.

LETTERS_7_BIT_ASCII

uint128 internal constant LETTERS_7_BIT_ASCII =
    0x7fffffe07fffffe0000000000000000

Lookup for 'abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ'.

LOWERCASE_7_BIT_ASCII

uint128 internal constant LOWERCASE_7_BIT_ASCII =
    0x7fffffe000000000000000000000000

Lookup for 'abcdefghijklmnopqrstuvwxyz'.

UPPERCASE_7_BIT_ASCII

uint128 internal constant UPPERCASE_7_BIT_ASCII = 0x7fffffe0000000000000000

Lookup for 'ABCDEFGHIJKLMNOPQRSTUVWXYZ'.

DIGITS_7_BIT_ASCII

uint128 internal constant DIGITS_7_BIT_ASCII = 0x3ff000000000000

Lookup for '0123456789'.

HEXDIGITS_7_BIT_ASCII

uint128 internal constant HEXDIGITS_7_BIT_ASCII =
    0x7e0000007e03ff000000000000

Lookup for '0123456789abcdefABCDEF'.

OCTDIGITS_7_BIT_ASCII

uint128 internal constant OCTDIGITS_7_BIT_ASCII = 0xff000000000000

Lookup for '01234567'.

PRINTABLE_7_BIT_ASCII

uint128 internal constant PRINTABLE_7_BIT_ASCII =
    0x7fffffffffffffffffffffff00003e00

Lookup for '0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ!"#$%&'()*+,-./:;<=>?@[\]^_`{|}~ \t\n\r\x0b\x0c'.

PUNCTUATION_7_BIT_ASCII

uint128 internal constant PUNCTUATION_7_BIT_ASCII =
    0x78000001f8000001fc00fffe00000000

Lookup for '!"#$%&'()*+,-./:;<=>?@[\]^_`{|}~'.

WHITESPACE_7_BIT_ASCII

uint128 internal constant WHITESPACE_7_BIT_ASCII = 0x100003e00

Lookup for ' \t\n\r\x0b\x0c'.

String Storage Operations

set(StringStorage,string)

function set(StringStorage storage $, string memory s) internal

Sets the value of the string storage $ to s.

setCalldata(StringStorage,string)

function setCalldata(StringStorage storage $, string calldata s) internal

Sets the value of the string storage $ to s.

clear(StringStorage)

function clear(StringStorage storage $) internal

Sets the value of the string storage $ to the empty string.

isEmpty(StringStorage)

function isEmpty(StringStorage storage $) internal view returns (bool)

Returns whether the value stored is $ is the empty string "".

length(StringStorage)

function length(StringStorage storage $) internal view returns (uint256)

Returns the length of the value stored in $.

get(StringStorage)

function get(StringStorage storage $)
    internal
    view
    returns (string memory)

Returns the value stored in $.

uint8At(StringStorage,uint256)

function uint8At(StringStorage storage $, uint256 i)
    internal
    view
    returns (uint8)

Returns the uint8 at index i. If out-of-bounds, returns 0.

bytesStorage(StringStorage)

function bytesStorage(StringStorage storage $)
    internal
    pure
    returns (LibBytes.BytesStorage storage casted)

Helper to cast $ to a BytesStorage.

Decimal Operations

toString(uint256)

function toString(uint256 value)
    internal
    pure
    returns (string memory result)

Returns the base 10 decimal representation of value.

toString(int256)

function toString(int256 value)
    internal
    pure
    returns (string memory result)

Returns the base 10 decimal representation of value.

Hexadecimal Operations

toHexString(uint256,uint256)

function toHexString(uint256 value, uint256 byteCount)
    internal
    pure
    returns (string memory result)

Returns the hexadecimal representation of value,
left-padded to an input length of byteCount bytes.
The output is prefixed with "0x" encoded using 2 hexadecimal digits per byte,
giving a total length of byteCount * 2 + 2 bytes.
Reverts if byteCount is too small for the output to contain all the digits.

toHexStringNoPrefix(uint256,uint256)

function toHexStringNoPrefix(uint256 value, uint256 byteCount)
    internal
    pure
    returns (string memory result)

Returns the hexadecimal representation of value,
left-padded to an input length of byteCount bytes.
The output is not prefixed with "0x" and is encoded using 2 hexadecimal digits per byte,
giving a total length of byteCount * 2 bytes.
Reverts if byteCount is too small for the output to contain all the digits.

toHexString(uint256)

function toHexString(uint256 value)
    internal
    pure
    returns (string memory result)

Returns the hexadecimal representation of value.
The output is prefixed with "0x" and encoded using 2 hexadecimal digits per byte.
As address are 20 bytes long, the output will left-padded to have
a length of 20 * 2 + 2 bytes.

toMinimalHexString(uint256)

function toMinimalHexString(uint256 value)
    internal
    pure
    returns (string memory result)

Returns the hexadecimal representation of value.
The output is prefixed with "0x".
The output excludes leading "0" from the toHexString output.
0x00: "0x0", 0x01: "0x1", 0x12: "0x12", 0x123: "0x123".

toMinimalHexStringNoPrefix(uint256)

function toMinimalHexStringNoPrefix(uint256 value)
    internal
    pure
    returns (string memory result)

Returns the hexadecimal representation of value.
The output excludes leading "0" from the toHexStringNoPrefix output.
0x00: "0", 0x01: "1", 0x12: "12", 0x123: "123".

toHexStringNoPrefix(uint256)

function toHexStringNoPrefix(uint256 value)
    internal
    pure
    returns (string memory result)

Returns the hexadecimal representation of value.
The output is encoded using 2 hexadecimal digits per byte.
As address are 20 bytes long, the output will left-padded to have
a length of 20 * 2 bytes.

toHexStringChecksummed(address)

function toHexStringChecksummed(address value)
    internal
    pure
    returns (string memory result)

Returns the hexadecimal representation of value.
The output is prefixed with "0x", encoded using 2 hexadecimal digits per byte,
and the alphabets are capitalized conditionally according to
https://eips.ethereum.org/EIPS/eip-55

toHexString(address)

function toHexString(address value)
    internal
    pure
    returns (string memory result)

Returns the hexadecimal representation of value.
The output is prefixed with "0x" and encoded using 2 hexadecimal digits per byte.

toHexStringNoPrefix(address)

function toHexStringNoPrefix(address value)
    internal
    pure
    returns (string memory result)

Returns the hexadecimal representation of value.
The output is encoded using 2 hexadecimal digits per byte.

toHexString(bytes)

function toHexString(bytes memory raw)
    internal
    pure
    returns (string memory result)

Returns the hex encoded string from the raw bytes.
The output is encoded using 2 hexadecimal digits per byte.

toHexStringNoPrefix(bytes)

function toHexStringNoPrefix(bytes memory raw)
    internal
    pure
    returns (string memory result)

Returns the hex encoded string from the raw bytes.
The output is encoded using 2 hexadecimal digits per byte.

Rune String Operations

runeCount(string)

function runeCount(string memory s)
    internal
    pure
    returns (uint256 result)

Returns the number of UTF characters in the string.

is7BitASCII(string)

function is7BitASCII(string memory s) internal pure returns (bool result)

Returns if this string is a 7-bit ASCII string.
(i.e. all characters codes are in [0..127])

is7BitASCII(string,uint128)

function is7BitASCII(string memory s, uint128 allowed)
    internal
    pure
    returns (bool result)

Returns if this string is a 7-bit ASCII string,
AND all characters are in the allowed lookup.
Note: If s is empty, returns true regardless of allowed.

to7BitASCIIAllowedLookup(string)

function to7BitASCIIAllowedLookup(string memory s)
    internal
    pure
    returns (uint128 result)

Converts the bytes in the 7-bit ASCII string s to
an allowed lookup for use in is7BitASCII(s, allowed).
To save runtime gas, you can cache the result in an immutable variable.

Byte String Operations

For performance and bytecode compactness, byte string operations are restricted
to 7-bit ASCII strings. All offsets are byte offsets, not UTF character offsets.
Usage of byte string operations on charsets with runes spanning two or more bytes
can lead to undefined behavior.

replace(string,string,string)

function replace(
    string memory subject,
    string memory needle,
    string memory replacement
) internal pure returns (string memory)

Returns subject all occurrences of needle replaced with replacement.

indexOf(string,string,uint256)

function indexOf(string memory subject, string memory needle, uint256 from)
    internal
    pure
    returns (uint256)

Returns the byte index of the first location of needle in subject,
needleing from left to right, starting from from.
Returns NOT_FOUND (i.e. type(uint256).max) if the needle is not found.

indexOf(string,string)

function indexOf(string memory subject, string memory needle)
    internal
    pure
    returns (uint256)

Returns the byte index of the first location of needle in subject,
needleing from left to right.
Returns NOT_FOUND (i.e. type(uint256).max) if the needle is not found.

lastIndexOf(string,string,uint256)

function lastIndexOf(
    string memory subject,
    string memory needle,
    uint256 from
) internal pure returns (uint256)

Returns the byte index of the first location of needle in subject,
needleing from right to left, starting from from.
Returns NOT_FOUND (i.e. type(uint256).max) if the needle is not found.

lastIndexOf(string,string)

function lastIndexOf(string memory subject, string memory needle)
    internal
    pure
    returns (uint256)

Returns the byte index of the first location of needle in subject,
needleing from right to left.
Returns NOT_FOUND (i.e. type(uint256).max) if the needle is not found.

contains(string,string)

function contains(string memory subject, string memory needle)
    internal
    pure
    returns (bool)

Returns true if needle is found in subject, false otherwise.

startsWith(string,string)

function startsWith(string memory subject, string memory needle)
    internal
    pure
    returns (bool)

Returns whether subject starts with needle.

endsWith(string,string)

function endsWith(string memory subject, string memory needle)
    internal
    pure
    returns (bool)

Returns whether subject ends with needle.

repeat(string,uint256)

function repeat(string memory subject, uint256 times)
    internal
    pure
    returns (string memory)

Returns subject repeated times.

slice(string,uint256,uint256)

function slice(string memory subject, uint256 start, uint256 end)
    internal
    pure
    returns (string memory)

Returns a copy of subject sliced from start to end (exclusive).
start and end are byte offsets.

slice(string,uint256)

function slice(string memory subject, uint256 start)
    internal
    pure
    returns (string memory)

Returns a copy of subject sliced from start to the end of the string.
start is a byte offset.

indicesOf(string,string)

function indicesOf(string memory subject, string memory needle)
    internal
    pure
    returns (uint256[] memory)

Returns all the indices of needle in subject.
The indices are byte offsets.

split(string,string)

function split(string memory subject, string memory delimiter)
    internal
    pure
    returns (string[] memory result)

Returns an arrays of strings based on the delimiter inside of the subject string.

concat(string,string)

function concat(string memory a, string memory b)
    internal
    pure
    returns (string memory)

Returns a concatenated string of a and b.
Cheaper than string.concat() and does not de-align the free memory pointer.

toCase(string,bool)

function toCase(string memory subject, bool toUpper)
    internal
    pure
    returns (string memory result)

Returns a copy of the string in either lowercase or UPPERCASE.
WARNING! This function is only compatible with 7-bit ASCII strings.

fromSmallString(bytes32)

function fromSmallString(bytes32 s)
    internal
    pure
    returns (string memory result)

Returns a string from a small bytes32 string.
s must be null-terminated, or behavior will be undefined.

normalizeSmallString(bytes32)

function normalizeSmallString(bytes32 s)
    internal
    pure
    returns (bytes32 result)

Returns the small string, with all bytes after the first null byte zeroized.

toSmallString(string)

function toSmallString(string memory s)
    internal
    pure
    returns (bytes32 result)

Returns the string as a normalized null-terminated small string.

lower(string)

function lower(string memory subject)
    internal
    pure
    returns (string memory result)

Returns a lowercased copy of the string.
WARNING! This function is only compatible with 7-bit ASCII strings.

upper(string)

function upper(string memory subject)
    internal
    pure
    returns (string memory result)

Returns an UPPERCASED copy of the string.
WARNING! This function is only compatible with 7-bit ASCII strings.

escapeHTML(string)

function escapeHTML(string memory s)
    internal
    pure
    returns (string memory result)

Escapes the string to be used within HTML tags.

escapeJSON(string,bool)

function escapeJSON(string memory s, bool addDoubleQuotes)
    internal
    pure
    returns (string memory result)

Escapes the string to be used within double-quotes in a JSON.
If addDoubleQuotes is true, the result will be enclosed in double-quotes.

escapeJSON(string)

function escapeJSON(string memory s)
    internal
    pure
    returns (string memory result)

Escapes the string to be used within double-quotes in a JSON.

encodeURIComponent(string)

function encodeURIComponent(string memory s)
    internal
    pure
    returns (string memory result)

Encodes s so that it can be safely used in a URI,
just like encodeURIComponent in JavaScript.
See: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/encodeURIComponent
See: https://datatracker.ietf.org/doc/html/rfc2396
See: https://datatracker.ietf.org/doc/html/rfc3986

eq(string,string)

function eq(string memory a, string memory b)
    internal
    pure
    returns (bool result)

Returns whether a equals b.

eqs(string,bytes32)

function eqs(string memory a, bytes32 b)
    internal
    pure
    returns (bool result)

Returns whether a equals b, where b is a null-terminated small string.

cmp(string,string)

function cmp(string memory a, string memory b)
    internal
    pure
    returns (int256)

Returns 0 if a == b, -1 if a < b, +1 if a > b.
If a == b[:a.length], and a.length < b.length`, returns -1.

packOne(string)

function packOne(string memory a) internal pure returns (bytes32 result)

Packs a single string with its length into a single word.
Returns bytes32(0) if the length is zero or greater than 31.

unpackOne(bytes32)

function unpackOne(bytes32 packed)
    internal
    pure
    returns (string memory result)

Unpacks a string packed using packOne.
Returns the empty string if packed is bytes32(0).
If packed is not an output of packOne, the output behavior is undefined.

packTwo(string,string)

function packTwo(string memory a, string memory b)
    internal
    pure
    returns (bytes32 result)

Packs two strings with their lengths into a single word.
Returns bytes32(0) if combined length is zero or greater than 30.

unpackTwo(bytes32)

function unpackTwo(bytes32 packed)
    internal
    pure
    returns (string memory resultA, string memory resultB)

Unpacks strings packed using packTwo.
Returns the empty strings if packed is bytes32(0).
If packed is not an output of packTwo, the output behavior is undefined.

directReturn(string)

function directReturn(string memory a) internal pure

Directly returns a without copying.