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

  1. a random key in the Dictionary
  2. 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

  1. whether the get was successful
  2. 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

  1. the key
  2. 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

Posts Quoted:
Reply
Clear All Quotes