General Libraries

-- Table Library

--[[
    Documentation

    This is my extention of the Lua tables library.  I hope you find them all useful.

    The following examples will all be interrelated and will create a very basic stats table.

    Here are descriptions of each function and how to use them:

    table.save(t, filename)

        -- t: <table> The table you'll be saving into a textfile.
        -- filename: <string> The name of the file you'll be saving this table to.

        Example:

            function OnScriptUnload()

                table.save(players, "players.data")
            end

        Notes:

            -- By default, table.save saves your table in "Documents\\My Games\\Halo\\data".

    table.load(filename)

        -- filename: <string> The name of the file you want to load a table from.

        Example:

            function OnScriptLoad(process, game, persistent)

                players = table.load("players.data")
            end

            function OnPlayerJoin(player)

                makestats(player)
            end

            function makestats(player)

                local hash = gethash(player)
                stats[hash] = table.load(hash .. ".data")

                players[hash] = players[hash] or {}
                players[hash].joins = players[hash].joins or 0 + 1

                stats[hash].name = stats[hash].name or getname(player)

                stats[hash].kills = stats[hash].kills or {}
                stats[hash].kills.humanweap = stats[hash].kills.humanweap or 0
                stats[hash].kills.covenantweap = stats[hash].kills.covenantweap or 0
            end

        Notes:

            -- If the file doesn't exist or is empty, table.load returns an empty table {}.

    table.len(t)

        -- t: <table> Table you want to find the length of.

        Returns:  Total length of table.

        Example:

            local total_players = table.len(players)

        Notes:

            -- The reason this function is necessary is because #t returns the length of a table as defined by ipairs.  This means Lua begins at index 1 of table t and adds 1 to the index until the value at the current index is nil.  If you have a table that is indexed by hashes, #players will return 0 because players[1] = nil.  table.len returns the length of a table including non-numeric keys.

    table.find(t, v, [case])

        -- t: <table> Table you're searching.
        -- v: <any type> Value you're searching for in the table.
        -- case: <boolean> Defines if the value should be case-sensitive (default = true).

        Returns:  The key at which the specified value is found.

        Example:

            swears = {"balls", "boners", "poppycock"}  -- My name is Nuggets and I (dis)approve of these words.

            function OnServerChat(player, type, message)

                if player then
                    local words = tokenizestring(message)
                    for k,v in ipairs(words) do
                        if table.find(swears, v, false) then  -- ensures that "boners" as well as "BONERS" and "bOnErS" are all blocked (poor boners).
                            privatesay(player, "YOU HAVE SAID EVIL THINGS.")
                            return false
                        end
                    end
                end
            end

    table.max(t)

        -- t: <table> Table you want to find the maximum value of.

        Returns:  Key which contains the maximum value as well as the maximum value.

        Example:

            function OnPlayerKill(killer, victim, mode)

                local khash = gethash(killer)
                if humanweapon(killer) then  -- making up a function here to get to the point
                    stats[khash].kills.humanweap = stats[khash].kills.humanweap + 1
                end

                local weaptype, kills = table.max(stats[khash].kills)
                privatesay(killer, "You have the most kills with " .. weaptype .. ": " .. kills)
            end

            >> You have the most kills with humanweap: 12

    table.maxv(t)

        -- See table.max; the only difference is this function only returns the maximum value, not the key at which it was found.

    table.maxes(t)

        -- t: <table> Table of which you would like to find the keys which have the maximum values.

        Returns:  A table of keys which all contain the maximum value of the table and the maximum value.

        Example:

            local t = {1, 2, 2, 5, 7, 2, 7, 3, 7, 7}
            local keys, max = table.maxes(t)

            for k,v in ipairs(keys) do
                hprintf(v)
            end

            hprintf("Max: " .. max)

            >> 5
            >> 7
            >> 9
            >> 10
            >> Max: 7

    table.sum(t)

        -- t: <table> Table of which you would like to find the sum of all numerical values.

        Returns:  Sum of all numerical values of the table specified and all tables nested within the table specified.

        Example:

            function OnPlayerKill(killer, victim, mode)

                local khash = gethash(killer)
                local total_kills = table.sum(stats[khash].kills)
                privatesay(killer, "You have " .. total_kills .. " total kills.")
            end


    If you have any questions about how any of these functions work, PM me (Nuggets) at phasor.proboards.com.
--]]

math.inf = 1 / 0

function table.save(t, filename)

    local dir = getprofilepath()
    local file = io.open(dir .. "\\data\\" .. filename, "w")
    local spaces = 0

    local function tab()

        local str = ""
        for i = 1,spaces do
            str = str .. " "
        end

        return str
    end

    local function format(t)

        spaces = spaces + 4
        local str = "{ "

        for k,v in opairs(t) do
            -- Key datatypes
            if type(k) == "string" then
                k = string.format("%q", k)
            elseif k == math.inf then
                k = "1 / 0"
            end

            -- Value datatypes
            if type(v) == "string" then
                v = string.format("%q", v)
            elseif v == math.inf then
                v = "1 / 0"
            end

            if type(v) == "table" then
                if table.len(v) > 0 then
                    str = str .. "\n" .. tab() .. "[" .. k .. "] = " .. format(v) .. ","
                else
                    str = str .. "\n" .. tab() .. "[" .. k .. "] = {},"
                end
            else
                str = str .. "\n" .. tab() .. "[" .. k .. "] = " .. tostring(v) .. ","
            end
        end

        spaces = spaces - 4

        return string.sub(str, 1, string.len(str) - 1) .. "\n" .. tab() .. "}"
    end

    file:write("return " .. format(t))
    file:close()
end

function table.load(filename)

    local dir = getprofilepath()
    local file = loadfile(dir .. "\\data\\" .. filename)
    if file then
        return file() or {}
    end

    return {}
