Class Support.Arr

The Arr class contains helper functions to manipulate arrays.

Usage:

    -- library is an instance of the Stormwind Library
library.arr

Methods

support.arr:concat (...) Concatenates the values of the arrays passed as arguments into a single array.
support.arr:count (list) Counts the number of items in a list.
support.arr:each (list, callback) Iterates over the list values and calls the callback function in the second argument for each of them.
support.arr:filter (list, callback) Filters the list values based on a callback function.
support.arr:freeze (table) Freezes a table, making it immutable.
support.arr:get (list, key, default) Gets a value in an array using the dot notation.
support.arr:hasKey (list, key) Determines whether a table has a key or not.
support.arr:implode (delimiter, list) Combines the elements of a table into a single string, separated by a specified delimiter.
support.arr:inArray (list, value) Determines whether a value is in an array.
support.arr:insertNotInArray (list, value) Inserts a value in an array if it's not in the array yet.
support.arr:isArray (value) Determines whether the value is an array or not.
support.arr:map (list, callback) Iterates over the list values and calls the callback function in the second argument for each of them, storing the results in a new list to be returned.
support.arr:maybeInitialize (list, key, initialValue) Initializes a value in a table if it's not initialized yet.
support.arr:pluck (list, key) Extracts a list of values from a list of objects based on a given key.
support.arr:remove (list, value) Removes a value from an indexed array.
support.arr:safeGet (list, key) Safe get is an internal method, not meant to be used by other classes that will return a value from a list given a key that can be a string or a number.
support.arr:set (list, key, value) Sets a value using arrays dot notation.
support.arr:unpack (list, i, j) Calls the available unpack() method given the running environment.
support.arr:wrap (value) Wraps a value in a table.


Methods

support.arr:concat (...)
Concatenates the values of the arrays passed as arguments into a single array.

This method should be called only for arrays, as it won't consider table keys and will only concatenate their values.

Parameters:

  • ... table The arrays to be concatenated

Returns:

    table The concatenated array

Usage:

    local list1 = {1, 2}
local list2 = {3, 4}
local results = library.arr:concat(list1, list2)
-- results = {1, 2, 3, 4}
support.arr:count (list)
Counts the number of items in a list.

This method solves the problem of counting the number of items in a list that's not an array, so it can't be counted using the # operator.

Parameters:

  • list table The list to be counted

Returns:

    integer The number of items in the list

Usage:

    local list = {a = 'a', b = 'b', c = 'c'}
local count = library.arr:count(list)
-- count = 3
support.arr:each (list, callback)
Iterates over the list values and calls the callback function in the second argument for each of them.

The callback function must be a function that accepts (val) or (val, i) where val is the object in the interaction and i it's index.

This method accepts arrays and tables.

If you need to store the results of the callback, use the Arr:map() method.

Parameters:

  • list table the list to be iterated
  • callback function the function to be called for each item in the list

See also:

Usage:

    local list = {1, 2, 3}
local results = library.arr:map(list, function(val) print(val * 2) end)
support.arr:filter (list, callback)
Filters the list values based on a callback function.

The callback function must be a function that accepts (val) or (val, i) where val is the object in the interaction and i it's index. It must return a boolean value. When it evaluates to true, the value is stored in the results table.

If list is an array, the results will be stored in a new array. If it's an associative array, the results will be stored in a new associative array with the same keys.

Parameters:

  • list table The list to be filtered
  • callback function The function to be called for each item in the list

Returns:

    table The filtered list

Usage:

    local list = {1, 2, 3}
local results = library.arr:filter(list, function(val) return val > 1 end)
-- results = {2, 3}
support.arr:freeze (table)
Freezes a table, making it immutable.

This method is useful when you want to create a constant table that can't be changed after its creation, considering that Lua doesn't have a native way to define constants.

The implementation below was inspired by the following article: https://andrejs-cainikovs.blogspot.com/2009/05/lua-constants.html

Parameters:

  • table table the table to be frozen

Returns:

    table the frozen table

Usage:

    local table = {a = 1}
local frozen = library.arr:freeze(table)
frozen.a = 2
-- error: a is a constant and can't be changed
support.arr:get (list, key, default)
Gets a value in an array using the dot notation. With the dot notation search, it's possible to query a value in a multidimensional array by passing a single string containing keys separated by dot.

Parameters:

  • list table the table containing the value to be retrieved
  • key string a dot notation key to be used in the search
  • default optional any the default value to be returned if the key is not found

Returns:

    any or nil

Usage:

    local list = {a = {b = {c = 1}}}
local value = library.arr:get(list, 'a.b.c')
-- value = 1
support.arr:hasKey (list, key)
Determines whether a table has a key or not.

This method is a simple wrapper around the get() method, checking if the value returned is not nil. It also accepts a dot notation key.

Parameters:

  • list table the table to be checked
  • key string a dot notation key to be used in the search

Returns:

    boolean whether the key is in the table or not

Usage:

    local list = {a = {b = {c = 1}}}
local hasKey = library.arr:hasKey(list, 'a.b.c')
-- hasKey = true
support.arr:implode (delimiter, list)
Combines the elements of a table into a single string, separated by a specified delimiter.

Parameters:

  • delimiter string the delimiter used to separate the elements in the resulting string
  • list table the table containing elements to be combined into a string

Returns:

    string

Usage:

    local list = {1, 2, 3}
local combined = library.arr:implode(', ', list)
-- combined = '1, 2, 3'
support.arr:inArray (list, value)
Determines whether a value is in an array.

