LuaAPI/stringx - Revision history

Celtic Minstrel: Note that ipairs works too

2026-03-22T01:16:29Z

Note that ipairs works too

Celtic Minstrel: Document starts_with and ends_with

2024-09-21T17:45:42Z

Document starts_with and ends_with

Laela at 18:04, 18 April 2024

2024-04-18T18:04:18Z

Celtic Minstrel: /* stringx.escaped_split */ Somehow the default got misstated…

2024-02-13T07:51:59Z

‎stringx.escaped_split: Somehow the default got misstated…

Celtic Minstrel: /* stringx.iter_ranges */ Fix header

2023-01-21T16:07:54Z

‎stringx.iter_ranges: Fix header

Celtic Minstrel: /* strinx.iter_ranges */ Fix some missing plurals

2023-01-21T16:07:40Z

‎strinx.iter_ranges: Fix some missing plurals

Celtic Minstrel: /* stringx.vformat */ For some reason the method call version wasn't included

2023-01-21T16:05:56Z

‎stringx.vformat: For some reason the method call version wasn't included

Celtic Minstrel: Fix incorrect documentation of format_*_list functions

2021-07-26T05:06:31Z

Fix incorrect documentation of format_*_list functions

Celtic Minstrel: Move commas out of optional brackets

2021-07-04T22:19:44Z

Move commas out of optional brackets

Celtic Minstrel: Document trim and the range functions

2021-07-02T22:50:38Z

Document trim and the range functions

@@ Line 3: / Line 3: @@
 The <tt>stringx</tt> 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, <syntaxhighlight lang=lua inline>str[n]</syntaxhighlight> is a shorthand for <syntaxhighlight lang=lua inline>str:sub(n,n)</syntaxhighlight>. This means negative indices count from the end of the string, and invalid indices output an empty string.
+In addition, it permits extracting characters from a string by indexing with an integer. Basically, <syntaxhighlight lang=lua inline>str[n]</syntaxhighlight> is a shorthand for <syntaxhighlight lang=lua inline>str:sub(n,n)</syntaxhighlight>. This means negative indices count from the end of the string, and invalid indices output an empty string. It also means you can use <syntaxhighlight lang=lua inline>ipairs(str)</syntaxhighlight> to iterate over the characters of the string.
 == Functions ==

← Older revision		Revision as of 17:45, 21 September 2024
Line 78:		Line 78:

	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 <tt>,</tt> and the key-value separator defaults to <tt>:</tt>.		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 <tt>,</tt> and the key-value separator defaults to <tt>:</tt>.
		+
		+	=== stringx.ends_with ===
		+
		+	{{DevFeature1.19\|4}}
		+
		+	* '''stringx.ends_with'''(''string'', ''suffix'') → ''boolean''
		+
		+	Determines whether the string ends with the specified suffix.
		+
		+	=== stringx.starts_with ===
		+
		+	{{DevFeature1.19\|4}}
		+
		+	* '''stringx.starts_with'''(''string'', ''prefix'') → ''boolean''
		+
		+	Determines whether the string starts with the specified prefix.

	=== stringx.vformat ===		=== stringx.vformat ===

← Older revision		Revision as of 18:04, 18 April 2024
Line 4:		Line 4:

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

	=== stringx.split ===		=== stringx.split ===

@@ Line 26: / Line 26: @@
 * ''str'':'''escaped_split'''([''separator'', [''escape'']]) &rarr; ''list of strings''
-A convenient shorthand for specifying the '''escape''' option in '''stringx.split'''. The separator and escape default to <tt>,</tt> and <tt>/</tt> respectively.
+A convenient shorthand for specifying the '''escape''' option in '''stringx.split'''. The separator and escape default to <tt>,</tt> and <tt>\</tt> respectively.
 === stringx.quoted_split ===

@@ Line 129: / Line 129: @@
 </syntaxhighlight>
-=== strinx.iter_ranges ===
+=== stringx.iter_ranges ===
 * '''stringx.iter_ranges'''(''range strings'') &rarr; ''iterator'' &rArr; ''integer''

@@ Line 131: / Line 131: @@
 === strinx.iter_ranges ===
-* '''stringx.iter_range'''(''range strings'') &rarr; ''iterator'' &rArr; ''integer''
+* '''stringx.iter_ranges'''(''range strings'') &rarr; ''iterator'' &rArr; ''integer''
 * ''ranges'':'''iter_ranges'''() &rarr; ''iterator'' &rArr; ''integer''
@@ Line 137: / Line 137: @@
 <syntaxhighlight lang=lua>
-for i in stringx.iter_range "1-3,7-9" do
+for i in stringx.iter_ranges "1-3,7-9" do
    print(i)
 end
@@ Line 147: / Line 147: @@
 -- 8
 -- 9
-for i in stringx.iter_range "1-3,3-6" do
+for i in stringx.iter_ranges "1-3,3-6" do
    print(i)
 end

