LuaAPI/stringx

(Version 1.15.3 and later only)

The stringx module contains additional string support functions. It also registers itself as the string metatable so that these functions can be called directly on strings.

In addition, it permits extracting characters from a string by indexing with an integer. Basically, str[n] is a shorthand for str:sub(n,n). This means negative indices count from the end of the string, and invalid indices output an empty string.

stringx.split

• stringx.split(str, [separator] , [options]) → list of strings
• str:split([separator] , [options]) → list of strings

Splits a string on a separator character, which currently must be a single character and defaults to ','. The optional options table controls how the string is split (beyond the basic option of the separator character). It can contain the following keys:

• remove_empty: If true, empty strings are omitted from the result. If the options table is omitted, this will default to true; otherwise, it will default to false.
• strip_spaces: Spaces surrounding the separator character are stripped. If the options table is omitted, this will default to true; otherwise, it will default to false.
• escape: Specify a single character as the "escape" character. If a separator character is preceded by this character, then it will not be considered for splitting. The escape character is not removed from the result strings. This option is incompatible with the quote options. For example: {escape = [[\]]}
• quote: Specify one or more quote characters. Any separators within the matching instances of the quotes will not be considered for splitting. For example: {quote = [['"]]}
• quote_left, quote_right: As above, but you can separately specify opening and closing versions of each quote. The first left quote will match the first right quote, the second left quote will match the second right quote, and so on. For example: {quote_left = '([', quote_right = ')]'
• expand_anim: If true, expand the progressive string syntax of AnimationWML. This option is compatible with the quote options, but since the progressive string syntax treats square brackets as special characters, they may not be specified as quote characters with this option.

stringx.escaped_split

• stringx.escaped_split(str, [separator, [escape]]) → list of strings
• str:escaped_split([separator, [escape]]) → list of strings

A convenient shorthand for specifying the escape option in stringx.split. The separator and escape default to , and / respectively.

stringx.quoted_split

• stringx.quoted_split(str, [separator, [quotes, [quotes]]]) → list of strings
• str:quoted_split([separator, [quotes, [quotes]]]) → list of strings

A convenient shorthand for specifying quote options in stringx.split. If two quote parameters are passed, they are in the order left, right. The separator defaults to , and the quotes default to ( and ).

stringx.anim_split

• stringx.anim_split(str, [separator]) → list of strings
• str:anim_split([separator]) → list of strings

A convenient shorthand for specifying the expand_anim option in stringx.split. The separator defaults to ,.

stringx.parenthetical_split

• stringx.parenthetical_split(str, left_parens, right_parens) → list of strings
• str:parenthetical_split(left_parens, right_parens) → list of strings

Splits a string into parenthesized portions and portions between the parenthesized portions. With multiple parenthesis types, only the toplevel type at a given point participates in the split. The parentheses default to ( and ) respectively.

stringx.map_split

• stringx.map_split(str, [item separator, [key-value separator, [options]]) → string map
• str:map_split([item separator, [key-value separator, [options]]) → string map

Splits a string into key-value pairs based on the two separators, which currently must each be a single character. The item separator defaults to , and the key-value separator defaults to :. The options table supports the following keys:

• remove_empty, strip_spaces: Same as in stringx.split above.
• default: Used as the value if any item is missing the key_value_separator.

stringx.join

• stringx.join(list of strings, [separator]) → string
• separator:join(list of strings) → string

Joins a list of strings into a single string using the specified separator string. Accepts its arguments in either order. If omitted, the separator defaults to ,.

stringx.join_map

• stringx.join_map(string map, [item separator, [key-value separator]]) → string
• item_separator:join_map(string map, [key-value separator]) → string

Joins a map of strings into a single string using the specified separators. Keys will be output in lexicographical order. Accepts its arguments in any order, with the caveat that the item separator must appear before the key-value separator. If omitted, the item separator defaults to , and the key-value separator defaults to :.

stringx.vformat

• stringx.vformat(format_string, values) → formatted string
• string:vformat(values) → formatted string

Similar to string.format but using Wesnoth's variable substitution syntax, and also supporting translatable strings. Any valid WML table can be passed as the values, though typically you will only need key-value pairs. You could also substitute WML variables into a string by passing wml.all_variables as the second parameter.

This function preserves the translatability of the input format string.

stringx.format_conjunct_list

• stringx.format_conjunct_list(empty, list_of_strings) → formatted string

Formats a list of usually-translatable strings into a localized list string of the form "A, B, and C". If the list contains no elements, returns empty.

stringx.format_disjunct_list

• stringx.format_disjunct_list(empty, list_of_strings) → formatted string

Formats a list of usually-translatable strings into a localized list string of the form "A, B, or C". If the list contains no elements, returns empty.

stringx.trim

• stringx.trim(str) → trimmed string
• str:trim() → trimmed string

Strips out any leading and trailing whitespace from the string and returns the resulting string.

stringx.parse_range

• stringx.parse_range(range string) → start, end
• range:parse_range() → start, end

Parses a range of the form "1-5" and returns the endpoints of the range as two separate values.

stringx.iter_range

• stringx.iter_range(range string) → iterator ⇒ integer
• range:iter_range() → iterator ⇒ integer

Iterate over a range of the form "1-5".

for i in stringx.iter_range "1-3" do
  print(i)
end
-- Output:
-- 1
-- 2
-- 3

strinx.iter_ranges

• stringx.iter_range(range strings) → iterator ⇒ integer
• ranges:iter_ranges() → iterator ⇒ integer

Iterates over a sequence of comma-separated ranges. If the ranges overlap, numbers will be yielded more than once.

for i in stringx.iter_range "1-3,7-9" do
  print(i)
end
-- Output:
-- 1
-- 2
-- 3
-- 7
-- 8
-- 9
for i in stringx.iter_range "1-3,3-6" do
  print(i)
end
-- Output:
-- 1
-- 2
-- 3
-- 3
-- 4
-- 5
-- 6