String

Utilities for string manipulation, searching, and formatting.

Trimming and Padding

str.trim

Signature: str.trim(s)

Description: Removes leading and trailing whitespace from a string.

Parameters:

• s (string): The string to trim.

Returns:

• string: The trimmed string.

Example:

local text = "  Hello, world!  "
local trimmed = str.trim(text)
engine.log("Original: '" .. text .. "'", 255, 255, 255, 255)
engine.log("Trimmed: '" .. trimmed .. "'", 255, 255, 255, 255)
-- Output: "Hello, world!"

---

str.ltrim

Signature: str.ltrim(s)

Description: Removes leading whitespace from a string.

Parameters:

• s (string): The string to trim.

Returns:

• string: The left-trimmed string.

Example:

local text = "  Hello, world!  "
local ltrimmed = str.ltrim(text)
engine.log("Original: '" .. text .. "'", 255, 255, 255, 255)
engine.log("Left trimmed: '" .. ltrimmed .. "'", 255, 255, 255, 255)
-- Output: "Hello, world!  "

---

str.rtrim

Signature: str.rtrim(s)

Description: Removes trailing whitespace from a string.

Parameters:

• s (string): The string to trim.

Returns:

• string: The right-trimmed string.

Example:

local text = "  Hello, world!  "
local rtrimmed = str.rtrim(text)
engine.log("Original: '" .. text .. "'", 255, 255, 255, 255)
engine.log("Right trimmed: '" .. rtrimmed .. "'", 255, 255, 255, 255)
-- Output: "  Hello, world!"

---

str.pad_left

Signature: str.pad_left(s, len, char)

Description: Pads the string from the left with a specified character to reach the desired length.

Parameters:

• s (string): The string to pad.

• len (number): The desired length.

• char (string, optional): The character to use for padding. Defaults to space.

Returns:

• string: The padded string.

Example:

local number = "42"
local padded = str.pad_left(number, 5, "0")
engine.log("Original: '" .. number .. "'", 255, 255, 255, 255)
engine.log("Padded: '" .. padded .. "'", 255, 255, 255, 255)
-- Output: "00042"

---

str.pad_right

Signature: str.pad_right(s, len, char)

Description: Pads the string from the right with a specified character to reach the desired length.

Parameters:

• s (string): The string to pad.

• len (number): The desired length.

• char (string, optional): The character to use for padding. Defaults to space.

Returns:

• string: The padded string.

Example:

local text = "Hello"
local padded = str.pad_right(text, 10, "-")
engine.log("Original: '" .. text .. "'", 255, 255, 255, 255)
engine.log("Padded: '" .. padded .. "'", 255, 255, 255, 255)
-- Output: "Hello-----"

---

str.strip_prefix

Signature: str.strip_prefix(s, prefix)

Description: Removes the specified prefix from the beginning of the string if present.

Parameters:

• s (string): The string to process.

• prefix (string): The prefix to remove.

Returns:

• string: The string with the prefix removed if it was present.

Example:

local filename = "prefix_document.txt"
local stripped = str.strip_prefix(filename, "prefix_")
engine.log("Original: '" .. filename .. "'", 255, 255, 255, 255)
engine.log("Stripped: '" .. stripped .. "'", 255, 255, 255, 255)
-- Output: "document.txt"

---

str.strip_suffix

Signature: str.strip_suffix(s, suffix)

Description: Removes the specified suffix from the end of the string if present.

Parameters:

• s (string): The string to process.

• suffix (string): The suffix to remove.

Returns:

• string: The string with the suffix removed if it was present.

Example:

local filename = "document.txt"
local stripped = str.strip_suffix(filename, ".txt")
engine.log("Original: '" .. filename .. "'", 255, 255, 255, 255)
engine.log("Stripped: '" .. stripped .. "'", 255, 255, 255, 255)
-- Output: "document"

---

Search and Matching

str.startswith

