string

Creates a byte map — a lookup table from byte value to true — from a list of individual byte strings and/or byte ranges, for fast byte_map[ byte ] membership checks (e.g. in character-classification helpers like ascii_isSpace).

Each argument is either a single-character string (whose byte is added to the map) or a string.ByteMapRange table with leading_byte/trailing_byte fields giving an inclusive range of single-character strings to add, and an optional step_size (defaults to 1) to skip bytes within that range.

Pads a string with a single repeated byte until it reaches desired_length characters, on the left, the right, or both sides evenly.

Unlike string.pad, which pads with an arbitrary (possibly multi-byte) padding string, this pads with one fixed byte value, which avoids the chunk-size arithmetic string.pad needs and is a cheaper option when a single repeated byte is all that's needed.

If neither left nor right is true, or str is already at least desired_length characters long, str is returned unchanged. When padding both sides and the missing length is odd, the extra byte goes to the right side.

Returns a string that is the concatenation of repetitions copies of the byte rep_byte.

Equivalent to string.rep( string.char( rep_byte ), repetitions ). Repetition counts from 1 to 16 are special-cased as direct string_char calls, which JIT-compile to 2-4x faster code than string.rep when rep_byte is constant at the call site; any other count falls back to string.rep( string.char( rep_byte ), repetitions ).

Replaces all occurrences of the specified byte within str with replaceable, within the given range.

Implemented by splitting str around every occurrence of searchable_byte (via byte_split) and rejoining the pieces with replaceable in between — the byte-level counterpart to string.replace, which matches a substring or pattern instead of a single byte value. If searchable_byte is nil, this falls back to byte_split's default of splitting on space (0x20).

Splits a string into an array of substrings, breaking at every occurrence of the specified byte within the given range. The delimiter byte itself is not included in any of the resulting segments.

Consecutive delimiter bytes produce empty-string segments rather than being collapsed, so e.g. splitting "a,,b" on , yields { "a", "", "b" }.

Inserts a separator (e.g. a comma) every offset characters, counting from the right end of the string — the typical "thousands separator" formatting for large numbers (e.g. "1234567" → "1,234,567").

Operates purely on the string as a sequence of characters, with no awareness of numeric structure: it doesn't special-case a leading sign, a decimal point, or non-digit characters, so calling it on something that isn't a plain digit string (e.g. one that already contains a . or -) will insert separators through those characters too, based purely on position from the right.

offset is normalized to a non-negative integer (math_abs + math_floor); an offset of 0 returns str unchanged, since no grouping width is meaningful.

Checks if str contains searchable.

Wraps string.find and returns true if a match is found at or after start_position. By default the search is treated as a plain substring match; pass with_pattern = true to interpret searchable as a Lua pattern instead.

Checks whether a string contains the specified single byte value, within the given range.

The single-byte counterpart to string.containsBytes, which checks for membership in a whole byte map instead of one exact value.

Checks whether a string contains at least one byte that's a member of the given byte map, within the given range.

byte_map is a lookup table of the kind produced by string.byteMap — a table mapping byte values to true — so this is effectively "does any byte in this range belong to the given character class".

The scan stops at the first match. If the resolved start position is greater than the end position, the range is scanned backwards, so the match returned is the last one in the string rather than the first.

Returns the number of non-overlapping matches of a substring or pattern within a string.

Matching proceeds left to right, always resuming immediately after the end of the previous match — so overlapping occurrences are not counted separately (e.g. counting "aa" in "aaaa" returns 2, not 3).

If searchable is nil or an empty string, the length of str is returned instead of a match count, since an empty pattern would otherwise match at every position.

Returns the total number of occurrences of the specified byte within a string, scanning the whole [start_position, end_position] range rather than stopping at the first non-matching byte.

Unlike string.countConsecutiveByte, a non-matching byte doesn't end the count early — every matching byte in the range is counted, regardless of what's in between.

Returns 0 if str is empty or counted_byte is nil.

Returns the number of consecutive repetitions of the specified byte, starting from start_position and scanning towards end_position, stopping as soon as a byte that doesn't match counted_byte is encountered.

Note that this only counts a run starting exactly at start_position — it does not search the range for the longest run of counted_byte anywhere within it. If the byte at start_position doesn't match counted_byte, 0 is returned immediately.

Returns 0 if str is empty or counted_byte is nil.

Computes a Myers diff between two strings.

The result is a list of edit operations that transform source into target. Operations are returned in order from the start of the strings to the end, and runs of the same kind are merged; within every changed region removals come before insertions.