end

function table.len(t)

    local count = 0
    for k,v in pairs(t) do
        count = count + 1
    end

    return count
end

function table.find(t, v, case)

    if case == nil then case = true end

    for k,val in pairs(t) do
        if case then
            if v == val then
                return k
            end
        else
            if string.lower(v) == string.lower(val) then
                return k
            end
        end
    end
end

function table.max(t)

    local max = -math.inf
    local key

    for k,v in pairs(t) do
        if tonumber(v) then
            if tonumber(v) > max then
                key = k
                max = tonumber(v)
            end
        end
    end

    return key,max
end

function table.maxv(t)

    local max = -math.inf
    local key

    for k,v in pairs(t) do
        if tonumber(v) then
            if tonumber(v) > max then
                key = k
                max = tonumber(v)
            end
        end
    end

    return max
end

function table.maxes(t)

    local keys = {}
    local max = -math.inf
    for k,v in pairs(t) do
        if tonumber(v) then
            if tonumber(v) > max then
                max = tonumber(v)
            end
        end
    end

    for k,v in pairs(t) do
        if tonumber(v) == max then
            table.insert(keys, k)
        end
    end

    return keys,max
end

function table.sum(t, key)

    local sum = 0
    for k,v in pairs(t) do
        if type(v) == "table" then
            sum = sum + table.sum(v, key)
        elseif tonumber(v) then
            if key then
                if key == k then
                    sum = sum + tonumber(v)
                end
            else
                sum = sum + tonumber(v)
            end
        end
    end

    return sum
end

-- Iterative Functions

--[[
    Documentation:

    These are all iterative functions.  Iterative functions are used in loops (pairs and ipairs are two examples) and can be very useful if you want to loop through a table or numbers in a specific order.

    All of the following examples will be assuming the following table exists:

    t = {}
    t[1] = 7
    t[2] = 8
    t[5] = -2
    t["cheese"] = 10
    t["derp"] = -14

    Here are descriptions of each function and how to use them:

    opairs

        Syntax:

            for k,v in opairs(t) do
                hprintf(k .. ": " .. v)
            end

        When to use:

            -- The function opairs is short for "ordered pairs".  This iterative function will loop through all elements of a table (including string keys) in alphanumeric order.
            -- Contrary to most beginning scripters' beliefs, ipairs does NOT do this.  ipairs loops through a table beginning at index 1 and adds 1 to the index until the value at the current index is nil.
            -- Example of why this is useful:

                for k,v in opairs(t) do
                    hprintf(k .. ": " .. v)
                end

                >> 1: 7
                >> 2: 8
                >> 5: -2
                >> cheese: 10
                >> derp: -14

                for k,v in ipairs(t) do
                    hprintf(k .. ": " .. v)
                end

                >> 1: 7
                >> 2: 8

                -- ipairs only prints up to key 2 because t[3] = nil.  All other keys are disregarded by ipairs.

    rpairs

        -- See opairs for details; rpairs is exactly the same, but loops in reverse order.

    expairs

        Syntax:

            for k,v in expairs(t, function(key, value) return true end)
                hprintf(k .. ": " .. v)
            end

        When to use:

            -- expairs allows you to loop through a table while using a function to determine which keys and values the loop should consider.
            -- For example:

                -- Only loop through numerical keys
                for k,v in expairs(t, function(key, value) return type(key) == "number" end)
                    hprintf(k .. ": " .. v)
                end

                >> 1: 7
                >> 2: 8
                >> 5: -2

    irand

        Syntax:

            for i in irand(min, max) do
                hprintf(i)
            end

        When to use:

            -- irand iterates from min to max in a random order.
            -- Example:

                for i in irand(0,15) do
                    say(getname(i))
                end

                >> Oxide
                >> Nuggets
                >> Wizard
                >> Chalonic


    Iterative functions can be tricky, so let me know if you need help with any of them.  PM me (Nuggets) at phasor.proboards.com for any questions you have.
--]]

function opairs(t)

    local keys = {}
    for k,v in pairs(t) do
        table.insert(keys, k)
    end
    table.sort(keys,
    function(a,b)
        if type(a) == "number" and type(b) == "number" then
            return a < b
        end
        an = string.lower(tostring(a))
        bn = string.lower(tostring(b))
        if an ~= bn then
            return an < bn
        else
            return tostring(a) < tostring(b)
        end
    end)
    local count = 1
    return function()
        if table.unpack(keys) then
            local key = keys[count]
            local value = t[key]
            count = count + 1
            return key,value
        end
    end
end

function rpairs(t)

    local keys = {}
    for k,v in pairs(t) do
        table.insert(keys, k)
    end
    table.sort(keys,
    function(a,b)
        if type(a) == "number" and type(b) == "number" then
            return a > b
        end
        an = string.lower(tostring(a))
        bn = string.lower(tostring(b))
        if an ~= bn then
            return an > bn
        else
            return tostring(a) > tostring(b)
        end
    end)
    local count = 1
    return function()
        if table.unpack(keys) then
            local key = keys[count]
            local value = t[key]
            count = count + 1
            return key,value
        end
    end
end

function expairs(t, fn)

    local keys = {}
    for k,v in opairs(t) do
        if fn(k,v) then
            table.insert(keys, k)
        end
    end
    local count = 1
    return function()
        if table.unpack(keys) then
            local key = keys[count]
            local value = t[key]
            count = count + 1
            return key,value
        end
    end
end

function irand(min, max)

    local u = {}
    for i = min,max do
        table.insert(u, i)
    end
    return function()
        if table.unpack(u) then
            local rand = getrandomnumber(1, #u + 1)
            local value = u[rand]
            table.remove(u, rand)
            return value
        end
    end
end