Map

The map object is a way to store key-value pairs which need to be iterated through often.

Unlike a standard table, this construct iterates using a simple incrementing number that goes through its set of keys. This avoids pairs, which would stop LuaJIT from JIT compiling the code.

Also unlike a standard table, iterating is always dependent on the order that key-value pairs were added.

To get a new map, use:

local Map = Shine.Map()

In cases where keys are likely to be added and removed regularly and the order of iteration is not important, an unordered variant also exists which removes keys in constant time:

local Map = Shine.UnorderedMap()

Its methods are identical to Shine.Map, except it does not guarantee a stable insertion-based key order.

Methods

Map:Add()

Adds a key-value mapping.

FoodOpinionMap:Add( "Cake", "Delicious" )

Map:Remove()

Removes a key-value mapping.

local RemovedKey, RemovedValue = FoodOpinionMap:Remove( "Cake" )

Map:Get()

Retrieves a value for the given key, if one exists in the map.

local Opinion = FoodOpinionMap:Get( "Cake" )

Map:GetCount()

Returns the number of key-value mappings stored.

local NumFoodOpinions = FoodOpinionMap:GetCount()

Map:IsEmpty()

A shortcut for Map:GetCount() == 0.

local LacksTaste = FoodOpinionMap:IsEmpty()

Map:Iterate()

Use it in a generic for statement to iterate the map easily. This iterates from oldest key-value pair to most recent.

for Food, Opinion in FoodOpinionMap:Iterate() do
    print( Food, Opinion )
end

Map:IterateBackwards()

If insertion-order is important to you, and you want to go backwards from most recent to oldest key-value pair, then this iterator will do that.

for Food, Opinion in FoodOpinionMap:IterateBackwards() do
    print( Food, Opinion )
end

Map:Filter()

Provides an efficient way to filter the map's key-values in-place.

-- Filter function receives key-value pairs, and whatever context value was passed. Use the context to avoid needing
-- closures.
local function FilterOpinions( Key, Value, AcceptableOpinions )
    return AcceptableOpinions[ Key ] == Value
end

FoodOpinionMap:Add( "Cake", "Delicious" )
FoodOpinionMap:Add( "Cookies", "Even Better" )

-- The map is modified in-place, though it is also returned for method chaining.
FoodOpinionMap:Filter( FilterOpinions, {
    Cake = "Delicious"
} )
--> Map( { Cake = "Delicious" } )

Map:SortKeys()

Sorts the keys of the map in-place using table.sort and an optional comparator function.

-- Sort using the default sorting order.
FoodOpinionMap:SortKeys()

-- Or sort using a comparator.
FoodOpinionMap:SortKeys( function( Left, Right ) return Left > Right end )

Map:StableSortKeys()

Sorts the keys of the map in-place using table.MergeSort and an optional comparator function.

-- Sort using the default sorting order.
FoodOpinionMap:StableSortKeys()

-- Or sort using a comparator.
FoodOpinionMap:StableSortKeys( function( Left, Right )
    if Left:StartsWith( "C" ) and Right:StartsWith( "C" ) then
        return 0
    end
    return Left < Right and -1 or 1
end )