If so, returns true and the index, false and 0 otherwise.

Class instances can also be checked in this method, not only primitive types, as long as they implement the __eq method.

Parameters:

  • list table the array to be checked
  • value any the value to be checked

Returns:

  1. boolean whether the value is in the array
  2. integer the index of the value in the array

Usage:

    local list = {'a', 'b', 'c'}
local found, index = library.arr:inArray(list, 'b')
-- found = true, index = 2
support.arr:insertNotInArray (list, value)
Inserts a value in an array if it's not in the array yet.

It's important to mention that this method only works for arrays with numeric indexes. After all, if using string keys, there's no need to check, but only setting and replacing the value.

Class instances can also be passed as the value, not only primitive types, as long as they implement the __eq method.

Parameters:

  • list table the array to have the value inserted
  • value any the value to be inserted

Returns:

    boolean whether the value was inserted or not

Usage:

    local list = {'a', 'b'}
local inserted = library.arr:insertNotInArray(list, 'c')
-- list = {'a', 'b', 'c'}, inserted = true
support.arr:isArray (value)
Determines whether the value is an array or not.

The function checks whether the parameter passed is a table in Lua. If it is, it iterates over the table's key-value pairs, examining each key to determine if it is numeric. If all keys are numeric, indicating an array-like structure, the function returns true; otherwise, it returns false.

This strategy leverages Lua's type checking and table iteration capabilities to ascertain whether the input value qualifies as an array.

Parameters:

  • value any the value to be checked

Returns:

    boolean

Usage:

    local value = {1, 2, 3}
local isArray = library.arr:isArray(value)
-- isArray = true

value = {a = 1, b = 2, c = 3}
isArray = library.arr:isArray(value)
-- isArray = false
support.arr:map (list, callback)
Iterates over the list values and calls the callback function in the second argument for each of them, storing the results in a new list to be returned.

The callback function must be a function that accepts (val) or (val, i) where val is the object in the interaction and i it's index.

This method accepts arrays and tables.

Parameters:

  • list table the list to be iterated
  • callback function the function to be called for each item in the list

Returns:

    table the list with the callback results

Usage:

    local list = {1, 2, 3}
local results = library.arr:map(list, function(val) return val * 2 end)
-- results = {2, 4, 6}
support.arr:maybeInitialize (list, key, initialValue)
Initializes a value in a table if it's not initialized yet.

The key accepts a dot notation key just like get() and set().

Parameters:

  • list table the table to have the value initialized
  • key string the key to be initialized
  • initialValue any the value to be set if the key is not initialized

Usage:

    local list = {}
library.arr:maybeInitialize(list, 'a.b.c', 1)
-- list = {a = {b = {c = 1}}}
support.arr:pluck (list, key)
Extracts a list of values from a list of objects based on a given key.

It's important to mention that nil values won't be returned in the resulted list. Which means: objects that have no property or when their properties are nil, the values won't be returned. That said, a list with n items can return a smaller list.

The key accepts a dot notation key just like get() and set().

Parameters:

  • list table the list of objects to have the values extracted
  • key string the key to be extracted from the objects

Returns:

    table the list of values extracted from the objects

Usage:

    local list = {{a = 1}, {a = 2}, {a = 3}}
local values = library.arr:pluck(list, 'a')
-- values = {1, 2, 3}
support.arr:remove (list, value)
Removes a value from an indexed array.

Tables with non numeric keys won't be affected by this method.

The value must be the value to be removed and not the index.

Parameters:

  • list table the array to have the value removed
  • value any the value to be removed

Returns:

    boolean whether the value was removed or not

Usage:

    local list = {1, 2, 3}
local removed = library.arr:remove(list, 2)
-- list = {1, 3}, removed = true
support.arr:safeGet (list, key)
Safe get is an internal method, not meant to be used by other classes that will return a value from a list given a key that can be a string or a number.

This method is a helper to allow dot notation keys to contain numbers, which was a limitation of the get() method until version 1.10.0.

Parameters:

  • list table the table to have the value retrieved
  • key string or number the key to be used in the search

Returns:

    any or nil the value found in the list
support.arr:set (list, key, value)
Sets a value using arrays dot notation.

It will basically iterate over the keys separated by "." and create the missing indexes, finally setting the last key with the value in the args list.

Parameters:

  • list table the table to have the value set
  • key string the key to be set
  • value any the value to be set

Usage:

    local list = {}
library.arr:set(list, 'a.b.c', 1)
-- list is now {a = {b = {c = 1}}}
support.arr:unpack (list, i, j)
Calls the available unpack() method given the running environment.

This method is an important helper because World of Warcraft supports the unpack() function but not table.unpack(). At the same time, some Lua installations have no unpack() but table.unpack().

Parameters:

  • list table the list to be unpacked
  • i optional integer the initial index
  • j optional integer the final index

Returns:

    any...

Usage:

    local list = {1, 2, 3}
local a, b, c = library.arr:unpack(list)
-- a = 1, b = 2, c = 3
support.arr:wrap (value)
Wraps a value in a table.

This method is very useful for methods that accept objects and arrays on the same variable. That way, they don't need to check the type, but wrap it and work with an array.

If the value provided is a table, this method won't result in a bidimensional table, but will return the table itself.

Parameters:

  • value any the value to be wrapped

Returns:

    table

Usage:

    local value = 1
local wrapped = library.arr:wrap(value)
-- wrapped = {1}
generated by LDoc 1.5.0 Last updated 2024-09-11 16:27:53