str

String utility helpers modeled after Python's str.

Quick Reference

Quick Reference: 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.

Quick Reference: 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 and string is non-empty.
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 and string is non-empty.
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.

Quick Reference: Layout:

Function	Description
join(sep, ls)	Join an iterable 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).

Quick Reference: 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 on failure (placeholder).
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.

Quick Reference: 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.

Functions

Formatting

capitalize(s)

Return copy with first character capitalized and the rest lowercased.

local s = capitalize("hello WORLD")
--result: "Hello world"

center(s, width, fillchar)

Center string within width, padded with fill characters.

local s = center("hi", 6, "-")
--result: "--hi--"

count(s, sub, start, stop)

Count non-overlapping occurrences of a substring.

local n = count("aaaa", "aa")
--result: 2

n = count("aaaa", "a", 2, -1)
--result: 2

n = count("abcd", "")
--result: 5

endswith(s, suffix, start, stop)

Return true if string ends with suffix. If suffix is a list, return true if any suffix matches.

local ok = endswith("hello.lua", ".lua")
--result: true

expandtabs(s, tabsize)

Expand tabs to spaces using given tabsize.

local s = expandtabs("a\tb", 4)
--result: "a   b"

find(s, sub, start, stop)

Return lowest index of substring or nil if not found.

local i = find("hello", "ll")
--result: 3

format_map(s, mapping)

Format string with mapping (key-based) replacement.

local s = format_map("hi {name}", { name = "bob" })
--result: "hi bob"

Predicates

isalnum(s)

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

local ok = isalnum("abc123")
--result: 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.

local ok = isalpha("abc")
--result: 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 and string is non-empty.

local ok = isascii("hello")
--result: true

NOTE

The empty string returns true.

isdecimal(s)

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

local ok = isdecimal("123")
--result: true

isdigit(s)

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

local ok = isdigit("123")
--result: true

isidentifier(s)

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

local ok = isidentifier("foo_bar")
--result: true

ok = isidentifier("2var")
--result: false

ok = isidentifier("end")
--result: false (keyword)

islower(s)

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

local ok = islower("hello")
--result: true

isnumeric(s)

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

local ok = isnumeric("123")
--result: true

isprintable(s)

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

local ok = isprintable("abc!")
--result: true

NOTE

The empty string returns true.

isspace(s)

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

local ok = isspace(" \t")
--result: true

istitle(s)

Return true if string is titlecased.

local ok = istitle("Hello World")
--result: true

isupper(s)

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

local ok = isupper("HELLO")
--result: true

Layout

join(sep, ls)

Join an iterable of strings using this string as separator.

local s = join(",", { "a", "b", "c" })
--result: "a,b,c"

ljust(s, width, fillchar)

Left-justify string in a field of given width.

local s = ljust("hi", 5, ".")
--result: "hi..."

lower(s)

Return lowercased copy.

local s = lower("HeLLo")
--result: "hello"

lstrip(s, chars)

Remove leading characters (default: whitespace).

local s = lstrip("  hello")
--result: "hello"

rstrip(s, chars)

Remove trailing characters (default: whitespace).

local s = rstrip("hello  ")
--result: "hello"

strip(s, chars)

Remove leading and trailing characters (default: whitespace).

local s = strip("  hello  ")
--result: "hello"

Split & Replace

partition(s, sep)

Partition string into head, sep, tail from left.

local a, b, c = partition("a-b-c", "-")
--result: "a", "-", "b-c"

removeprefix(s, prefix)

Remove prefix if present.

local s = removeprefix("foobar", "foo")
--result: "bar"

removesuffix(s, suffix)

Remove suffix if present.

local s = removesuffix("foobar", "bar")
--result: "foo"

replace(s, old, new, count)

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

local s = replace("a-b-c", "-", "_", 1)
--result: "a_b-c"

rfind(s, sub, start, stop)

Return highest index of substring or nil if not found.

local i = rfind("ababa", "ba")
--result: 4

rindex(s, sub, start, stop)

Like rfind but raises on failure (placeholder).

local i = rindex("ababa", "ba")
--result: 4

rjust(s, width, fillchar)

Right-justify string in a field of given width.

local s = rjust("hi", 5, ".")
--result: "...hi"

rpartition(s, sep)

Partition string into head, sep, tail from right.

local a, b, c = rpartition("a-b-c", "-")
--result: "a-b", "-", "c"

rsplit(s, sep, maxsplit)

Split from the right by separator, up to maxsplit.

local parts = rsplit("a,b,c", ",", 1)
--result: { "a,b", "c" }

split(s, sep, maxsplit)

Split by separator (or whitespace) up to maxsplit.

local parts = split("a,b,c", ",")
--result: { "a", "b", "c" }

splitlines(s, keepends)

Split on line boundaries.

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

Casing & Transform

swapcase(s)

Return a copy with case of alphabetic characters swapped.

local s = swapcase("AbC")
--result: "aBc"

startswith(s, prefix, start, stop)

Return true if string starts with prefix. If prefix is a list, return true if any prefix matches.

local ok = startswith("hello.lua", "he")
--result: true

title(s)

Return titlecased copy.

local s = title("hello world")
--result: "Hello World"

translate(s, table_map)

Translate characters using a mapping table.

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

upper(s)

Return uppercased copy.

local s = upper("Hello")
--result: "HELLO"

zfill(s, width)

Pad numeric string on the left with zeros.

local s = zfill("42", 5)
--result: "00042"