Common prefixes and suffixes shared by source and target are detected and emitted as 0 (equal) operations directly, without going through the general diff algorithm; the remaining differing middle section, if any, is solved using an O(ND) Myers shortest-edit-script search to find the minimal set of insertions and removals.

By default the minimal script is then cleaned up for readability: every equal run that is not longer than the changes on both of its sides is folded into them, so a heavily rewritten region becomes one removal and one insertion instead of a byte-by-byte mix of coincidental matches. Pass minimal as true to skip this and get the raw script.

Splits a string into fixed-size chunks of size bytes each, in order from the start of the string. The final chunk may be shorter than size if the string's length isn't an exact multiple of it.

size is clamped to [1, string length], so it can never be 0 or negative, and a size larger than the string just returns the whole string as a single chunk.

Escapes special characters in a string.

Within the given range, any byte that has a known escape sequence (e.g. newline, tab, quote, backslash etc.) is replaced with that sequence.

Any other byte that is a control character (below 0x20, or below 0x21 i.e. including the space character when escape_spaces is true) or is outside the printable ASCII range (0x7F and above) is replaced with a \xHH hexadecimal escape.

All other bytes, and anything outside start_position/end_position, are left untouched.

Escapes a string so it can be safely embedded in a Lua pattern and matched literally, rather than having its characters interpreted as pattern syntax.

Within the given range, every byte that has a special meaning in Lua patterns (the magic characters, listed in pattern_bytes) is prefixed with %; the null byte (0x00) is specifically escaped as %z, since patterns can't contain a literal embedded null. All other bytes, and anything outside start_position/end_position, are left untouched.

This is the pattern-syntax counterpart to string.escape, which escapes for display/ string-literal purposes rather than for safe use inside a pattern.

Finds the first match of searchable within str, removes it from the string, and returns both the remaining string and the matched text (or a capture of it, when searchable is a pattern with captures).

If searchable is a pattern (with_pattern == true) and it contains a capture, the first captured value is returned as extracted instead of the whole match; otherwise the whole matched substring is returned. If no match is found, str is returned unchanged along with default.

Finds the position of the first occurrence of the specified byte value within a string, searching the given range.

Unlike string.find, this matches a raw byte value directly rather than a substring or pattern, so it's a cheaper option when you only need to locate one specific byte.

Returns the Fowler-Noll-Vo (FNV-0) [deprecated] hash of the string.

Wiki Page

Returns the Fowler-Noll-Vo (FNV-1) hash of the string.

Wiki Page

Returns the Fowler-Noll-Vo (FNV-1a) hash of the string.

Wiki Page

Checks if the string starts with the prefix, optionally checking at a byte offset into the string rather than from the very start.

Checks if the string ends with the suffix, optionally checking with a byte offset from the end of the string rather than at the very end.

Sets a string's leading indentation to exactly size spaces, replacing any existing leading whitespace rather than adding to it.

Operates on str as a single line — any existing leading whitespace is stripped (via unIndent) and then size spaces are prepended; embedded newlines are not treated specially, so only the very start of str is affected. See string.indentLines for per-line indentation of multi-line text.

Indents every line of a string by setting each line's leading whitespace to exactly size spaces (via string.indent), splitting on \n and rejoining the result the same way.

Like string.indent, this replaces each line's existing leading whitespace rather than adding to it.

Returns the index of the first occurrence of searchable within str, searching from position onwards.

Returns 0 if searchable is nil or an empty string, and -1 if searchable is not found (including when position is already past the end of str) — so a non-negative result other than 0 always indicates an actual match position, while -1 specifically means "not found" and 0 specifically means "nothing to search for".

Inserts value into str at the given index, shifting everything from index onwards to the right.

index defaults to the end of the string (i.e. appending), and negative values count from the end of the string. An index of 0 inserts before the first character, and an index beyond the string's length is clamped to appending at the end.

When called with only two arguments (string.insert( str, value )), value is simply appended to the end of str.

Interpolates a string with the given arguments, replacing {...} placeholders with values from variables, within the given range.

The arguments are replaced in the string using the following format:

{1}, {2}, {3}, {4}, {5}, {6}, {7}, {8}, {9}

It's also supports named arguments:

{key}, {my_val}, {something} and etc.

In both cases the text between the braces is used as a literal string key into variables (so {1} looks up variables["1"], not variables[1]) — keep that in mind when passing a positional/array-style table, since Lua treats numeric and string keys as distinct.

