Iterative Library

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