Difference between revisions of "LuaAPI/stringx"

Revision as of 21:26, 26 December 2020

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.

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.

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.

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.

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 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.

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.

@@ Line 16: / Line 16: @@
 * '''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: <syntaxhighlight lang=lua inline>{escape = [[\]]}</syntaxhighlight>
 * '''quote''': Specify one or more quote characters. Any separators within the matching instances of the quotes will not be considered for splitting. For example: <syntaxhighlight lang=lua inline>{quote = [['"]]}</syntaxhighlight>
-* '''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: <syntaxhighlight lang=lua inline>{quote_left = [=[([]=], quote_right = [=[)]]=]</syntaxhighlight>
+* '''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: <syntaxhighlight lang=lua inline>{quote_left = '([', quote_right = ')]'</syntaxhighlight>
 * '''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.