Module:Sandbox/TiiJ7/StringBuilder

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.

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"

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.
Example: sb:append('Some'):append(' string') -- "Some string"

appendAll (aa)

Appends multiple strings, separated by commas.
Example: sb:appendAll('A',' series',' of',' strings') -- "A series of strings"

clear (c)

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

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: sb:setMode('ignore'):append('My table: '):append({}) -- "My table: "

setSeparator (s)

Changes the separator with which the strings are concatenated (by default the empty string '').
Example: sb:setSeparator(','):appendAll('comma','separated','list') -- "comma,separated,list"

Examples

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

---

------------------------------------------------------------
-- Quick module to help creating a concatenated string.
-- To be used in other modules.
--
-- By User:TiiJ7
------------------------------------------------------------
 
local StringBuilder = {}
StringBuilder.__index = StringBuilder
local StringBuilderModes = { convert = true, ignore = true, error = true }
 
-- Creates a new string builder
function StringBuilder.new()
    local sb = {}
    setmetatable(sb,StringBuilder)
    sb._buffer = {}
    sb._mode = 'convert'
    sb._separator = ''
    return sb
end
 
-- Sets the mode of the string builder, see doc
function StringBuilder:setMode(mode)
    if not mode then return self end
    if StringBuilderModes[mode] then
        self._mode = mode
    end
    return self -- Method chaining
end
 
-- Sets the separator with which the strings are concatted
function StringBuilder:setSeparator(separator)
    if not separator then return self end
    separator = tostring(separator)
    if separator ~= nil then self._separator = separator end
    return self -- Method chaining
end
 
-- Appends a string
function StringBuilder:append(str)
    if str then
        self:_addString(str,self._buffer)
    end
    return self -- Method chaining
end
 
-- Appends multiple strings
function StringBuilder:appendAll(...)
    local argcount = select('#',...)
    if argcount then
        local b = self._buffer
        local f = self._addString
        for i=1,argcount do
           f(self,select(i,...),b)
        end
    end
    return self -- Method chaining
end
 
-- Clears the internal buffer
function StringBuilder:clear()
    local b = self._buffer
    for i=1,#b do
        b[i] = nil     
    end
    return self -- Method chaining
end
 
-- Returns the result as a string
function StringBuilder:toString()
    local b = self._buffer
    if #b == 0 then return '' end
    return table.concat(b,self._separator)
end
 
-- Adds a single string
function StringBuilder:_addString(str,t)
    if type(str) ~= 'string' and type(str) ~= 'number' then
        local m = self._mode
        if m == 'convert' then
            str = tostring(str)
            if not str then return end
        elseif m == 'error' then
            error( 'ERROR: Trying to append object of type "' .. type(str) .. '"' )
        else
            return
        end
    end
    t[#t+1] = str
end
 
-- Meta tostring function
function StringBuilder:__tostring()
    return self:toString()
end
 
-- Some function aliases...
StringBuilder.a = StringBuilder.append
StringBuilder.aa = StringBuilder.appendAll
StringBuilder.c = StringBuilder.clear
StringBuilder.m = StringBuilder.setMode
StringBuilder.s = StringBuilder.setSeparator
 
return StringBuilder