API/Dictionary
Dictionary.From(obj)
Return a Dictionary by trying to convert an object to one through some means.
Passing in nil will result in an empty Dictionary
Passing in a Dictionary will return the same Dictionary
Passing in a table will call Dictionary.WrapTable
Any other object will result in an error.
Parameters
- obj
Return value
an Enumerable
Usage
Dictionary.From(nil):ToString() == "Dictionary[]"
Dictionary.From(Dictionary.New()):ToString() == "Dictionary[]"
Dictionary.From({ 'a', 'b', 'c' }):ToString() == 'Dictionary[1: "a", 2: "b", 3: "c"]'
Dictionary.From({ a = 1, b = 2, c = 3 }):ToString() == 'Dictionary["a": 1, "b": 2, "c": 3]'
Dictionary.IsDictionary(obj)
Return whether the provided object is a Dictionary
Parameters
- obj
- the object to check
Return value
whether the object inherits from or is a Dictionary
Dictionary.New(dict, comparison_selector)
Construct and return a new Dictionary
Parameters
- dict
- optional: a Dictionary or lua table to populate the new dictionary with
- comparison_selector
- optional: a function to generate a unique key per element
Usage
Dictionary.New()
Dictionary.New({ a = 1, b = 2 })
Dictionary.New({ a = 1, b = 2 }, string.upper)
Dictionary.New(nil, string.upper)
Dictionary.WrapTable(t)
Wrap a lua table such that there is parity between the passed-in table and the Dictionary.
Unlike other tables, this will not gracefully handle nils.
Parameters
- t
- the table to wrap around
Return value
a Dictionary
Usage
local dict = Dictionary.WrapTable({ alpha = 1, bravo = 2 })
Dictionary.prototype:Add(key, value)
Add the specific key and value to the Dictionary.
This will error if an element with the same key already exists in the Dictionary.
To avoid erroring, use :Set(key, value) instead.
Parameters
- key
- the key of the element to add
- value
- the value of the element to add
Usage
dict:Add("key", "value")
Dictionary.prototype:Clear()
Clear all elements from the Dictionary
Usage
dict:Clear()
Dictionary.prototype:Clone()
Make a shallow clone of the Set.
Usage
local other = dict:Clone()
Dictionary.prototype:ContainsKey(key)
Return whether a given key is present in the Dictionary
Parameters
- key
- the key to check for
Return value
a boolean
Usage
local found = dict:ContainsKey("key")
Dictionary.prototype:ContainsValue(value)
Return whether a given value is present in the Dictionary
Parameters
- value
- the value to check for
Return value
a boolean
Usage
local found = dict:ContainsValue("value")
Dictionary.prototype:ConvertToReadOnly()
Make the Set read-only, preventing any further modifications.
There is no way to convert a Set back to being modifiable.
Return value
the same Set that was made read-only
Usage
set:ConvertToReadOnly()
Dictionary.prototype:ForEachByPair(action)
Immediately performs an action on each element in the dictionary.
If the action returns false, that will act as a break and prevent any more execution on the sequence.
Parameters
- action
- a function that takes the key, value, and the 1-based index of the element.
Usage
dict:ForEachByPair(function(key, value, index) end)
Dictionary.prototype:Get(key)
Get the specific value in the Dictionary given the requested key.
This will error if the key is not in the Dictionary.
Parameters
- key
- the key of the element to get
Return value
the value requested
Usage
local value = dict:Get("key")
Dictionary.prototype:GetEnumerator()
Return an enumerator for the Dictionary that returns the keys of the dictionary
Dictionary.prototype:GetOrDefault(key, default)
Get the specific value or a default value in the Dictionary given the requested key.
This will return the default value if not found.
Parameters
- key
- the key of the element to get
- default
- the default value to return if the key is not found.
Return value
the value requested or the default value
Usage
local value = dict:GetOrDefault("key", 0)
Dictionary.prototype:IsReadOnly()
Return whether the Set is read-only, and thus cannot have modifications made to it.
Return value
a boolean
Usage
local read_only = set:IsReadOnly()
Dictionary.prototype:Iterate()
Return a lua iterator that returns the index, key, and value of each element and can be used in for loops.
Usage
for index, key, value in Dictionary.New({ a = 1, b = 2 }):Iterate() do end
Dictionary.prototype:Keys()
Return an Enumerable of all the keys in the Dictionary.
This may not return in a known order.
Return value
an Enumerable
Usage
local keys = dict:Keys()
Dictionary.prototype:Merge(other)
Merge another dictionary onto the current Dictionary.
Parameters
- other
- a Dictionary to Merge onto the current
Usage
Dictionary.From({ alpha = 1, bravo = 2 }):Merge({ bravo = 3, charlie = 4 }) -- Dictionary["alpha": 1, "bravo": 3, "charlie": 4]
Dictionary.prototype:PickAndRemoveRandom()
Randomly pick a random element in the Dictionary, remove it, and return the key and value.
This will error if the Set is empty.
Return values
- a random key in the Dictionary
- a random value in the Dictionary
Usage
local key, value = dict:PickAndRemoveRandom()
Dictionary.prototype:Remove(key)
Removes the element with the provided key from the Dictionary
Parameters
- key
- the key to remove
Return value
whether the element was removed
Usage
local removed = dict:Remove("key")
Dictionary.prototype:RemoveWhere(predicate)
Remove all elements which match a given predicate
Parameters
- predicate
- a function which is passed each key and value and should return true to remove, false to keep
Return value
the number of elements removed
Usage
local num = dict:RemoveWhere(function(k, v) return v % 2 == 0 end)
Dictionary.prototype:SelectByPair(selector)
Project each element of the sequence to a new element.
Parameters
- selector
- the transform function which takes the key, value, and the 1-based index
Return value
an Enumerable
Usage
dict:SelectByPair(function(key, value, index) return key.."="..value end)
Dictionary.prototype:Set(key, value)
Set the specific key and value to the Dictionary.
If overriding an existing value, the key will not change or be overridden.
Parameters
- key
- the key of the element to set
- value
- the value of the element to set
Usage
dict:Set("key", "value")
Dictionary.prototype:SetContract(contract)
Set a contract that will be verified against any existing elements and any added elements or changed values.
This is handy for if you want to verify that all keys are strings and all values are positive integers or something like that.
This will call :VerifyContract()
Parameters
- contract
- a function that is passed the key and value and should return whether the pair is valid.
Usage
dict:SetContract(function(k, v) return type(k) == "string" and type(v) == "number" end)
Dictionary.prototype:ToKeyValuePairs()
Return an Enumerable of KeyValuePair representing all the elements of the current Dictionary.
Return value
an Enumerable
Usage
local kvps = dict:ToKeyValuePairs()
Dictionary.prototype:ToTable(kind)
Convert the Dictionary to a simple lua table.
This will be missing values if nil is used.
Parameters
- kind
- "set" to return a table where all values are true, "list" to return a list-like table, or nil to return a standard dictionary-like table
Usage
Dictionary.New({ hey = "there" }):ToTable()["hey"] == "there"
Dictionary.New({ hey = "there" }):ToTable("list")[1] == "hey"
Dictionary.New({ hey = "there" }):ToTable("set")["hey"] == true
Dictionary.prototype:TryGetValue(key)
Try to get the specific value in the Dictionary given the requested key.
Parameters
- key
- the key of the element to get
Return values
- whether the get was successful
- the value requested
Usage
local success, value = dict:TryGetValue("key")
Dictionary.prototype:Values()
Return an Enumerable of all the values in the Dictionary.
This may not return in a known order.
Return value
an Enumerable
Usage
local values = dict:Values()
Dictionary.prototype:VerifyContract()
Verify that the contract for this Dictionary is valid for all elements in the dictionary.
If there is no contract, this does nothing.
Usage
dict:VerifyContract()
Enumerable.prototype:ToDictionary(key_selector, value_selector, comparison_selector)
Create and return a new Dictionary from the current Enumerable based on the provided selectors.
Parameters
- key_selector
- a function to get the key of the dictionary from an element
- value_selector
- optional: a function to get the value of the dictionary from an element
- comparison_selector
- optional: a function to generate a unique key per element
Return value
a Dictionary
Usage
Enumerable.From({ "Alpha", "Bravo", "Charlie" }):ToDictionary(function(x) return x:sub(1, 1) end)
Enumerable.From({ "Alpha", "Bravo", "Charlie" }):ToDictionary(function(x) return x:sub(1, 1) end, string.lower)
Enumerable.From({ "Alpha", "Bravo", "Charlie" }):ToDictionary(function(x) return x:sub(1, 1) end, nil, string.upper)
KeyValuePair.prototype:Key()
Return the key of the current KeyValuePair
Return value
a value
Usage
local key = kvp:Key()
KeyValuePair.prototype:KeyAndValue()
Return the key and value of the current KeyValuePair
Return values
- the key
- the value
Usage
local key, value = kvp:KeyAndValue()
KeyValuePair.prototype:Value()
Return the value of the current KeyValuePair
Return value
a value
Usage
local value = kvp:Value()
Comments