--- Returns the split name and hashtag from an Atelier 801 username
--
-- @param  username  The original username string.
--
-- @return           (Pair) The user's name (before hashtag) and hashtag.
--
function username_and_tags(username)
    local name, hashtag

    if not username then
        error("Username argument not supplied.")
    end

    if username:sub(1,1) == '+' then
        name = username
    else
        local tagLocation = username:find('#')
        if tagLocation then
            name = username:sub(1, tagLocation - 1)
            hashtag = username:sub(tagLocation, -1)
        else
            name = username
        end
    end
    return name, hashtag
end

--- Checks if a given full or partial Atelier 801 username is within the given list.
--
-- @param       username  The username string.
--
-- @param[opt]  list      The list to check within. If no list supplied,
--                        tfm.get.room.playerList is used.
--
-- @param[opt]  values    If true, the values inside the list will be checked
--                        instead of the keys.
--
-- @return                Returns true if a single name is found.
--                        Returns false if no names are found.
--                        Returns a list of names if multiple are found.
--
function user_in_list(username, list, values)
    local name, hashtag = username_and_tags(username)
    local list = list or tfm.get.room.playerList
    local values = values or false
    local playersFound = {}

    for iteration_key, iteration_value in pairs(list) do
        local valueToCheck = values and iteration_value or iteration_key
        local nameToCheck, hashtagToCheck = username_and_tags(valueToCheck)

        if name == nameToCheck and (not hashtag or hashtag == hashtagToCheck) then
            table.insert(playersFound, valueToCheck)
        end
    end

    if #playersFound == 0 then
        return false
    end

    if #playersFound == 1 then
        return true
    end

    return playersFound
end

local playerListAssociative = {
    ["Shamousey#0000"] = true,
    ["Shamousey#1234"] = true,
    ["Shamousey#9999"] = true,
    ["Tigrounette#0000"] = true,
    ["+Goondad"] = true,
}

local playerListFlat = {
    [1] = "Shamousey#0000",
    [2] = "Shamousey#1234",
    [3] = "Shamousey#9999",
    [4] = "Tigrounette#0000",
    [5] = "+Goondad",
}

do
    -- An error is thrown if no username is passed.
    assert(false == pcall(function() user_in_list() end))

    -- Fully qualified usernames return true.
    assert(true  == user_in_list("Shamousey#0000", playerListAssociative))
    assert(true  == user_in_list("Tigrounette#0000", playerListAssociative))
    assert(true  == user_in_list("+Goondad", playerListAssociative))
    assert(true  == user_in_list("Tigrounette#0000", playerListAssociative))

    -- Usernames without the hashtag that exist will return either true or a list.
    assert(true  == user_in_list("Tigrounette", playerListAssociative))
    assert(3     == #user_in_list("Shamousey", playerListAssociative))

    -- Usernames that can not be found at all return false.
    assert(false == user_in_list("+Goond", playerListAssociative))
    assert(false == user_in_list("+Goondad#0000", playerListAssociative))
    assert(false == user_in_list("Melibellule#0000", playerListAssociative))
    assert(false == user_in_list("Melibellule", playerListAssociative))
    assert(false == user_in_list("Shamo", playerListAssociative))

    -- The same methods also work when checking for a value instead of a key
    assert(true  == user_in_list("Shamousey#0000", playerListFlat, true))
    assert(true  == user_in_list("+Goondad", playerListFlat, true))
    assert(true  == user_in_list("Tigrounette", playerListFlat, true))
    assert(3     == #user_in_list("Shamousey", playerListFlat, true))
    assert(false == user_in_list("+Goond", playerListFlat, true))
    assert(false == user_in_list("+Goondad#0000", playerListFlat, true))

    print("All tests passed.")
end