Vendor.Enumerable classmod

A collection library to simplify sequential table operations

local Enumerable = require('__stdlib__/stdlib/enumerable')
Enumerable.create({1,2,3})

  • Author: Billiam

Tables

Vendor.Enumerable._data Internal collection data

Methods

Vendor.Enumerable:all(callback) Returns true if callback returns truthy for all elements in the collection.
Vendor.Enumerable:any(callback) Returns true if callback returns truthy for any element in the collection.
Vendor.Enumerable:collect()
Vendor.Enumerable:concat(other) Append the contents of one table onto the end of the existing enumerable.
Vendor.Enumerable:count(callback) Return the number of items in the collection.
Vendor.Enumerable:create(collection) Enumerable constructor.
Vendor.Enumerable:data() Return the unwrapped collection data.
Vendor.Enumerable:detect()
Vendor.Enumerable:each(callback) Pass all elements in the collection to a callback.
Vendor.Enumerable:empty() Whether the collection has no elements.
Vendor.Enumerable:find(callback) Returns the first element in the collection where the callback returns true.
Vendor.Enumerable:find_all()
Vendor.Enumerable:find_index(callback) Find the position of the first item in collection for which the callback returns true.
Vendor.Enumerable:first(n) Return the first element or elements in the collection.
Vendor.Enumerable:group_by(callback) Groups elements into collections based on the result of the provided callback.
Vendor.Enumerable:inject()
Vendor.Enumerable:last(n) Return the last element or elements in the collection.
Vendor.Enumerable:map(callback) Pass all elements in collection to a callback.
Vendor.Enumerable:max(callback) Find the highest value in the enumerable instance.
Vendor.Enumerable:min(callback) Find the lowest value in the enumerable instance.
Vendor.Enumerable:minmax(callback) Find the highest and lowest values in the enumerable.
Vendor.Enumerable:partition(callback) Split enumerable into two groups, based on the true or false result of the callback.
Vendor.Enumerable:pop() Remove and return the last item from the collection.
Vendor.Enumerable:push(...) Add one or more items to the enumerable.
Vendor.Enumerable:reduce(initial, callback) Combine elements of enumerable by passing all items to a callback.
Vendor.Enumerable:reject(callback) Create a new collection with elements which the callback returns false.
Vendor.Enumerable:select(callback) Create a new collection with elements which the callback returns true.
Vendor.Enumerable:shift() Remove and return the first item from the collection.
Vendor.Enumerable:sort(callback) Sort the enumerable by optional callback in place.
Vendor.Enumerable:to_table() Create a shallow copy of the unwrapped collection data.
Vendor.Enumerable:unshift(...) Insert one or more items into the beginning of the collection.

Tables

# Vendor.Enumerable._data

Internal collection data

Methods

# Vendor.Enumerable:all(callback)

Returns true if callback returns truthy for all elements in the collection.

Parameters:
  • callback : (callable)
Returns:
  • (bool)
Usage:
items = Enumerable.create({10, 20, 30})
items:all(function(value, index) return value > 5 end)
-> true
items:all(function(value, index) return value < 25 end)
-> false
# Vendor.Enumerable:any(callback)

Returns true if callback returns truthy for any element in the collection.

Parameters:
  • callback : (callable)
Returns:
  • (bool)
Usage:
items = Enumerable.create({10, 20, 30})
items:any(function(value, index) return value > 25 end)
-> true
items:any(function(value, index) return value > 30 end)
-> false
# Vendor.Enumerable:collect()
See also:
# Vendor.Enumerable:concat(other)

Append the contents of one table onto the end of the existing enumerable.

Parameters:
  • other : (table) Table with content to append to enumerable
Returns:
  • (enumerable) The enumerable instance
Usage:
pets = Enumerable:create({'dog', 'cat'})
pets:concat({'turtle', 'wizard'})
-> pets now contains {'dog', 'cat', 'turtle', 'wizard'}
# Vendor.Enumerable:count(callback)

Return the number of items in the collection.

If a callback is given, count will return the number of elements for which the callback returns true

Parameters:
  • callback : (callable) Callback used to determine whether element should be counted
