Skip to content

StringClass

Jump to bottom
github-actions[bot] edited this page Nov 23, 2024 · 7 revisions

StringClass

string.append

Appends a suffix to a string if it does not already end with that suffix. The check is done using PCRE regex pattern matching to ensure accurate suffix detection.

Parameters

  • str (string) - The string to append to.
  • suffix (string) - The suffix to append to the string.

Returns

string - The resulting string.

Examples

string.append("hello", " world")    -- "hello world"
string.append("hello world", "world") -- "hello world"

string.contains

Checks if a string contains a given pattern using PCRE regex. This is for finding patterns anywhere within the string. The pattern must not start with "^" or end with "$" - use starts_with() or ends_with() for those cases instead.

Parameters

  • str (string) - The string to check.
  • pattern (string) - The pattern to check for.

Returns

boolean - Whether the string contains the pattern.

Examples

string.contains("hello world", "world")     -- true
string.contains("hello world", "goodbye")   -- false

string.ends_with

Checks if a string ends with a given pattern using PCRE regex. If the pattern doesn't already end with "$", it will be automatically appended to ensure matching at the end of the string.

Parameters

  • str (string) - The string to check.
  • ending (string) - The pattern to check for.

Returns

boolean - Whether the string ends with the pattern.

Examples

string.ends_with("hello world", "world")     -- true
string.ends_with("hello world", "hello")     -- false
string.ends_with("test.lua", "\\.lua$")      -- true

string.format_number

Formats a number with thousands separators and decimal places. Works with both numbers and numeric strings. If not specified, uses "," for thousands and "." for decimal separator. Handles negative numbers and maintains decimal precision.

Parameters

  • number (number|string) - The number to format.
  • thousands (string?) - The thousands separator.
  • decimal (string?) - The decimal separator.

Returns

string - The formatted number.

Examples

string.format_number(1234567.89)           -- "1,234,567.89"
string.format_number(-1234.56)             -- "-1,234.56"
string.format_number(1234567, ".", ",")    -- "1.234.567"

string.ltrim

Removes whitespace characters from the beginning (left side) of a string. Whitespace includes spaces, tabs, and newlines.

Parameters

  • str (string) - The string to remove whitespace from.

Returns

string - The resulting string without whitespace on the left.

Examples

string.ltrim("  hello world  ")    -- "hello world  "
string.ltrim("\t\nhello")          -- "hello"

string.parse_formatted_number

Converts a formatted number string back into a number. Handles thousands and decimal separators, removing the thousands separators and converting the decimal separator to a period if necessary.

Parameters

  • str (string) - The string to parse.
  • thousands (string?) - The thousands separator.
  • decimal (string?) - The decimal separator.

Returns

number - The parsed number.

Examples

string.parse_formatted_number("1,234,567.89")       -- 1234567.89
string.parse_formatted_number("1.234.567,89", ".", ",")  -- 1234567.89

string.prepend

Prepends a prefix to a string if it does not already start with that prefix. Uses PCRE regex pattern matching to ensure accurate prefix detection.

Parameters

  • str (string) - The string to prepend to.
  • prefix (string) - The prefix to prepend to the string.

Returns

string - The resulting string.

Examples

string.prepend("world", "hello ")          -- "hello world"
string.prepend("hello world", "hello")     -- "hello world"

string.reg_assoc

Performs pattern matching using reg_assoc with PCRE regex support. Associates patterns with tokens and returns both the matched segments and their corresponding token assignments.

Parameters

  • text (string) - The text to search through
  • patterns (table) - The patterns to search for
  • tokens (table) - The tokens to replace the patterns with
  • default_token (string?) - The default token for unmatched text

Returns

table, table - The results table and token list

Examples

local results, tokens = string.reg_assoc(
   "hello world",
   {"hello", "world"},
   {"greeting", "place"}
)
- results: {"hello", " ", "world"}
- tokens: {"greeting", -1, "place"}

string.replace

Replaces all occurrences of a pattern in a string with a replacement string. Continues replacing until no more matches are found to handle overlapping or repeated patterns.

Parameters

  • str (string) - The string to replace the pattern in.
  • pattern (string) - The pattern to replace.
  • replacement (string) - The replacement string.

Returns

string - The resulting string.

Examples

string.replace("hello world", "o", "a")     -- "hella warld"
string.replace("test", "t", "p")            -- "pesp"

string.rtrim

Removes whitespace characters from the end (right side) of a string. Whitespace includes spaces, tabs, and newlines.

Parameters

  • str (string) - The string to remove whitespace from.

Returns

string - The resulting string without whitespace on the right.

Examples

string.rtrim("  hello world  ")    -- "  hello world"
string.rtrim("hello\t\n")          -- "hello"

string.split

Splits a string into a table of strings using PCRE regex. If no delimiter is provided, it defaults to ".", which will split the string into individual characters. The delimiter is treated as a regex pattern.

Parameters

  • str (string) - The string to split.
  • delimiter (string?) - The regex delimiter to split the string by.

Returns

string[] - The resulting array of strings.

Examples

string.split("hello world")           -- {"h", "e", "l", "l", "o", " ", "w", "o", "r", "l", "d"}
string.split("hello world", " ")      -- {"hello", "world"}
string.split("hello.world", "\\.")    -- {"hello", "world"}
string.split("hello world", "o")      -- {"hell", " w", "rld"}

string.starts_with

Checks if a string starts with a given pattern using PCRE regex. If the pattern doesn't already start with "^", it will be automatically prepended to ensure matching at the start of the string.

Parameters

  • str (string) - The string to check.
  • start (string) - The pattern to check for.

Returns

boolean - Whether the string starts with the pattern.

Examples

string.starts_with("hello world", "hello")     -- true
string.starts_with("hello world", "world")     -- false
string.starts_with("test.lua", "^test")        -- true

string.strip_linebreaks

Removes all line breaks from a string, including both \r and \n characters. Useful for converting multi-line text into a single line.

Parameters

  • str (string) - The string to strip line breaks from.

Returns

string - The resulting string without line breaks.

Examples

string.strip_linebreaks("hello\nworld")     -- "helloworld"
string.strip_linebreaks("hello\r\nworld")   -- "helloworld"

string.trim

Removes whitespace from both the beginning and end of a string. Whitespace includes spaces, tabs, and newlines.

Parameters

  • str (string) - The string to trim.

Returns

string - The trimmed string.

Examples

string.trim("  hello world  ")    -- "hello world"
string.trim("\t\nhello\n\t")      -- "hello"

string.walk

Creates an iterator that walks through a string character by character or by split segments if a delimiter is provided. Returns index and value pairs.

Parameters

  • input (string) - The string to walk through.
  • delimiter (string?) - The delimiter to split the string by.

Returns

function - The iterator function.

Examples

for i, part in string.walk("hello world") do
 print(i, part)  -- prints: 1,"h" 2,"e" 3,"l" 4,"l" 5,"o" 6," " 7,"w" 8,"o" 9,"r" 10,"l" 11,"d"
end

for i, part in string.walk("a,b,c", ",") do
 print(i, part)  -- prints: 1,"a" 2,"b" 3,"c"
end

Documentation generated with Gludoc.

Clone this wiki locally