A backslash (\) escapes the character immediately following it, both inside and outside of {...}, so e.g. \{ or \} can be used to include a literal brace without it being treated as a placeholder delimiter.

A placeholder is only replaced if its key exists in variables with a non-nil value; otherwise the placeholder (including its braces) is left in the output unchanged. The same applies to an empty placeholder ({}) and to an unterminated { with no matching } before end_position — both are left as literal text rather than erroring.

Replaces occurrences of a specific byte in the string with values from variables, in the order they're found — the first occurrence of interpolate_byte is replaced with variables[1], the second with variables[2], and so on.

Unlike string.interpolate, which matches named/numbered {...} placeholders, this matches a single repeated placeholder byte (similar to %s-style sequential substitution, but using one literal byte as the marker instead of a format specifier). It also has no escape syntax — every occurrence of interpolate_byte within the range is treated as a placeholder, with no way to include a literal copy of that byte.

Substitution stops once every entry in variables (up to variable_count) has been used; any further occurrences of interpolate_byte beyond that point are left untouched in the output. If variable_count is 0 (or variables is empty), the string is returned unchanged without scanning it at all.

Checks whether a string starts with a LuaJIT bytecode header for the given JIT version.

Verifies that the first three bytes at start_position match the LuaJIT bytecode magic signature \x1BLJ (ESC, L, J), and that the fourth byte equals jit_version — this is the same version byte exposed as jit.version_byte (e.g. 0x01 for LuaJIT 2.0, 0x02 for LuaJIT 2.1), which lets a loader reject bytecode compiled for a different LuaJIT version before attempting to load it.

This only checks the header; it doesn't validate the rest of the chunk as well-formed bytecode.

Checks whether a string is empty, i.e. has no bytes at all.

Checks whether a string (or a sub-range of it) can be parsed as a valid number, using the same base auto-detection and sub-range rules as toNumber/string.toNumber.

Equivalent to string.toNumber( str, base, start_position, end_position ) ~= nil, but without needing to hold on to the converted value when only the validity check matters.

Checks whether a string looks like a well-formed URL, matched against a strict pattern rather than resolved or validated against any real scheme or host.

Specifically requires: a scheme starting with a lowercase letter and continuing with lowercase letters, +, -, or . (e.g. http, git+ssh), followed by a :, followed by the rest of the URL — which may be empty, but must not contain whitespace or control characters (bytes 0x00–0x20), bytes above 0x7E (0x7F–0xFF), or the characters ", <, >, ^, ` `, {, |, or }`.

This is a syntactic sanity check, not a full RFC 3986 validator — it doesn't verify that the scheme is a known/registered one, or inspect the structure of the authority, path, query, or fragment beyond the character restrictions above.

Packs a sequence of bytes into a string, the inverse of string.unpack.

