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.

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

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(list_of_strings) → formatted string

Formats a list of usually-translatable strings into a localized list string of the form "A, B, and C".

stringx.format_disjunct_list

stringx.format_disjunct_list(list_of_strings) → formatted string

Formats a list of usually-translatable strings into a localized list string of the form "A, B, or C".