str

String operations for searching, splitting, trimming, and formatting text.

Usage

str = require "mods.str"

print(str.capitalize("hello world")) --> "Hello world"

Functions

Formatting:

Function	Description
capitalize(s)	Return copy with first character capitalized and the rest lowercased.
center(s, width, fillchar?)	Center string within width, padded with fill characters.
count(s, sub, start?, stop?)	Count non-overlapping occurrences of a substring.
endswith(s, suffix, start?, stop?)	Return true if string ends with suffix.
expandtabs(s, tabsize?)	Expand tabs to spaces using given tabsize.
find(s, sub, start?, stop?)	Return lowest index of substring or nil if not found.
format_map(s, mapping)	Format string with mapping (key-based) replacement.

Predicates:

Function	Description
isalnum(s)	Return true if all characters are alphanumeric and string is non-empty.
isalpha(s)	Return true if all characters are alphabetic and string is non-empty.
isascii(s)	Return true if all characters are ASCII.
isdecimal(s)	Return true if all characters are decimal characters and string is non-empty.
isdigit(s)	Return true if all characters are digits and string is non-empty.
isidentifier(s)	Return true if string is a valid identifier and not a reserved keyword.
islower(s)	Return true if all cased characters are lowercase and there is at least one cased character.
isnumeric(s)	Return true if all characters are numeric and string is non-empty.
isprintable(s)	Return true if all characters are printable.
isspace(s)	Return true if all characters are whitespace and string is non-empty.
istitle(s)	Return true if string is titlecased.
isupper(s)	Return true if all cased characters are uppercase and there is at least one cased character.

Layout:

Function	Description
join(sep, ls)	Join an array-like table of strings using this string as separator.
ljust(s, width, fillchar?)	Left-justify string in a field of given width.
lower(s)	Return lowercased copy.
lstrip(s, chars?)	Remove leading characters (default: whitespace).
rstrip(s, chars?)	Remove trailing characters (default: whitespace).
strip(s, chars?)	Remove leading and trailing characters (default: whitespace).

Split & Replace:

Function	Description
partition(s, sep)	Partition string into head, sep, tail from left.
removeprefix(s, prefix)	Remove prefix if present.
removesuffix(s, suffix)	Remove suffix if present.
replace(s, old, new, count?)	Return a copy of the string with all occurrences of a substring replaced.
rfind(s, sub, start?, stop?)	Return highest index of substring or nil if not found.
rindex(s, sub, start?, stop?)	Like rfind but raises an error when the substring is not found.
rjust(s, width, fillchar?)	Right-justify string in a field of given width.
rpartition(s, sep)	Partition string into head, sep, tail from right.
rsplit(s, sep?, maxsplit?)	Split from the right by separator, up to maxsplit.
split(s, sep?, maxsplit?)	Split by separator (or whitespace) up to maxsplit.
splitlines(s, keepends?)	Split on line boundaries.

Casing & Transform:

Function	Description
swapcase(s)	Return a copy with case of alphabetic characters swapped.
startswith(s, prefix, start?, stop?)	Return true if string starts with prefix.
title(s)	Return titlecased copy.
translate(s, table_map)	Translate characters using a mapping table.
upper(s)	Return uppercased copy.
zfill(s, width)	Pad numeric string on the left with zeros.

Formatting

capitalize(s)

Return copy with first character capitalized and the rest lowercased.

Parameters:

• s (string): Input string.

Return:

• capitalized (string): Capitalized string.

Example:

s = capitalize("hello WORLD") --> "Hello world"

center(s, width, fillchar?)

Center string within width, padded with fill characters.

Parameters:

• s (string): Input string.
• width (integer): Target width.
• fillchar? (string): Optional fill character.

Return:

• centered (string): Centered string.

Example:

s = center("hi", 6, "-") --> "--hi--"

count(s, sub, start?, stop?)

Count non-overlapping occurrences of a substring.

Parameters:

• s (string): Input string.
• sub (string): Substring to search.
• start? (integer): Optional start index (defaults to 1).
• stop? (integer): Optional exclusive end index (defaults to #s + 1).

Return:

• count (integer): Number of non-overlapping matches.

Example:

n = count("aaaa", "aa")       --> 2
n = count("aaaa", "a", 2, -1) --> 2
n = count("abcd", "")         --> 5

endswith(s, suffix, start?, stop?)

Return true if string ends with suffix.

Parameters:

• s (string): Input string.
• suffix (string|string[]): Suffix string.
• start? (integer): Optional start index (defaults to 1).
• stop? (integer): Optional exclusive end index (defaults to #s + 1).

Return:

• hasSuffix (boolean): True when s ends with suffix.

Example:

ok = endswith("hello.lua", ".lua") --> true

NOTE

If suffix is a list, returns true when any suffix matches.

expandtabs(s, tabsize?)

Expand tabs to spaces using given tabsize.

Parameters:

• s (string): Input string.
• tabsize? (integer): Optional tab width (defaults to 8).

Return:

• expanded (string): String with tabs expanded.

Example:

s = expandtabs("a\tb", 4) --> "a   b"

find(s, sub, start?, stop?)

Return lowest index of substring or nil if not found.

Parameters:

• s (string): Input string.
• sub (string): Substring to search.
• start? (integer): Optional start index (defaults to 1).
• stop? (integer): Optional exclusive end index (defaults to #s + 1).

Return:

• index (integer?): First match index, or nil when not found.

Example:

i = find("hello", "ll") --> 3

format_map(s, mapping)

Format string with mapping (key-based) replacement.

Parameters:

• s (string): Template string with {key} placeholders.
• mapping (table): Values used to replace placeholder keys.

Return:

• formatted (string): Formatted string with placeholders replaced.

Example:

s = format_map("hi {name}", { name = "bob" }) --> "hi bob"

NOTE

format_map is a lightweight {key} replacement helper. For richer templating, use mods.template.

Predicates

isalnum(s)

Return true if all characters are alphanumeric and string is non-empty.

Parameters:

• s (string): Input string.

Return:

• isAlnum (boolean): True when s is non-empty and all characters are alphanumeric.

Example:

ok = isalnum("abc123") --> true

NOTE

Lua letters are ASCII by default, so non-ASCII letters are not alphanumeric.

isalnum("á1") --> false

isalpha(s)

Return true if all characters are alphabetic and string is non-empty.

Parameters:

• s (string): Input string.

Return:

• isAlpha (boolean): True when s is non-empty and all characters are alphabetic.

Example:

ok = isalpha("abc") --> true

NOTE

Lua letters are ASCII by default, so non-ASCII letters are not alphabetic.

isalpha("á") --> false

isascii(s)

Return true if all characters are ASCII.

Parameters:

• s (string): Input string.

Return:

• isAscii (boolean): True when all bytes in s are ASCII.

Example:

ok = isascii("hello") --> true

NOTE

The empty string returns true.

isdecimal(s)

Return true if all characters are decimal characters and string is non-empty.

Parameters:

• s (string): Input string.

Return:

• isDecimal (boolean): True when s is non-empty and all characters are decimal digits.

Example:

ok = isdecimal("123") --> true

isdigit(s)

Return true if all characters are digits and string is non-empty.

Parameters:

• s (string): Input string.

Return:

• isDigit (boolean): True when s is non-empty and all characters are digits.

Example:

ok = isdigit("123") --> true

isidentifier(s)

Return true if string is a valid identifier and not a reserved keyword.

Parameters:

• s (string): Input string.

Return:

• isIdentifier (boolean): True when s is a valid identifier and not a keyword.

Example:

ok = isidentifier("foo_bar") --> true
ok = isidentifier("2var") --> false
ok = isidentifier("end") --> false (keyword)

islower(s)

Return true if all cased characters are lowercase and there is at least one cased character.

Parameters:

• s (string): Input string.

Return:

• isLower (boolean): True when s has at least one cased character and all are lowercase.

Example:

ok = islower("hello") --> true

isnumeric(s)

Return true if all characters are numeric and string is non-empty.

Parameters:

• s (string): Input string.

Return:

• isNumeric (boolean): True when s is non-empty and all characters are numeric.

Example:

ok = isnumeric("123") --> true

isprintable(s)

Return true if all characters are printable.

Parameters:

• s (string): Input string.

Return:

• isPrintable (boolean): True when all bytes in s are printable ASCII.

Example:

ok = isprintable("abc!") --> true

NOTE

The empty string returns true.

isspace(s)

Return true if all characters are whitespace and string is non-empty.

Parameters:

• s (string): Input string.

Return:

• isSpace (boolean): True when s is non-empty and all characters are whitespace.

Example:

ok = isspace(" \t") --> true

istitle(s)

Return true if string is titlecased.

Parameters:

• s (string): Input string.

Return:

• isTitle (boolean): True when s is titlecased.

Example:

ok = istitle("Hello World") --> true

isupper(s)

Return true if all cased characters are uppercase and there is at least one cased character.

Parameters:

• s (string): Input string.

Return:

• isUpper (boolean): True when s has at least one cased character and all are uppercase.

Example:

ok = isupper("HELLO") --> true

Layout

join(sep, ls)

Join an array-like table of strings using this string as separator.

Parameters:

• sep (string): Separator value.
• ls (string[]): Table value.

Return:

• joined (string): Joined string.

Example:

s = join(",", { "a", "b", "c" }) --> "a,b,c"

ljust(s, width, fillchar?)

Left-justify string in a field of given width.

Parameters:

• s (string): Input string.
• width (integer): Target width.
• fillchar? (string): Optional fill character.

Return:

• leftJustified (string): Left-justified string.

Example:

s = ljust("hi", 5, ".") --> "hi..."

lower(s)

Return lowercased copy.

Parameters:

• s (string): Input string.

Return:

• lowercased (string): Lowercased string.

Example:

s = lower("HeLLo") --> "hello"

lstrip(s, chars?)

Remove leading characters (default: whitespace).

Parameters:

• s (string): Input string.
• chars? (string): Optional character set.

Return:

• leadingStripped (string): String with leading characters removed.

Example:

s = lstrip("  hello") --> "hello"

rstrip(s, chars?)

Remove trailing characters (default: whitespace).

Parameters:

• s (string): Input string.
• chars? (string): Optional character set.

Return:

• trailingStripped (string): String with trailing characters removed.

Example:

s = rstrip("hello  ") --> "hello"

strip(s, chars?)

Remove leading and trailing characters (default: whitespace).

Parameters:

• s (string): Input string.
• chars? (string): Optional character set.

Return:

• stripped (string): String with leading and trailing characters removed.

Example:

s = strip("  hello  ") --> "hello"

Split & Replace

partition(s, sep)

Partition string into head, sep, tail from left.

Parameters:

• s (string): Input string.
• sep (string): Separator value.

Return:

• head (string): Part before the separator.
• separator (string): Matched separator, or empty string when not found.
• tail (string): Part after the separator.

Example:

a, b, c = partition("a-b-c", "-") --> "a", "-", "b-c"

removeprefix(s, prefix)

Remove prefix if present.

Parameters:

• s (string): Input string.
• prefix (string): Prefix string.

Return:

• prefixRemoved (string): String with prefix removed when present.

Example:

s = removeprefix("foobar", "foo") --> "bar"

removesuffix(s, suffix)

Remove suffix if present.

Parameters:

• s (string): Input string.
• suffix (string): Suffix string.

Return:

• suffixRemoved (string): String with suffix removed when present.

Example:

s = removesuffix("foobar", "bar") --> "foo"

replace(s, old, new, count?)

Return a copy of the string with all occurrences of a substring replaced.

Parameters:

• s (string): Input string.
• old (string): Substring to replace.
• new (string): Replacement string.
• count? (integer): Optional maximum replacement count.

Return:

• replaced (string): String with replacements applied.

Example:

s = replace("a-b-c", "-", "_", 1) --> "a_b-c"

rfind(s, sub, start?, stop?)

Return highest index of substring or nil if not found.

Parameters:

• s (string): Input string.
• sub (string): Substring to search.
• start? (integer): Optional start index (defaults to 1).
• stop? (integer): Optional inclusive end index (defaults to #s).

Return:

• index (integer?): Last match index, or nil when not found.

Example:

i = rfind("ababa", "ba") --> 4

rindex(s, sub, start?, stop?)

Like rfind but raises an error when the substring is not found.

Parameters:

• s (string): Input string.
• sub (string): Substring to search.
• start? (integer): Optional start index (defaults to 1).
• stop? (integer): Optional inclusive end index (defaults to #s).

Return:

• index (integer): Last match index.

Example:

i = rindex("ababa", "ba") --> 4

rjust(s, width, fillchar?)

Right-justify string in a field of given width.

Parameters:

• s (string): Input string.
• width (integer): Target width.
• fillchar? (string): Optional fill character.

Return:

• rightJustified (string): Right-justified string.

Example:

s = rjust("hi", 5, ".") --> "...hi"

rpartition(s, sep)

Partition string into head, sep, tail from right.

Parameters:

• s (string): Input string.
• sep (string): Separator value.

Return:

• head (string): Part before the separator.
• separator (string): Matched separator, or empty string when not found.
• tail (string): Part after the separator.

Example:

a, b, c = rpartition("a-b-c", "-") --> "a-b", "-", "c"

rsplit(s, sep?, maxsplit?)

Split from the right by separator, up to maxsplit.

Parameters:

• s (string): Input string.
• sep? (string): Optional separator value.
• maxsplit? (integer): Optional maximum number of splits.

Return:

• parts (mods.List): Split parts.

Example:

parts = rsplit("a,b,c", ",", 1) --> { "a,b", "c" }

split(s, sep?, maxsplit?)

Split by separator (or whitespace) up to maxsplit.

Parameters:

• s (string): Input string.
• sep? (string): Optional separator value.
• maxsplit? (integer): Optional maximum number of splits.

Return:

• parts (mods.List): Split parts.

Example:

parts = split("a,b,c", ",") --> { "a", "b", "c" }

splitlines(s, keepends?)

Split on line boundaries.

Parameters:

• s (string): Input string.
• keepends? (boolean): Optional whether to keep line endings.

Return:

• lines (mods.List): Split lines.

Example:

lines = splitlines("a\nb\r\nc") --> { "a", "b", "c" }

Casing & Transform

swapcase(s)

Return a copy with case of alphabetic characters swapped.

Parameters:

• s (string): Input string.

Return:

• swappedCase (string): String with alphabetic case swapped.

Example:

s = swapcase("AbC") --> "aBc"

startswith(s, prefix, start?, stop?)

Return true if string starts with prefix.

Parameters:

• s (string): Input string.
• prefix (string|string[]): Prefix string.
• start? (integer): Optional start index (defaults to 1).
• stop? (integer): Optional exclusive end index (defaults to #s + 1).

Return:

• hasPrefix (boolean): True when s starts with prefix.

Example:

ok = startswith("hello.lua", "he") --> true

NOTE

If prefix is a list, returns true when any prefix matches.

title(s)

Return titlecased copy.

Parameters:

• s (string): Input string.

Return:

• titlecased (string): Titlecased string.

Example:

s = title("hello world") --> "Hello World"

translate(s, table_map)

Translate characters using a mapping table.

Parameters:

• s (string): Input string.
• table_map (table): Character translation map.

Return:

• translated (string): Translated string.

Example:

map = { [string.byte("a")] = "b", ["c"] = false }
s = translate("abc", map) --> "bb"

upper(s)

Return uppercased copy.

Parameters:

• s (string): Input string.

Return:

• uppercased (string): Uppercased string.

Example:

s = upper("Hello") --> "HELLO"

zfill(s, width)

Pad numeric string on the left with zeros.

Parameters:

• s (string): Input string.
• width (integer): Target width.

Return:

• zeroFilled (string): Zero-padded string.

Example:

s = zfill("42", 5) --> "00042"