--- Extends Lua 5.2 string.
-- @module StdLib.String
-- @alias string

-- luacheck: globals string (Allow mutating string)

--- Returns a copy of the string with any leading or trailing whitespace from the string removed.
-- @tparam string string s the to remove leading or trailing whitespace from
-- @treturn string a copy of the string without leading or trailing whitespace
function string.trim(s)
    return (s:gsub("^%s*(.-)%s*$", "%1"))
end

--- Tests if a string starts with a given substring.
-- @tparam string string s the to check for the start substring
-- @tparam string start the substring to test for
-- @treturn boolean true if the start substring was found in the string
function string.starts_with(s, start)
    return string.find(s, start, 1, true) == 1
end

--- Tests if a string ends with a given substring.
-- @tparam string string s the to check for the end substring
-- @tparam string ends the substring to test for
-- @treturn boolean true if the end substring was found in the string
function string.ends_with(s, ends)
    return #s >= #ends and string.find(s, ends, #s - #ends + 1, true) and true or false
end

--- Tests if a string contains a given substring.
-- @tparam string string s the to check for the substring
-- @tparam string contains the substring to test for
-- @treturn boolean true if the substring was found in the string
function string.contains(s, contains)
    return s and string.find(s, contains) ~= nil
end

--- Tests whether a string is empty.
-- @tparam string string s the to test
-- @treturn boolean true if the string is empty
function string.is_empty(s)
    return s == nil or s == ''
end

--- Splits a string into an array.
-- *Note:* Empty split substrings are not included in the resulting table.
-- <p>For example, `string.split("foo.bar...", ".", false)` results in the table `{"foo", "bar"}`.
-- @tparam string string s the to split
-- @tparam[opt="."] string sep the separator to use.
-- @tparam[opt=false] string boolean pattern whether to interpret the separator as a lua pattern or plaintext for the split
-- @treturn {string,...} an array of strings
function string.split(s, sep, pattern)
    sep = sep or "."
    sep = sep ~= "" and sep or "."
    sep = not pattern and string.gsub(sep, "([^%w])", "%%%1") or sep

    local fields = {}
    local start_idx, end_idx = string.find(s, sep)
    local last_find = 1
    while start_idx do
        local substr = string.sub(s, last_find, start_idx - 1)
        if string.len(substr) > 0 then
            table.insert(fields, string.sub(s, last_find, start_idx - 1))
        end
        last_find = end_idx + 1
        start_idx, end_idx = string.find(s, sep, end_idx + 1)
    end
    local substr = string.sub(s, last_find)
    if string.len(substr) > 0 then
        table.insert(fields, string.sub(s, last_find))
    end
    return fields
end

-- added by cooldude2606
--- Returns a string as a hex format (also a string)
-- @usage a = 'foo'
-- string.to_hex(a) -- return '666f6f'
-- @tparam string string str the to encode
-- @treturn string the hex format of the string
function string.to_hex(str)
    if not is_type(str,'string') then return '' end
    return str:gsub('.',function (c)
        return string.format('%02X',string.byte(c))
    end)
end