Returns: Usage:
collection = Enumerable.create({1,2,3})
collection:count()
-> 3
collection:count(function(value, index) return value % 2 == 0 end)
-> 1
# Vendor.Enumerable:create(collection)

Enumerable constructor.

If no collection is provided, a new empty table will be generated.

Parameters:
  • collection : (optional table) Sequential table to wrap
Returns:
  • (enumerable) A new collection instance
Raises
‘Enumerable data must be a sequence’ if given a non-sequential table Usage:
collection = Enumerable.create({123})
# Vendor.Enumerable:data()

Return the unwrapped collection data.

Returns: Usage:
collectionData = collection:to_table()
# Vendor.Enumerable:detect()
See also:
# Vendor.Enumerable:each(callback)

Pass all elements in the collection to a callback.

Parameters:
  • callback : (callable)
Returns:
  • (enumerable) The collection instance
Usage:
collection:each(function(value, index) ... end)
# Vendor.Enumerable:empty()

Whether the collection has no elements.

Returns:
  • (bool)
Usage:
collection = Enumerable.create()
 if collection:empty() then
   print('Collection is empty')
 end
 -> Collection is empty
# Vendor.Enumerable:find(callback)

Returns the first element in the collection where the callback returns true.

Parameters:
  • callback : (callable)
Returns:
  • Matching item
Usage:
numbers = Enumerable.create({20, 30, 40})
numbers:find(function(value, index) return value > 25 end)
-> 30
# Vendor.Enumerable:find_all()
See also:
# Vendor.Enumerable:find_index(callback)

Find the position of the first item in collection for which the callback returns true.

Parameters:
  • callback : (callable)
Returns:
  • (int) the position of the matched element
Usage:
collection = Collection.create({0, 1, 2, 3, 4})
collection:findIndex(function(value, index) return value > 2 end)
-> 4
# Vendor.Enumerable:first(n)

Return the first element or elements in the collection.

Parameters:
  • n : (optional int) Number of elements to return. If absent, the first item will be returned.
Returns: See also: Usage:
collection = Enumerable.create({1,2,3,4})
collection:first()
-> 1
collection:first(3)
-> {1,2,3}
# Vendor.Enumerable:group_by(callback)

Groups elements into collections based on the result of the provided callback.

Resulting table will have keys matching the returned value of the callback, and values as a table of elements which returned that value.

Parameters:
  • callback : (callable)
Returns: Usage:
numbers = Enumerable.create({1,2,3,4,5,6})
result = Enumerable.group_by(function(value, index) return value % 3 end)
result[0]
-> Enumerable containing {3, 6}
result[1]
-> Enumerable containing {2, 5}
result[2]
-> Enumerable containing {1, 4}
# Vendor.Enumerable:inject()
See also:
# Vendor.Enumerable:last(n)

Return the last element or elements in the collection.

Parameters:
  • n : (optional int) Number of elements to return. If absent, the last item will be returned.
Returns: See also: Usage:
collection = Enumerable.create({1,2,3,4})
collection:last()
-> 4
collection:last(3)
-> {2, 3, 4}
# Vendor.Enumerable:map(callback)

Pass all elements in collection to a callback.

returns a new enumerable instance containing values returned by the callback.

Parameters:
  • callback : (callable)
Returns:
  • (enumerable) New enumerable instance
Usage:
collection = Enumerable.create({1, 2, 3})
collection:map(function(value, index) return value* 2 end)
> Enumerable containing {2, 4, 6}
# Vendor.Enumerable:max(callback)

Find the highest value in the enumerable instance.

If a callback is provided, the return value will be used to determine the highest value.

Parameters:
  • callback : (optional callable)
Returns:
  • Highest value