Signature: str.startswith(s, prefix)

Description: Returns true if the string starts with the specified prefix.

Parameters:

• s (string): The string to check.

• prefix (string): The prefix to look for.

Returns:

• boolean: true if the string starts with the prefix, false otherwise.

Example:

local text = "Hello, world!"
local result = str.startswith(text, "Hello")
engine.log("Text: '" .. text .. "'", 255, 255, 255, 255)
engine.log("Starts with 'Hello': " .. tostring(result), 255, 255, 255, 255)
-- Output: true

---

str.endswith

Signature: str.endswith(s, suffix)

Description: Returns true if the string ends with the specified suffix.

Parameters:

• s (string): The string to check.

• suffix (string): The suffix to look for.

Returns:

• boolean: true if the string ends with the suffix, false otherwise.

Example:

local text = "Hello, world!"
local result = str.endswith(text, "world!")
engine.log("Text: '" .. text .. "'", 255, 255, 255, 255)
engine.log("Ends with 'world!': " .. tostring(result), 255, 255, 255, 255)
-- Output: true

---

str.contains

Signature: str.contains(s, substring)

Description: Returns true if the string contains the specified substring.

Parameters:

• s (string): The string to check.

• substring (string): The substring to look for.

Returns:

• boolean: true if the string contains the substring, false otherwise.

Example:

local text = "Hello, world!"
local result = str.contains(text, "world")
engine.log("Text: '" .. text .. "'", 255, 255, 255, 255)
engine.log("Contains 'world': " .. tostring(result), 255, 255, 255, 255)
-- Output: true

---

str.indexof

Signature: str.indexof(s, substr, start)

Description: Returns the first index of the substring in the string, or nil if not found.

Parameters:

• s (string): The string to search in.

• substr (string): The substring to find.

• start (number, optional): The starting position for the search. Defaults to 1.

Returns:

• number: The 1-based index of the first occurrence of the substring, or nil if not found.

Example:

local text = "Hello, world! Hello again!"
local index = str.indexof(text, "Hello")
local index2 = str.indexof(text, "Hello", 2)
engine.log("Text: '" .. text .. "'", 255, 255, 255, 255)
engine.log("First 'Hello' at index: " .. tostring(index), 255, 255, 255, 255) -- Output: 1
engine.log("Second 'Hello' at index: " .. tostring(index2), 255, 255, 255, 255) -- Output: 15

---

str.last_indexof

Signature: str.last_indexof(s, substr)

Description: Returns the last index of the substring in the string, or nil if not found.

Parameters:

• s (string): The string to search in.

• substr (string): The substring to find.

Returns:

• number: The 1-based index of the last occurrence of the substring, or nil if not found.

Example:

local text = "Hello, world! Hello again!"
local index = str.last_indexof(text, "Hello")
engine.log("Text: '" .. text .. "'", 255, 255, 255, 255)
engine.log("Last 'Hello' at index: " .. tostring(index), 255, 255, 255, 255)
-- Output: 15

---

str.count

Signature: str.count(s, substr)

Description: Counts occurrences of a substring within a string.

Parameters:

• s (string): The string to search in.

• substr (string): The substring to count.

Returns:

• number: The number of occurrences of the substring.

Example:

local text = "one, two, three, four, one, two"
local count = str.count(text, "one")
engine.log("Text: '" .. text .. "'", 255, 255, 255, 255)
engine.log("Count of 'one': " .. count, 255, 255, 255, 255)
-- Output: 2

---

str.empty

Signature: str.empty(s)

Description: Returns true if the string is empty.

Parameters:

• s (string): The string to check.

Returns:

• boolean: true if the string is empty, false otherwise.

Example:

local text1 = ""
local text2 = "Hello"
engine.log("Is text1 empty: " .. tostring(str.empty(text1)), 255, 255, 255, 255) -- Output: true
engine.log("Is text2 empty: " .. tostring(str.empty(text2)), 255, 255, 255, 255) -- Output: false