Equivalent to string.char( table.unpack( bytes, 1, byte_count ) ), but built with string_char calls batched 32 bytes at a time for performance rather than unpacking the whole array (and hitting Lua's C-stack argument limit) in one call.

Pads a string with a repeated padding string until it reaches desired_length characters, on the left, the right, or both sides evenly.

If neither left nor right is true, or the string is already at least desired_length characters long, str is returned unchanged.

When padding both sides, the missing length is split as evenly as possible between the left and right; if it doesn't divide evenly by whole copies of padding, the shortfall is made up with a partial copy of padding, with any extra leftover character going to the right side.

This is the byte-length counterpart to unicode.pad, which measures and pads by display width (columns) instead of raw byte length.

Removes every occurrence of the specified byte from a string, within the given range.

Implemented by splitting str around every occurrence of byte (via byte_split) and rejoining the pieces with nothing in between — equivalent to string.byteReplace( str, byte, "", start_position, end_position ), but without the overhead of an optional replacement argument.

Wraps a string in quotes, escaping any quote characters of the same kind already inside it so the result is a syntactically valid quoted literal.

Only the quote character itself is escaped — other characters that would normally need escaping in a string literal (backslashes, newlines, etc.) are left untouched, so this is not a full string-literal encoder, just a quote-wrapping helper.

Inverse of string.unQuote.

Generates a random string by repeatedly picking a random character pool and then a random character from it.

Can be used to generate a password/key/secret.

lowercase and numbers are included by default; uppercase, symbols, and extended_ascii are opt-in. At each position, one of the enabled pools is chosen at random with equal probability per pool, not per character — so if one pool is much larger than another (e.g. extended_ascii vs numbers), characters from the smaller pool still appear just as often on average, rather than being proportionally under-represented.

The length of the string is 8 by default. Passing 0 returns an empty string without requiring any pool to be enabled.

Removes the inclusive byte range [start_position, end_position] from a string, returning what remains with the gap closed up.

If the range covers the entire string, an empty string is returned.

Replaces all occurrences of searchable within str with replaceable.

Implemented by splitting str around every match of searchable (within the given range) and rejoining the pieces with replaceable in between — so this behaves the same as split( str, searchable, with_pattern, start_position, end_position ) followed by table.concat( segments, replaceable ). If searchable doesn't occur in str (or in the given range), the string is returned unchanged.

Splits a string into an array of substrings around every occurrence of searchable within the given range. The matched delimiter itself is not included in any segment.

If searchable is nil or an empty string, the string is instead split into one segment per byte (effectively str_length single-character segments), ignoring with_pattern, start_position, and end_position entirely.

Consecutive delimiters, or a delimiter at the very start or end of the searched range, produce empty-string segments rather than being collapsed or skipped — the segment count is always exactly one more than the number of delimiter matches found. If searchable never occurs within the range, the whole range is returned as a single segment.

string.replace is built directly on top of this function, rejoining the returned segments with a replacement string in place of replaceable.

Converts a string, or a sub-range of it, to a number, with automatic base detection when base is omitted.

If base is nil, the start of the (sub)string is inspected to guess the base: a 0x/ 0X prefix selects base 16, a leading 0 followed by another digit selects base 8, and anything else defaults to base 10. A bare "0x"/"0X" prefix with nothing after it is treated as a literal 0 rather than being passed through to the underlying conversion.

If neither start_position nor end_position is given, the whole string is converted directly; otherwise the selected sub-range is extracted first (via string.sub semantics) and that substring is converted instead.

Removes leading and/or trailing matches of a character set from a string.

pattern_str is treated as a set of characters to trim, not a general Lua pattern: a single character is escaped via pattern_bytes (if needed) and matched literally; a multi-character string that isn't already a %-class (like %s) is wrapped as a character class ([...]), so e.g. "-_" trims any run of - and _ characters, not the literal substring "-_". Defaults to %s (whitespace) when omitted.

left and right both default to true; passing false for either one disables trimming on that side while leaving the other side's default behavior unchanged, so only an explicit false turns a side off.

Removes leading and/or trailing occurrences of a single specific byte from a string, within the given range.

Unlike string.trim, this matches one exact byte value rather than a Lua pattern or character class — it's a cheaper, byte-level equivalent for the common case of trimming a single fixed character (e.g. spaces, null bytes, a delimiter).

left and right both default to true; passing false for either one disables trimming on that side while leaving the other side's default behavior unchanged.

If the entire range consists of trailing_byte, the result is an empty string.

Removes leading and/or trailing whitespace characters from a string, within the given range, and returns the trimmed string along with its length.

A byte counts as whitespace according to ascii_isSpace (space, tab, newline, and other ASCII whitespace bytes), not just the literal space character — unlike string.trimByte, which only matches one specific byte value.

left and right both default to true; passing false for either one disables trimming on that side while leaving the other side's default behavior unchanged.

If the entire range consists of whitespace, the result is an empty string.

Unescapes special characters in a string.

The inverse of string.escape.

Within the given range, recognized escape sequences (e.g. \n, \t, \", \\ etc.) are converted back into their raw byte, and \xHH hexadecimal escapes are decoded into the byte they represent.

Any other byte, and anything outside start_position/end_position, is left untouched.

Removes leading whitespace from the start of a single-line string (does not affect subsequent lines if str contains embedded newlines — see string.unindentLines for that).

If size is given, at most size leading whitespace bytes are removed; otherwise all leading whitespace is removed, equivalent to string.trimSpaces( str, true, false ).

Removes leading whitespace from every line of a string (via string.unIndent), splitting on \n and rejoining the result the same way. The multi-line counterpart to string.unIndent, which only strips the first line.

Unpacks a string into a sequence of bytes, the inverse of string.pack.

Equivalent to { string.byte( str, start_position, end_position ) } over the given range, but built with string_byte calls batched 32 bytes at a time for performance.

Removes a surrounding pair of quotes from a string and unescapes any escaped quote characters of the same kind inside it. Inverse of string.quote.

If str isn't wrapped in the expected quote character at both ends, it's returned unchanged (aside from unescaping) rather than erroring — so this is safe to call on a string that may or may not actually be quoted.