Editing Module:Sandbox/TiiJ7/StringBuilder/doc

'''StringBuilder''' is a simple module that can be used to concatenate many strings into one bigger string. It stores all strings in a table and then concatenates them all in one go. This is more efficient than concatenating strings manually. For small strings however, the difference is negligible, so you should use the StringBuilder for building enormous string only.

== Usage ==
This module should only be used in other modules, rather than being invoked.

<syntaxhighlight lang="lua">
local StringBuilder = require('Module:Sandbox/TiiJ7/StringBuilder')

local sb = StringBuilder.new()

sb:append('This')
sb:appendAll(' is',' a',' test')

tostring(sb) -- "This is a test"
</syntaxhighlight>

== Method overview ==
Below are the available methods for the StringBuilder. They should be called with the colon syntax.

Most methods have a name shortcut, which is listed between brackets.

All methods also return the same StringBuilder, so you can use method chaining.

=== append (a) ===
Appends a single string to the builder.
<br>'''Example:''' <code>sb:append('Some'):append(' string') -- "Some string"</code>

=== appendAll (aa) ===
Appends multiple strings, separated by commas.
<br>'''Example:''' <code>sb:appendAll('A',' series',' of',' strings') -- "A series of strings"</code>

=== clear (c) ===
Resets the builder (erases all strings from internal buffer). Make sure to take a tostring before you clear the builder if needed!
<br>'''Example:''' <code>sb:append('Old text'):clear():append('New text') -- "New text"</code>

=== setMode (m) ===
Changes the mode of the StringBuilder. The mode decides what will happen if the user tries to append a non-string and non-number:
* '''convert''' (default) - Converts the argument to a string by calling tostring() on it.
* '''ignore''' - Simply ignores invalid values and doesn't append them.
* '''error''' -- Raises a Lua error, effectively stopping the script unless handled with pcall. Should be used for debugging only.
'''Example:''' <code>sb:setMode('ignore'):append('My table: '):append({}) -- "My table: "</code>

=== setSeparator (s) ===
Changes the separator with which the strings are concatenated (by default the empty string <nowiki>''</nowiki>).
<br>'''Example:''' <code>sb:setSeparator(','):appendAll('comma','separated','list') -- "comma,separated,list"</code>

== Examples ==
<syntaxhighlight lang="lua">
-- Building a simple XML element:
local elem = { tag = 'foo', name = 'bar', content = 'baz' }
local sb = StringBuilder.new()

-- method 1 (append):
sb:a('<'):a(elem.tag):a('name="'):a(elem.name):a('">')
    :a(elem.content):a('</'):a(elem.tag):a('>') -- "<foo name="bar">baz</text>"

-- method 2 (appendAll):
sb:aa('<', elem.tag, 'name="', elem.name, '">', elem.content, '</', elem.tag, '>') -- "<foo name="bar">baz</text>"
</syntaxhighlight>