---

str.equals

Signature: str.equals(a, b)

Description: Compares two strings for equality.

Parameters:

• a (string): The first string.

• b (string): The second string.

Returns:

• boolean: true if the strings are equal, false otherwise.

Example:

local str1 = "Hello"
local str2 = "Hello"
local str3 = "hello"
engine.log("str1 equals str2: " .. tostring(str.equals(str1, str2)), 255, 255, 255, 255) -- Output: true
engine.log("str1 equals str3: " .. tostring(str.equals(str1, str3)), 255, 255, 255, 255) -- Output: false

---

Modification and Replacement

str.replace

Signature: str.replace(s, from, to)

Description: Replaces all occurrences of a substring with another string.

Parameters:

• s (string): The string to modify.

• from (string): The substring to replace.

• to (string): The replacement string.

Returns:

• string: The modified string.

Example:

local text = "Hello, world! Hello, universe!"
local modified = str.replace(text, "Hello", "Hi")
engine.log("Original: '" .. text .. "'", 255, 255, 255, 255)
engine.log("Modified: '" .. modified .. "'", 255, 255, 255, 255)
-- Output: "Hi, world! Hi, universe!"

---

str.repeat_str

Signature: str.repeat_str(s, count)

Description: Repeats a string a specified number of times.

Parameters:

• s (string): The string to repeat.

• count (number): The number of times to repeat.

Returns:

• string: The repeated string.

Example:

local text = "Hello "
local repeated = str.repeat_str(text, 3)
engine.log("Original: '" .. text .. "'", 255, 255, 255, 255)
engine.log("Repeated: '" .. repeated .. "'", 255, 255, 255, 255)
-- Output: "Hello Hello Hello "

---

str.reverse

Signature: str.reverse(s)

Description: Reverses a string.

Parameters:

• s (string): The string to reverse.

Returns:

• string: The reversed string.

Example:

local text = "Hello"
local reversed = str.reverse(text)
engine.log("Original: '" .. text .. "'", 255, 255, 255, 255)
engine.log("Reversed: '" .. reversed .. "'", 255, 255, 255, 255)
-- Output: "olleH"

---

str.insert

Signature: str.insert(s, pos, substr)

Description: Inserts a substring at a specified position in the string.

Parameters:

• s (string): The original string.

• pos (number): The position to insert at (1-based index).

• substr (string): The substring to insert.

Returns:

• string: The resulting string.

Example:

local text = "Hello world!"
local modified = str.insert(text, 7, "beautiful ")
engine.log("Original: '" .. text .. "'", 255, 255, 255, 255)
engine.log("Modified: '" .. modified .. "'", 255, 255, 255, 255)
-- Output: "Hello beautiful world!"

---

str.remove

Signature: str.remove(s, start, end)

Description: Removes characters from a string between start and end positions.

Parameters:

• s (string): The original string.

• start (number): The starting position (1-based index).

• end (number): The ending position (1-based index).

Returns:

• string: The resulting string.

Example:

local text = "Hello, beautiful world!"
local modified = str.remove(text, 8, 17)
engine.log("Original: '" .. text .. "'", 255, 255, 255, 255)
engine.log("Modified: '" .. modified .. "'", 255, 255, 255, 255)
-- Output: "Hello, world!"

---

str.substitute

Signature: str.substitute(s, table)

Description: Replaces {key} placeholders in a string with values from a table.

Parameters:

• s (string): The template string with {key} placeholders.

• table (table): A table with key-value pairs for substitution.

Returns:

• string: The string with placeholders replaced by their values.

Example:

local template = "Hello, {name}! You are {age} years old."
local values = {
    name = "John",
    age = 30
}
local result = str.substitute(template, values)
engine.log("Template: '" .. template .. "'", 255, 255, 255, 255)
engine.log("Result: '" .. result .. "'", 255, 255, 255, 255)
-- Output: "Hello, John! You are 30 years old."

