ordered map - MSUTeam/MSU GitHub Wiki

File Path: /msu/classes/ordered_map.nut

An ordered map is a wrapper class for a squirrel table and array that effectively functions like a squirrel table with element order preserved. It can be interacted with just like a normal table except for the functions listed below.

• Constructor
• Functions
  • addTable
  • sort
  • in / contains
  • shuffle
  • reverse
  • apply
  • filter
  • map
  • values
  • keys
  • toTable

local orderedMap = ::MSU.Class.OrderedMap( _table = null );
// _table is a table

If _table is null, the Ordered Map initializes empty, if it isn't, after initialization the Ordered Map calls this.addTable(_table).

<OrderedMap>.addTable( _table, _overwrite = true );
// _table is a table
// _overwrite is a boolean

Iterates over all the slots in _table and creates new slots in the Ordered Map with the same keys and values. Values which are reference types are stored as references. If a key in _table already exists in the Ordered Map then if _overwrite is true it's value is updated to be the one in _table, and if _overwrite is false, it throws a ::MSU.Exception:DuplicateKey.

<OrderedMap>.sort(function( _key1, _value1, _key2, _value2 ) {
    // return 1 if (_key1, _value1) should be ordered before (_key2, _value2)
    // return 0 if they are equal
    // return -1 if (_key2, _value2) should be ordered before (_key1, _value1)
});

Unlike for an array, OrderedMap.sort accepts a function which should should accept 4 arguments. The keys and values are the keys and values for the table.

<OrderedMap>.contains( _key );
// Returns a bool

When using in on an Ordered Map, squirrel checks if the key is contained in the class instance. Since there is no way to overwrite this behavior, contains must be used to check if the OrderedMap contains a key.

<OrderedMap>.shuffle();

Since ::MSU.Array.shuffle(<Array>) does not work on an OrderedMap, this function must be used to randomly shuffle the Ordered Map.

<OrderedMap>.reverse();

Works just like <Array>.reverse() and reverses the order of its elements.

<OrderedMap>.apply( _function )
// function is a function with _key, _val, _idx parameters
// _key is a key in the OrderedMap
// _val is a value in the OrderedMap corresponding to _key
// _idx is an int

Works just like <Array>.apply(_function) except for the different function parameters. Iterates over all the elements in the Ordered Map, calling _function on them and passing:
_key: the current key being iterated over
_value: the current value being iterated over
_idx: the internal position of the _key being iterated over

<OrderedMap>.filter( _function )
// _function is a function with _key, _val, _idx parameters
// _key is a key in the OrderedMap
// _val is a value in the OrderedMap corresponding to _key
// _idx is an int

Works just like <Array>.filter(_function) except for the different function parameters. Iterates over all the elements in the Ordered Map, adding them to a new Ordered Map if _function returns true. Then returns the new Ordered Map.
_key: the current key being iterated over
_value: the current value being iterated over
_idx: the internal position of the _key being iterated over

<OrderedMap>.map( _function )
// _function is a function with _key, _val, _idx parameters
// _key is a key in the OrderedMap
// _val is a value in the OrderedMap corresponding to _key
// _idx is an int

Works just like <Array>.map(_function) except for the different function parameters. Iterates over all the elements in the Ordered Map, calling _function on them and adding the return value of _function to a new Ordered Map. Then returns the new Ordered Map.
_key: the current key being iterated over
_value: the current value being iterated over
_idx: the internal position of the _key being iterated over

<OrderedMap>.values()

Returns an array of the values in the Ordered Map.

<OrderedMap>.keys()

Returns an array of the keys in the Ordered Map.

<OrderedMap>.toTable()

Returns a table with the same keys and values as in the Ordered Map.

<OrderedMap>.onSerialize( _out )
// _out is the C++ object passed to BB onSerialize functions

Serializes the Ordered Map.

<OrderedMap>.onDeserialize( _in )
// _in is the C++ object passed to BB onDeserialize functions

Deserializes the Ordered Map.

local orderedMap = ::MSU.Class.OrderedMap();
orderedMap.key1 <- 30;
orderedMap["key2"] <- 20;

foreach(key, value in orderedMap)
{
    this.logInfo(key + " | " + value);
}
// This would print out:
// "key1 | 30"
// "key2 | 20"

orderedMap.sort(function( _k, _v, _k1, _v1 )
{
    return _v <=> _v1;
});
// We sort according to the values in the table

foreach(key, value in orderedMap)
{
    this.logInfo(key + " | " + value);
}
// This would print out:
// "key2 | 20"
// "key1 | 30"