string.lua

--- A simple module for dealing with strings and unicode.
-- @module string
-- @type String
local String = {}
String.__index = String
local utf8 = require "utf8"

--- Creates a String object.
-- @tparam string text The text to encapsulate.
-- @return The String object.
function String:__call(text)
    local s = {text=text}
    setmetatable(s, self)
    return s
end

--- Returns the encapsulated text.
function String:__tostring()
    return self.text
end

--- Returns the length, in characters, of the string.
function String:__len()
    return utf8.len(self.text)
end

--- Joins two strings
function String:__concat(s)
    return String(self.text .. s)
end

--- Returns the index of the last byte of the character.
local endOffset = function(s, char)
    local charSize = #String(s):getChar(char)

    return utf8.offset(s, char) + charSize - 1
end

--- Returns a substring of the string.
-- @see string.sub
function String:sub(start, finish)
    finish = finish or self:__len()

    local ustart = utf8.offset(self.text, start)
    local ufinish = endOffset(self.text, finish)

    return string.sub(self.text, ustart, ufinish)
end

--- Returns the character at the provided index
function String:getChar(index)
    -- This is a horrible hack, don't do this...
    return utf8.char(utf8.codepoint(self.text, utf8.offset(self.text, index)))
end

--- Returns the position (in bytes) where the encoding of the n-th character starts.
-- @see utf8.offset
function String:offset(...)
    return utf8.offset(self.text, ...)
end

setmetatable(String, String)
return String