---

Case and Splitting

str.upper

Signature: str.upper(s)

Description: Converts a string to uppercase.

Parameters:

• s (string): The string to convert.

Returns:

• string: The uppercase string.

Example:

local text = "Hello, world!"
local upper = str.upper(text)
engine.log("Original: '" .. text .. "'", 255, 255, 255, 255)
engine.log("Uppercase: '" .. upper .. "'", 255, 255, 255, 255)
-- Output: "HELLO, WORLD!"

---

str.lower

Signature: str.lower(s)

Description: Converts a string to lowercase.

Parameters:

• s (string): The string to convert.

Returns:

• string: The lowercase string.

Example:

local text = "Hello, World!"
local lower = str.lower(text)
engine.log("Original: '" .. text .. "'", 255, 255, 255, 255)
engine.log("Lowercase: '" .. lower .. "'", 255, 255, 255, 255)
-- Output: "hello, world!"

---

str.split

Signature: str.split(s, delimiter)

Description: Splits a string by a delimiter into a table of substrings.

Parameters:

• s (string): The string to split.

• delimiter (string): The delimiter to split by.

Returns:

• table: A table of substrings.

Example:

local text = "apple,banana,orange,grape"
local parts = str.split(text, ",")
engine.log("Original: '" .. text .. "'", 255, 255, 255, 255)
engine.log("Split into " .. #parts .. " parts:", 255, 255, 255, 255)
for i, part in ipairs(parts) do
    engine.log("  " .. i .. ": '" .. part .. "'", 255, 255, 255, 255)
end
-- Output: ["apple", "banana", "orange", "grape"]

---

str.slice

---

Signature: str.slice(s, start, end)

Description: Returns a substring based on start and end positions.

Parameters:

• s (string): The original string.

• start (number): The starting position (1-based index).

• end (number, optional): The ending position (1-based index). Defaults to the end of the string.

Returns:

• string: The extracted substring.

Example:

local text = "Hello, world!"
local slice1 = str.slice(text, 1, 5)
local slice2 = str.slice(text, 8)
engine.log("Original: '" .. text .. "'", 255, 255, 255, 255)
engine.log("Slice 1-5: '" .. slice1 .. "'", 255, 255, 255, 255) -- Output: "Hello"
engine.log("Slice 8-end: '" .. slice2 .. "'", 255, 255, 255, 255) -- Output: "world!"

---

UTF-8 Support

str.utf8len

Signature: str.utf8len(s)

Description: Returns the number of UTF-8 characters in a string.

Parameters:

• s (string): The UTF-8 string.

Returns:

• number: The number of UTF-8 characters.

Example:

local ascii = "Hello"
local unicode = "你好, world!"
engine.log("ASCII string: '" .. ascii .. "'", 255, 255, 255, 255)
engine.log("Length: " .. #ascii .. ", UTF-8 length: " .. str.utf8len(ascii), 255, 255, 255, 255)
engine.log("Unicode string: '" .. unicode .. "'", 255, 255, 255, 255)
engine.log("Length: " .. #unicode .. ", UTF-8 length: " .. str.utf8len(unicode), 255, 255, 255, 255)

---

str.utf8sub

Signature: str.utf8sub(s, start, end)

Description: Returns a UTF-8 safe substring.

Parameters:

• s (string): The UTF-8 string.

• start (number): The starting character position (1-based).

• end (number, optional): The ending character position (1-based). Defaults to the end of the string.

Returns:

• string: The UTF-8 substring.

Example:

local text = "English and 中文 Japanese 日本語"
local substring = str.utf8sub(text, 13, 14)
engine.log("Original: '" .. text .. "'", 255, 255, 255, 255)
engine.log("UTF-8 substring (13-14): '" .. substring .. "'", 255, 255, 255, 255) -- Output: "Ja"