Class enumerable

A collection library to simplify sequential table operations

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

Info:

  • Author: Billiam

Functions

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

Tables

enumerable._data Internal collection data

Local Functions

enumerable.isCallable (f) Whether the item passed in may be called as a function
enumerable.isSequence (t) Tests tables for numeric keys with no gaps


Functions

Methods
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})
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
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
Enumerable:collect ()

See also:

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'}
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:

    int

Usage:

      collection = Enumerable.create({1,2,3})
  collection:count()
  -> 3
  collection:count(function(value, index) return value % 2 == 0 end)
  -> 1
Enumerable:data ()
Return the unwrapped collection data.

Returns:

    table

Usage:

    collectionData = collection:to_table()
Enumerable:detect ()

See also:

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)
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
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
Enumerable:find_all ()

See also:

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
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:

    table or *

See also:

Usage:

      collection = Enumerable.create({1,2,3,4})
  collection:first()
  -> 1
  collection:first(3)
  -> {1,2,3}
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:

    table

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}
Enumerable:inject ()

See also:

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:

    table

See also:

Usage:

      collection = Enumerable.create({1,2,3,4})
  collection:last()
  -> 4
  collection:last(3)
  -> {2, 3, 4}
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}
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'
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'
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:

  1. Lowest value
  2. 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)
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:

  1. enumerable Collection containing items which returned true
  2. enumerable Collection containing items which returned false

Usage:

      numbers = Enumerable.create({1,2,3,4,5,6})
 even, 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}
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}
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}
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
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}
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}
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}
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}
Enumerable:to_table ()
Create a shallow copy of the unwrapped collection data.

Returns:

    table

Usage:

    clonedData = collection:to_table()
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}

Tables

enumerable._data
Internal collection data

Local Functions

Methods
enumerable.isCallable (f)
Whether the item passed in may be called as a function

Parameters:

  • f Item to test for callability

Returns:

    boolean True if passed in item may be called, false otherwise
enumerable.isSequence (t)
Tests tables for numeric keys with no gaps

Parameters:

Returns:

    boolean True if table is sequence-like, false otherwise
generated by LDoc 1.4.3 Last updated 2015-01-31 07:21:17