← Older revision		Revision as of 16:05, 21 January 2023
Line 80:		Line 80:

	* '''stringx.vformat'''(''format_string'', ''values'') → ''formatted string''		* '''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.		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.

@@ Line 87: / Line 87: @@
 === stringx.format_conjunct_list ===
-* '''stringx.format_conjunct_list'''(''list_of_strings'') &rarr; ''formatted string''
+* '''stringx.format_conjunct_list'''(''empty'', ''list_of_strings'') &rarr; ''formatted string''
-Formats a list of usually-translatable strings into a localized list string of the form "A, B, and C".
+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'''(''list_of_strings'') &rarr; ''formatted string''
+* '''stringx.format_disjunct_list'''(''empty'', ''list_of_strings'') &rarr; ''formatted string''
-Formats a list of usually-translatable strings into a localized list string of the form "A, B, or C".
+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 ===

@@ Line 23: / Line 23: @@
 === stringx.escaped_split ===
-* '''stringx.escaped_split'''(''str'' [, ''separator'' [, ''escape'']]) &rarr; ''list of strings''
+* '''stringx.escaped_split'''(''str'', [''separator'', [''escape'']]) &rarr; ''list of strings''
-* ''str'':'''escaped_split'''([''separator'' [, ''escape'']]) &rarr; ''list of strings''
+* ''str'':'''escaped_split'''([''separator'', [''escape'']]) &rarr; ''list of strings''
 A convenient shorthand for specifying the '''escape''' option in '''stringx.split'''. The separator and escape default to <tt>,</tt> and <tt>/</tt> respectively.
@@ Line 30: / Line 30: @@
 === stringx.quoted_split ===
-* '''stringx.quoted_split'''(''str'' [, ''separator'' [, ''quotes'' [, ''quotes'']]]) &rarr; ''list of strings''
+* '''stringx.quoted_split'''(''str'', [''separator'', [''quotes'', [''quotes'']]]) &rarr; ''list of strings''
-* ''str'':'''quoted_split'''([''separator'' [, ''quotes'' [, ''quotes'']]]) &rarr; ''list of strings''
+* ''str'':'''quoted_split'''([''separator'', [''quotes'', [''quotes'']]]) &rarr; ''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 <tt>,</tt> and the quotes default to <tt>(</tt> and <tt>)</tt>.
@@ Line 37: / Line 37: @@
 === stringx.anim_split ===
-* '''stringx.anim_split'''(''str'' [, ''separator'']) &rarr; ''list of strings''
+* '''stringx.anim_split'''(''str'', [''separator'']) &rarr; ''list of strings''
 * ''str'':'''anim_split'''([''separator'']) &rarr; ''list of strings''
@@ Line 53: / Line 53: @@
 === stringx.map_split ===
-* '''stringx.map_split'''(''str'' [, ''item separator'' [, ''key-value separator'' [, ''options'']]) &rarr; ''string map''
+* '''stringx.map_split'''(''str'', [''item separator'', [''key-value separator'', [''options'']]) &rarr; ''string map''
-* ''str'':'''map_split'''([''item separator'' [, ''key-value separator'' [, ''options'']]) &rarr; ''string map''
+* ''str'':'''map_split'''([''item separator'', [''key-value separator'', [''options'']]) &rarr; ''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 <tt>,</tt> and the key-value separator defaults to <tt>:</tt>. The options table supports the following keys:
@@ Line 65: / Line 65: @@
 === stringx.join ===
-* '''stringx.join'''(''list of strings'' [, ''separator'']) &rarr; ''string''
+* '''stringx.join'''(''list of strings'', [''separator'']) &rarr; ''string''
 * ''separator'':'''join'''(''list of strings'') &rarr; ''string''
@@ Line 72: / Line 72: @@
 === stringx.join_map ===
-* '''stringx.join_map'''(''string map'' [, ''item separator'' [, ''key-value separator'']]) &rarr; ''string''
+* '''stringx.join_map'''(''string map'', [''item separator'', [''key-value separator'']]) &rarr; ''string''
-* ''item_separator'':'''join_map'''(''string map'' [, ''key-value separator'']) &rarr; ''string''
+* ''item_separator'':'''join_map'''(''string map'', [''key-value separator'']) &rarr; ''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 <tt>,</tt> and the key-value separator defaults to <tt>:</tt>.

← Older revision		Revision as of 22:50, 2 July 2021
Line 96:		Line 96:

	Formats a list of usually-translatable strings into a localized list string of the form "A, B, or C".		Formats a list of usually-translatable strings into a localized list string of the form "A, B, or C".
		+
		+	=== 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 <syntaxhighlight lang=lua inline>"1-5"</syntaxhighlight> 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 <syntaxhighlight lang=lua inline>"1-5"</syntaxhighlight>.
		+
		+	<syntaxhighlight lang=lua>
		+	for i in stringx.iter_range "1-3" do
		+	print(i)
		+	end
		+	-- Output:
		+	-- 1
		+	-- 2
		+	-- 3
		+	</syntaxhighlight>
		+
		+	=== 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.
		+
		+	<syntaxhighlight lang=lua>
		+	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
		+	</syntaxhighlight>

	[[Category:Lua Reference]]		[[Category:Lua Reference]]