Skip to content

str.md

Latest commit

 

History

History
1032 lines (626 loc) · 22.1 KB

str.md

File metadata and controls

1032 lines (626 loc) · 22.1 KB
description String utility helpers modeled after Python's `str`.

str

String utility helpers modeled after Python's str.

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:

  • s (string): Computed string value.

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:

  • s (string): Computed string value.

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:

  • n (integer): Computed numeric value.

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:

  • ok (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:

  • s (string): Computed string value.

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:

  • s (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:

  • ok (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:

  • ok (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:

  • ok (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:

  • ok (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:

  • ok (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:

  • ok (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:

  • ok (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:

  • ok (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:

  • ok (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:

  • ok (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:

  • ok (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:

  • ok (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:

  • s (string): Computed string value.

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:

  • s (string): Computed string value.

Example:

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

lower(s)

Return lowercased copy.

Parameters:

  • s (string): Input string.

Return:

  • s (string): Computed string value.

Example:

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

lstrip(s, chars?)

Remove leading characters (default: whitespace).

Parameters:

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

Return:

  • s (string): Computed string value.

Example:

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

rstrip(s, chars?)

Remove trailing characters (default: whitespace).

Parameters:

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

Return:

  • s (string): Computed string value.

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:

  • s (string): Computed string value.

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.
  • sep_found (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:

  • s (string): Computed string value.

Example:

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

removesuffix(s, suffix)

Remove suffix if present.

Parameters:

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

Return:

  • s (string): Computed string value.

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:

  • s (string): Computed string value.

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): Computed numeric value.

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:

  • s (string): Computed string value.

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.
  • sep_found (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:

  • s (string): Computed string value.

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:

  • ok (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:

  • s (string): Computed string value.

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:

  • s (string): Computed string value.

Example:

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

upper(s)

Return uppercased copy.

Parameters:

  • s (string): Input string.

Return:

  • s (string): Computed string value.

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:

  • s (string): Computed string value.

Example:

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