Usage:
strings = Enumerable.create({'aaaaaa', 'bbb', 'c'})
strings:max()
> 'c'
strings:max(function(value) return #value end)
> 'aaaaa'
# Vendor.Enumerable:min(callback)

Find the lowest value in the enumerable instance.

If a callback is provided, the return value will be used to determine the lowest value.

Parameters:
  • callback : (optional callable)
Returns:
  • Lowest value
Usage:
strings = Enumerable.create({'aaaaaa', 'bbb', 'c'})
strings:min()
> 'aaaaa'
strings:min(function(value) return #value end)
> 'c'
# Vendor.Enumerable:minmax(callback)

Find the highest and lowest values in the enumerable.

If a callback is provided, the return value will be used to determine the highest and lowest values.

Parameters:
  • callback : (optional callable)
Returns:
  • Lowest value
  • Highest value
Usage:
numbers = Enumerable.create({6,3,1,5,2,4})
lowest, highest = numbers:minmax()
> (1,6)
strings:max(function(value) return 10 - value end)
> (6, 1)
# Vendor.Enumerable:partition(callback)

Split enumerable into two groups, based on the true or false result of the callback.

Aliases: find_all, detect

Parameters:
  • callback : (callable)
Returns:
  • (enumerable) Collection containing items which returned true
  • (enumerable) Collection containing items which returned false
Usage:
numbers = Enumerable.create({1,2,3,4,5,6})
ven, odd = Enumerable:partition(function(value, index) return value % 2 == 1 end)
> even is a collection containing {2, 4, 6}
> odd is a collection containing {1, 3, 5}
# Vendor.Enumerable:pop()

Remove and return the last item from the collection.

Returns:
  • (enumerable) The collection instance
Usage:
items = Enumerable.create({1,2,3})
items:pop()
> returns 3
> items now contains {1,2}
# Vendor.Enumerable:push(...)

Add one or more items to the enumerable.

Parameters:
  • ... : Items to append
Returns:
  • (enumerable) The collection instance
Usage:
items = Enumerable.create({1,2,3})
items:push(4, 5)
> items contains {1,2,3,4,5}
# Vendor.Enumerable:reduce(initial, callback)

Combine elements of enumerable by passing all items to a callback.

Values returned by the callback will be used as the accumulator value for subsequent callbacks.

Parameters:
  • initial : (optional int) Initial value for accumulator
  • callback : (callable)
Returns:
  • Accumulator value
Usage:
numbers = Enumerable.create({1,2,3})
numbers:reduce(function(accumulator, value) return (accumulator or 0) + value end)
-> 6
numbers:reduce(20, function(accumulator, value) return accumulator + value end)
-> 26
# Vendor.Enumerable:reject(callback)

Create a new collection with elements which the callback returns false.

Parameters:
  • callback : (callable)
Returns:
  • (enumerable) New collection instance
Usage:
items = Enumerable.create({1,2,3,4,5,6})
odd = Enumerable:reject(function(value, index) return value % 2 == 0 end)
-> Enumerable containing {1,3,5}
# Vendor.Enumerable:select(callback)

Create a new collection with elements which the callback returns true.

Parameters:
  • callback : (callable)
Returns:
  • (enumerable) New collection instance
Usage:
items = Enumerable.create({1,2,3,4,5,6})
even = Enumerable:select(function(value, index) return value % 2 == 0 end)
-> Enumerable containing {2,4,6}
# Vendor.Enumerable:shift()

Remove and return the first item from the collection.

Returns:
  • (enumerable) The collection instance
Usage:
items = Enumerable.create({1,2,3})
items:shift()
> returns 1
> items now contains {2,3}
# Vendor.Enumerable:sort(callback)

Sort the enumerable by optional callback in place.

If a callback is not provided, data will be sorted in ascending order. If callback is provided, it will be passed two table elements, and should return true if the first element should appear first, otherwise false. See also: table.sort documentation

Parameters:
  • callback : (optional callable) sort method
Returns:
  • (enumerable) The collection instance
Usage:
numbers = Enumerable.create({2,1,3})
numbers:sort()
-> numbers now contains {1,2,3}
numbers:sort(function(a, b) return b < a end)
-> numbers now contains {3,2,1}
# Vendor.Enumerable:to_table()

Create a shallow copy of the unwrapped collection data.

Returns: Usage:
clonedData = collection:to_table()
# Vendor.Enumerable:unshift(...)

Insert one or more items into the beginning of the collection.

Parameters:
  • ... : Elements to insert
Returns:
  • (enumerable) The collection instance
Usage:
items = Enumerable.create({4,5,6})
items:unshift(1,2,3)
-> Items now contains {1,2,3,4,5,6}