Skip to content
A robust Lua collection class based on Laravel collections.
Lua
Branch: master
Clone or download
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
.rockspec
LICENSE
README.md
collections.lua
tests.lua Removed unnecessary library used for debugging May 17, 2017

README.md

Lua Collections

Introduction

Collections are like tables on steroids. They are designed to act as a fluent wrapper when working with structured data, offering the developer convenience for common tasks.

For example, we can use the collect() helper to create a new collection, shuffle the items around, capitalise the words, add something to it, and then return it in a list suitable for pagination.

collect({'Cat', 'Dog', 'Mouse', 'Elephant', 'Hamster', 'Lion'})
        :shuffle()
        :map(function(key, value)
            return key, value:upper()
        end)
        :append('Coyote')
        :split(3)
        :all()

--[[
    {
        {'DOG', 'CAT', 'LION'},
        {'MOUSE', 'HAMSTER', 'ELEPHANT'},
        {'Coyote'}
    }
]]

This collection class was heavily inspired by the collection functionality found in the Laravel Framework for PHP, and implements many of the methods from it, although with some changes to functionality to account for how Lua handles data.

Please note that most collection methods are immutable, meaning they return a modified copy of the original collection. However, some methods modify the original collection by design: append (push), forget (remove), insert, pop, prepend, pull, put (set), shift, splice

Features

  • Pure Lua - no C package to worry about!
  • Wide range of pre-built methods
  • Method chaining reads like a sentence, and is easy to understand
  • Immutable tables (for the most part)
  • Convenience for developing
  • Tests, open source, and used in production software

Installing

Collections can be installed into a Lua project like any other Lua package.

  1. LuaRocks is a package manager for Lua projects, which can install the Collections library.

  2. Include collections.lua in the project's directory, and add Collection = require 'collection' to the file that collections are to be used in.

Creating Collections

A collection can be created with the collect() helper function, which is merely an alias for Collection:new(). It accepts an existing table as an argument to create the collection, or will be empty if none is supplied.

collect({'Hello', 'world'})

Available Methods

This section covers all of the available methods.

- - - -
all append average avg
chunk clone collapse combine
contains convertToIndexed count diff
diffKeys each eachi equals
every except filter first
flatten flip forEach forEachi
forget forPage get groupBy
has implode insert intersect
isAssociative isEmpty isNotEmpty keyBy
keys last map mapWithKeys
max mean median merge
min mode new notAssociative
nth only partition pipe
pluck pop prepend pull
push put random reduce
reject remove replace resort
reverse search set shift
shuffle slice sort sortAsc
sortDesc splice split sum
take tap times toJSON
toString toTable transform union
unique values when where
whereIn whereNotIn zip

Method Listing

all()

Description: Returns all elements from a collection as a table

Returns: table

Example:

collect({'Hello', 'world'}):all()

-- {'Hello', 'world'}

append(value)

Description: Adds an item to the end of a collection.

To add an item to the beginning of a collection, see the prepend method.

Returns: Original Collection

Arguments:

# Type Name Description
1 Any value The value to be added to the end of the collection

Example:

collect({1, 2, 3, 4}):append(5):all()
-- {1, 2, 3, 4, 5}

average([key])

Description: Returns the average value of a list or given key

Returns: number

Arguments:

# Type Name Description
1 string key (Optional) Key to be used in an associative table

Example:

collect({1, 1, 2, 4}):average()
-- 2

collect({ {foo = 10}, {foo = 10}, {foo = 20}, {foo = 40} }):average('foo')
-- 20

avg()

Description: Alias for the Collection:average() method


chunk(count)

Description: Breaks the collection into multiple smaller collections of a given size. Especially useful when dynamically paginating data, or displaying items in a grid. If the count is less than 1, a single empty table will be returned in the collection.

Returns: New Collection

Arguments:

# Type Name Description
1 number count Number of items in each chunk

Example:

collect({1, 2, 3, 4, 5, 6, 7}):chunk(4):all()
--[[
    {
        {1, 2, 3, 4},
        {5, 6, 7}
    }
]]

clone()

Description: Returns a copy of the collection.

Returns: New Collection

Example:

collection = collect({1, 2, 3, 4, 5})

clone = collection:clone():append(6):all()
-- {1, 2, 3, 4, 5, 6}

collection:all()
-- {1, 2, 3, 4, 5}

collapse()

Description: Collapses a collection of tables into a single, flat collection

Returns: New Collection

Example:

collect({ {1, 2, 3}, {4, 5, 6}, {7, 8, 9} }):collapse():all()
-- {1, 2, 3, 4, 5, 6, 7, 8, 9}

combine(values)

Description: Combines the keys of the collection with the values of another table

Returns: New Collection

Arguments:

# Type Name Description
1 table values The values to be combined into the main collection

Example:

collect({'name', 'age'}):combine({'George', 29}):all()
-- {name = 'George', age = 29}

contains(containValue, recursive)

Description: Determines whether the collection contains a given item as a value.

Returns: boolean

Arguments:

# Type Name Description
1 string containValue The value to be searched for
1 function containValue A function to determine a truth test on the value
2 boolean recursive If true, the table will be searched recursively for the value

Example:

collect({'Cat', 'Dog'}):contains('Cat')
-- true

collect({'Cat', 'Dog'}):contains('Walrus')
-- false

collect({evil = 'Cat', good = 'Dog'}):contains('Cat')
-- true

collect({1, 2, 3, 4, 5}):contains(function(key, value)
    return value > 5
end)
-- false

collect({ {'Cat', 'Dog'}, {'Rabbit', 'Mouse'} }):contains('Cat', true)
-- true

assert(collect({ {'Cat', 'Dog'}, {'Rabbit', 'Mouse'} }):contains('Cat')
-- false

convertToIndexed()

Description: Turns an associative table into an indexed one, removing string keys.

Returns: New Collection

Example:

collect({name = 'Liam', language = 'Lua'}):convertToIndexed():all()
-- {'Liam', 'Lua'}

count()

Description: Returns the total number of items in the collection

Returns: number

Example:

collect({'a', 'b', 'c', 'd', 'e'}):count()

-- 5

deal(hands)

Description: Deals the collection into a number of groups in order one at a time - like dealing a hand of cards.

Returns: New Collection

Arguments:

# Type Name Description
1 number hands The number of groups to turn the collection into

Example:

collect({1, 2, 3, 4, 5, 6, 7, 8, 9, 10}):deal(3):all()
--[[
    {
        {1, 4, 7, 10},
        {2, 5, 8},
        {3, 6, 9}
    }
]]

deassociate()

Description: Alias for the Collection:convertToIndexed() method


diff(difference)

Description: Compares a collection against another table based on its values. Returns the values in the original collection that are not present in the given table.

Returns: New Collection

Arguments:

# Type Name Description
1 table difference The value to be represented as a string

Example:

collect({1, 2, 3, 4, 5, 6}):diff({2, 4, 6, 8}):all()
-- {1, 3, 5}

diffKeys(difference)

Description: Compares the collection against another table based on its keys. Returns the key / value pairs in the original collection that are not present in the table.

Returns: New Collection

Arguments:

# Type Name Description
1 table difference The value to be represented as a string

Example:

collect({one = 10, two = 20, three = 30, four = 40, five = 50})
        :diffKeys({two = 2, four = 4, six = 6, eight = 8})
        :all()

-- {one = 10, three = 30, five = 50}

each(callback)

Description: Iterates over the items in the collection and passes each to a callback.

Returns: New Collection

Arguments:

# Type Name Description
1 function callback A function to be executed on each item in the collection. Returning false from this callback will break the loop.

Example:

collect({'a', 'b', 'c'}):each(function(key, value)
    print(key, value)
end)

-- 1    a
-- 2    b
-- 3    c

eachi(callback)

Description: Iterates over the items with a consecutive numeric index in the collection and passes each to a callback.

Returns: New Collection

Arguments:

# Type Name Description
1 function callback A function to be executed on each item in the collection. Returning false from this callback will break the loop.

Example:

collect({'a', 'b', 'c', key = 'Value', [26] = 'z'}):eachi(function(key, value)
    print(key, value)
end)

-- 1    a
-- 2    b
-- 3    c

equals(tbl, ignoreMetaTables, [subtbl])

Description: Compares a table with the internal table of the collection to determine if they are the same.

Returns: boolean

Arguments:

# Type Name Description
1 table tbl The table to compare to the collection.
1 boolean ignoreMetaTables If true, metatables won't be compared.
1 table subtbl (Internal argument) Optionally compare a table other than the collection's internal table.

Example:

collect({'a', 'b', 'c'}):equals({'a', 'b', 'c'})
-- true

collect({'a', 'b', 'c'}):equals({'Liam', 'Taylor', 'Jeffrey'})
-- false

every(callback)

Description: Verify that all elements of the collection pass a truth test

Returns: boolean

Arguments:

# Type Name Description
1 function callback The function that will return a boolean based on a given truth test

Example:

collect({1, 2, 3, 4}):every(function(key, value)
    return value > 2
end)
-- false

except(keys)

Description: Returns all items in the collection except those with specified keys.

For the inverse of except, see the only method.

Returns: New Collection

Arguments:

# Type Name Description
1 table keys The list of keys to be checked against

Example:

collect({productID = 1, price=100, discount = false})
        :except({'price', 'discount'})
        :all()

-- {productID = 1}

filter([callback])

Description: Filters the collection using the given callback, keeping only items that pass a truth test. If no callback is supplied, any "falsy" values will be removed. The items in the resulting collection retain their original keys

Returns: New Collection

Arguments:

# Type Name Description
1 function callback The function that will return a boolean based on a given truth test

Example:

collect({1, 2, 3, 4}):filter(function(key, value)
    return value > 2
end):all()
-- {[3] = 3, [4] = 4}

collect({1, 2, 3, nil, false, '', 0, {}}):filter():all()
-- {1, 2, 3}

first([callback])

Description: Returns the first element in the collection, or if a callback is given, the last element that passes a truth test.

To get the last item in a collection, see the last method.

Returns: Item inside the collection

Arguments:

# Type Name Description
1 function callback The function to determine if the value is true

Example:

collect({1, 2, 3, 4}):first()
-- 1

collect({1, 2, 3, 4}):first(function(key, value)
    return value > 2
end)
-- 3

flatten(depth, [tbl], [currentDepth])

Description: Flattens a multi-dimensional collection into a single dimension.

Returns: New Collection

Arguments:

# Type Name Description
1 number depth The amount of levels deep into subtables the flattening should occur
2 table tbl (Internal argument) Used to pass a sub-table to flatten
3 number currentDepth (Internal argument) The depth of the current iteration

Example:

collect({name = 'Taylor', languages = {'php', 'javascript', 'lua'} }):flatten():all()
-- {'Taylor', 'php', 'javascript', 'lua'}

collect({Apple = {name = 'iPhone 6S', brand = 'Apple'}, Samsung = {name = 'Galaxy S7', brand = 'Samsung'} })
        :flatten(1):values():all()
--[[
    {
        {name = 'iPhone 6S', brand = 'Apple'},
        {name = 'Galaxy S7', brand = 'Samsung'}
    }
]]

flip()

Description: Swaps the collection's keys with their corresponding values.

Returns: New Collection

Example:

collect({name = 'Liam', language = 'Lua'}):flip():all()
-- {Liam = 'name', Lua = 'language'}

forEach()

Description: Alias for the Collection:each() method


forEachi()

Description: Alias for the Collection:eachi() method


forget(key)

Description: Removes an item from the collection by its key.

Returns: Original Collection

Arguments:

# Type Name Description
1 string, number key The key of the value in the collection

Example:

collect({name = 'Liam', language = 'Lua'}):forget('language'):all()
-- {name = 'Liam'}

forPage(pageNumber, perPage)

Description: Returns a collection containing the items that would be present for a given page number.

Returns: New Collection

Arguments:

# Type Name Description
1 number pageNumber The number of the current page
2 number perPage The number of items to show per page

Example:

collect({1, 2, 3, 4, 5, 6, 7, 8, 9}):forPage(2, 3):all()
-- {4, 5, 6}

get(key, [default])

Description: Returns the item of a given key

Returns: Any

Arguments:

# Type Name Description
1 string, number key The value to be represented as a string
2 Any default (Optional) A value to be returned if the value was not found in the collection. If this is a function, it will be executred as a callback

Example:

collect({name = 'Liam', language = 'Lua'}):get('name')
-- 'Liam'

collect({name = 'Liam', language = 'Lua'}):get('foo', 'Default value')
-- 'Default value'

collect({name = 'Liam', language = 'Lua'}):get('foo', function(key)
    return '"' .. key .. '" was not found in the collection'
end)
-- '"foo" was not found in the collection'

groupBy(groupKey)

Description: Groups the collection's items by a given key

Returns: New Collection

Arguments:

# Type Name Description
1 string, number groupKey Key to group the collections by

Example:

collect({
    {name = 'Liam', language = 'Lua'},
    {name = 'Jeffrey', language = 'PHP'},
    {name = 'Taylor', language = 'PHP'}
}):groupBy('language'):all()

--[[
    {
        PHP = {
            {name = 'Jeffrey', language = 'PHP'},
            {name = 'Taylor', language = 'PHP'}
        },
        Lua = {
            {name = 'Liam', language = 'Lua'}
        }
    }
]]

has(key)

Description: Determines if a given key exists in the collection

Returns: boolean

Arguments:

# Type Name Description
1 string, number key The key to be checked for in the collection

Example:

collect({name = 'Liam', language = 'Lua'}):has('language')
-- true

implode(implodedKey, [delimeter = ', '])

Description: Joins the items in a collection into a string

Returns: string

Arguments:

# Type Name Description
1 string, number implodedKey The key to implode the value of. Not required if the table has one dimension (If so, delimeter takes place of this argument in the function call)
2 string delimeter (Optional) String to use as a delimeter between items

Example:

collect({'Lua', 'PHP'}):implode()
-- 'Lua, PHP'

collect({'Lua', 'PHP'}):implode(' | ')
-- 'Lua | PHP'

collect({
    {name = 'Liam', language = 'Lua'},
    {name = 'Jeffrey', language = 'PHP'}
}):implode('language')
-- 'Lua, PHP'

collect({
    {name = 'Liam', language = 'Lua'},
    {name = 'Jeffrey', language = 'PHP'}
}):implode('language', ' | ')
-- 'Lua | PHP'

insert(value, position)

Description: Inserts a value at a given numeric index.

Returns: Original Collection

Arguments:

# Type Name Description
1 Any value The value to be inserted into the collection
2 number position Position in the collection to insert the new value

Example:

collect({'Cat', 'Dog', 'Hamster', 'Walrus'}):insert('Mouse', 3):all()
-- {'Cat', 'Dog', 'Mouse', 'Hamster', 'Walrus'}

intersect(intersection)

Description: Removes any values from the original collection that are not present in the passed table. The resulting collection preserves the original collection's keys.

Returns: New Collection

Arguments:

# Type Name Description
1 table intersection The list of values to intersect with the original collection

Example:

collect({'Desk', 'Sofa', 'Chair'})
        :intersect({'Desk', 'Chair', 'Bookcase'})
        :all()
-- {[1] = 'Desk', [3] = 'Chair'}

isAssociative()

Description: Determines whether the collection is associative, or has ordered string keys.

Returns: boolean

Example:

collect({1, 2, 3, 4, 5}):isAssociative()
-- false

collect({name = 'Liam', language = 'Lua'}):isAssociative()
-- true

isEmpty()

Description: Determines if the collection is empty.

To determine if a collection contains values, see the isNotEmpty method.

Returns: boolean

Example:

collect({'Desk', 'Sofa', 'Chair'}):isEmpty()
-- false

collect():isEmpty()
-- true

isNotEmpty()

Description: Determines if the collection is not empty.

To determine if a collection contains no values, see the isEmpty method.

Returns: boolean

Example:

collect({'Desk', 'Sofa', 'Chair'}):isNotEmpty()
-- true

collect():isNotEmpty()
-- false

keyBy(keyName)

Description: Keys the collection by the given key. If multiple items have the same key, only the last one will appear in the returned collection.

Returns: New Collection

Arguments:

# Type Name Description
1 string, number keyName The key for the collection's value to be identified by
1 function keyName The callback function to determine a key value for the collection

Example:

collect({
    {name = 'Liam', language = 'Lua'},
    {name = 'Jeffrey', language = 'PHP'}
}):keyBy('language'):all()

--[[
    {
        Lua = {name = 'Liam', language = 'Lua'},
        PHP = {name = 'Jeffrey', language = 'PHP'}
    }
]]


collect({
    {name = 'Liam', language = 'Lua'},
    {name = 'Jeffrey', language = 'PHP'}
}):keyBy(function(key, value)
    return value['language']:lower()
end):all()

--[[
    {
        lua = {name = 'Liam', language = 'Lua'},
        php = {name = 'Jeffrey', language = 'PHP'}
    }
]]

keys()

Description: Returns a list of the collection's keys

Returns: New Collection

Example:

collect({name = 'Liam', language = 'Lua'}):keys():all()
-- {'name', 'language'}

last([callback])

Description: Returns the last element in the collection, or if a callback is given, the last element that passes a truth test.

To get the first item in a collection, see the first method.

Returns: Item inside the collection

Arguments:

# Type Name Description
1 function callback The function to determine if the value is true

Example:

collect({1, 2, 3, 4}):last()
-- 4

collect({1, 2, 3, 4}):last(function(key, value)
    return value > 2
end)
-- 4

map(callback)

Description: Iterates through the collection and passes each value to the callback, which can then modify the values, forming a new collection.

Returns: New Collection

Arguments:

# Type Name Description
1 function callback The function to determine the changes to be made to the current iteration's key and value.

Example:

collect({1, 2, 3, 4, 5}):map(function(key, value)
    return key, value * 2
end):all()
-- {2, 4, 6, 8, 10}

mapWithKeys(callback)

Description: Iterates through the the collection and remaps the key and value based on the return of a callback.

Returns: New Collection

Arguments:

# Type Name Description
1 function callback A function that returns a key / value pair

Example:

collect({
    {name = 'Liam', language = 'Lua'},
    {name = 'Jeffrey', language = 'PHP'}
}):mapWithKeys(function(key, value)
    return value['language'], value['name']
end):all()
--[[
    {
        Lua = 'Liam',
        PHP = 'Jeffrey'
    }
]]

max([maxKey])

Description: Returns the maximum value of a set of given values.

For the reverse of max, see the min method.

Returns: number

Arguments:

# Type Name Description
1 string maxKey The key to be evaluated in an associative table

Example:

collect({1, 2, 3, 4, 5}):max()
-- 5

collect({ {foo = 10}, {foo = 20} }):max('foo')
-- 20

mean()

Description: Alias for the Collection:average() method


median([medianKey])

Description: Returns the median value of a set of given values.

Returns: number

Arguments:

# Type Name Description
1 string medianKey The key to be evaluated in an associative table

Example:

collect({1, 1, 2, 4}):median()
-- 1.5

collect({ {foo = 10}, {foo = 10}, {foo = 20}, {foo = 40} }):median('foo')
-- 15

merge(toMerge)

Description: Merges the given table with the original collection. If a string key in the passed table matches a string key in the original collection, the given table's value will overwrite the value in the original collection.

Returns: New Collection

Arguments:

# Type Name Description
1 table toMerge The table to merge into the collection

Example:

collect({'Desk', 'Chair'}):merge({'Bookcase', 'Door'}):all()
-- {'Desk', 'Chair', 'Bookcase', 'Door'}

collect({name = 'Liam', language = 'Lua'})
        :merge({name = 'Taylor', experiencedYears = 14 })
        :all()
-- {name = 'Taylor', language = 'Lua', experiencedYears = 14}

min([minKey])

Description: Returns the minimum value of a set of given values.

For the reverse of min, see the max method.

Returns: number

Arguments:

# Type Name Description
1 string minKey The key to be evaluated in an associative table

Example:

collect({1, 2, 3, 4, 5}):min()
-- 1

collect({ {foo = 10}, {foo = 20} }):min('foo')
-- 10

mode([modeKey])

Description: Returns the mode value of a given key. The value returned is a collection of numbers.

Returns: New Collection

Arguments:

# Type Name Description
1 string modeKey The key to be evaluated in an associative table

Example:

collect({1, 1, 2, 4}):mode():all()
-- {1}

collect({ {foo = 10}, {foo = 10}, {foo = 20}, {foo = 20}, {foo = 40} })
    :mode('foo')
    :all()
-- {10, 20}

new([tbl])

Description: Creates a new collection instance

Returns: Collection New (new)

Arguments:

# Type Name Description
1 table tbl (Optional) Table to use for the collection. If no table is passed, the collection will assume a blank one

Example:

Collection:new({'Hello', 'world'}):all()

-- {'Hello', 'world'}

nth(step, [offset])

Description: -- Creates a new collection consisting of every nth element, with an optional offset.

Returns: New Collection

Arguments:

# Type Name Description
1 number step The nth step to be returned
2 number offset (Optional) A value to offset the nth result by

Example:

collect({'a', 'b', 'c', 'd', 'e', 'f'}):nth(4):all()
-- {'a', 'e'}

collect({'a', 'b', 'c', 'd', 'e', 'f'}):nth(4, 1):all()
-- {'b', 'f'}

only(keys)

Description: Returns only the items in the collection with the specified keys.

For the inverse of only, see the except method.

Returns: New Collection

Arguments:

# Type Name Description
1 table keys The list of keys to be returned from the original collection

Example:

collect({name = 'Taylor', language = 'Lua', experiencedYears = 14})
        :only({'name', 'experiencedYears'})
        :all()
-- {name = 'Taylor', experiencedYears = 14}

partition(callback)

Description: Returns a pair of collections, one containing elements that pass a given truth test, and the other containing elements that fail the given truth test.

Returns: Collection, Collection New (pair)

Arguments:

# Type Name Description
1 function callback A function to determine a truth test on the value

Example:

passed, failed = collect({1, 2, 3, 4, 5, 6}):partition(function(key, value)
    return value < 3
end)

passed:all()
-- {1, 2}
failed:all()
--{3, 4, 5, 6}

pipe(callback)

Description: Passes the collection to the given callback and returns the result.

Returns: The return value of the callback

Arguments:

# Type Name Description
1 function callback The function to execute

Example:

collect({1, 2, 3}):pipe(function(collection)
    return collection:sum()
end)
-- 6

pluck(valueName, [keyName])

Description: Retrives all of the values for a given key.

Returns: New Collection

Arguments:

# Type Name Description
1 string valueName The string key of the value to be plucked from the collection
2 string keyName (Optional) The name of the key to be set as the key for valueName in the resulting collection

Example:

collect({
    {name = 'Liam', language = 'Lua'},
    {name = 'Jeffrey', language = 'PHP'}
}):pluck('name'):all()
-- {'Liam', 'Jeffrey'}

collect({
    {name = 'Liam', language = 'Lua'},
    {name = 'Jeffrey', language = 'PHP'}
}):pluck('name', 'language'):all()
-- {Lua = 'Liam', PHP = 'Jeffrey'}

pop()

Description: Removes and returns the last item from the collection. This method modifies the original collection.

To remove and return the first item in a collection, see the shift method.

Returns: Last item from the collection

Example:

collection = collect({1, 2, 3, 4, 5})

collection:pop()
-- 5

collection:all()
-- {1, 2, 3, 4}

prepend(value)

Description: Adds an item to the beginning of the collection.

To add an item to the end of a collection, see the append method.

Returns: Original Collection

Arguments:

# Type Name Description
1 Any value The value to be added to the beginning of the collection

Example:

collection = collect({1, 2, 3, 4, 5})
collection:prepend(0)
collection:all()
-- {0, 1, 2, 3, 4, 5}

pull(key)

Description: Removes and returns an item from the collection by key. This method modifies the original collection.

Returns: Item from the collection

Arguments:

# Type Name Description
1 string key The key of the value in the collection

Example:

collection = collect({name = 'Liam', language = 'Lua'})

collection:pull('language')
-- 'Lua'

collection:all()
-- {name = 'Liam'}

push()

Description: Alias for the Collection:append() method


put(key, value)

Description: Sets the given key and value in the collection. If a key already exists in the collection, it is overwritten.

Returns: Original Collection

Arguments:

# Type Name Description
1 string, number key The key of the item to be set in the collection
2 Any value The value of the item to be set in the collection

Example:

collect({name = 'Liam', language = 'Lua'})
        :put('count', 12)
        :all()

-- {name = 'Liam', language = 'Lua', count = 12}

random([count = 1], [rep = false])

Description: Returns a random item or as many random unique items from the collection as possible.

Returns: New Collection

Arguments:

# Type Name Description
1 number count The number of items to be returned from the collection.
2 boolean rep Whether items can be repeated in the return value.

Example:

collect({1, 2, 3, 4, 5}):random():first()
-- 4

collect({1, 2, 3, 4, 5}):random(3)
-- {2, 4, 5}

collect({1, 2, 3, 4, 5}):random(10)
-- {2, 4, 5, 1, 3}

collect({1, 2, 3, 4, 5}):random(10, true)
-- {5, 2, 3, 3, 1, 4, 1, 2, 3, 5}

reduce(callback, [default])

Description: Reduces the collection to a single value, passing the result of each iteration into the next.

Returns: Value returned by the callback

Arguments:

# Type Name Description
1 function callback Function to iterate over the collection with
2 Any default The default value for carry, as one is not set before the first iteration

Example:

collect({1, 2, 3}):reduce(function(carry, value)
    return carry + value
end, 4)
-- 10

reject(callback)

Description: Filters the collection using the given fallback. If the callback returns true, the item is removed from the collection.

Returns: New Collection

Arguments:

# Type Name Description
1 function callback The function for a truth test to be executed in

Example:

collect({1, 2, 3, 4}):reject(function(key, value)
    return value > 2
end):all()
-- {1, 2}

remove()

Description: Alias for the Collection:forget() method


replace()

Description: Alias for the Collection:splice() method


resort()

Description: Fixes numerical keys to put them in consecutive order.

Returns: New Collection

Example:

collect({[1] = 'a', [5] = 'b'}):resort():all()
-- {[1] = 'a', [2] = 'b'}

reverse()

Description: Reverses the order of the numerical keys in the collection.

Returns: New Collection

Example:

collect({1, 2, 3, 4, 5}):reverse():all()
-- {5, 4, 3, 2, 1}

search(callback)

Description: Searches the collection for a value and returns the key of the first valid result.

Returns: string, number

Arguments:

# Type Name Description
1 string, number, boolean callback The value to be found in the collection
1 function callback A callback function to perform a truth test

Example:

collect({2, 4, 6, 8}):search(4)
-- 2

collect({2, 4, 6, 8}):search(function(key, value)
    return value > 5
end)
-- 3

set()

Description: Alias for the Collection:put() method


shift()

Description: Removes and returns the first item from the collection. This method modifies the original collection.

To remove and return the last item in a collection, see the pop method.

Returns: First item from the collection

Example:

collection = collect({1, 2, 3, 4, 5})

collection:shift()
-- 1

collection:all()
-- {2, 3, 4, 5}

shuffle()

Description: Randomly shuffles the order of items in the collection.

Returns: New Collection

Example:

collect({1, 2, 3, 4, 5}):shuffle():all()
-- {3, 2, 5, 1, 4}

slice(index, [length])

Description: Returns a slice of the collection at the given numerical index.

Returns: New Collection

Arguments:

# Type Name Description
1 number index The numerical index to start the slice at
2 number length (Optional) The number of items to include in the slice. If this is left blank, the slice will contain all items in the collection with an index higher than the given index

Example:

collect({1, 2, 3, 4, 5, 6, 7, 8, 9, 10}):slice(4):all()
-- {5, 6, 7, 8, 9, 10}

collect({1, 2, 3, 4, 5, 6, 7, 8, 9, 10}):slice(4, 2):all()
-- {5, 6}

sort([callback])

Description: Sorts the items in the collection.

Returns: New Collection

Arguments:

# Type Name Description
1 string, number callback (Optional) The key of an associative table to sort by
1 function callback (Optional) A function to define a custom algorithm to sort by

Example:

collect({5, 3, 1, 2, 4}):sort():all()
-- {1, 2, 3, 4, 5}

collect({
    {application = 'Google +', users = 12},
    {application = 'Facebook', users = 593},
    {application = 'MySpace', users = 62}
}):sort('users'):all()
--[[
    {
        {application = 'Facebook', users = 593},
        {application = 'MySpace', users = 62},
        {application = 'Google +', users = 12}
    }
]]

collect({
    {name = 'Desk', colors = {'Black', 'Mahogany'}},
    {name = 'Chair', colors = {'Black'}},
    {name = 'Bookcase', colors = {'Red', 'Beige', 'Brown'}}
}):sort(function(a, b)
    return #a['colors'] < #b['colors']
end):all()
--[[
    {
        {name = 'Chair', colors = {'Black'}},
        {name = 'Desk', colors = {'Black', 'Mahogany'}},
        {name = 'Bookcase', colors = {'Red', 'Beige', 'Brown'}}
    }
]]

sortAsc()

Description: Alias for the Collection:sort() method.


sortDesc()

Description: sortDesc() accepts the same arguments as the Collection:sort() method, but will sort the collection in the opposite order.


splice(index, [size], [replacements])

Description: Returns a slice of items from the original collection, and optionally also replaces them. This method modifies the original collection

Returns: New Collection

Arguments:

# Type Name Description
1 number index The numerical index to start the slice at
2 number length (Optional) The number of items to include in the slice. If this is left blank, the slice will contain all items in the collection with an index higher than the given index
3 table replacements (Optional) New list of items to replace the ones removed from the collection

Example:

collection1 = collect({1, 2, 3, 4, 5})

collection1:splice(2):all()
-- {3, 4, 5}

collection1:all()
-- {1, 2}



collection2 = collect({1, 2, 3, 4, 5})

collection2:splice(2, 2):all()
-- {3, 4}

collection2:all()
-- {1, 2, 5}



collection3 = collect({1, 2, 3, 4, 5})

collection3:splice(2, 2, {'c', 'd'}):all()
-- {3, 4}

collection3:all()
-- {1, 2, 'c', 'd', 5}

split(count)

Description: Breaks the collection into the given number of groups, provided the original collection has at least that many. Note that the groups will be first-heavy, not evenly distributed.

Returns: New Collection

Arguments:

# Type Name Description
1 number count The number of groups to split the collection into

Example:

collect({1, 2, 3, 4, 5}):split(3):all()
--[[
    {
        {1, 2},
        {3, 4},
        {5}
    }
]]

collect({1, 2, 3, 4, 5, 6, 7, 8, 9, 10}):split(3):all()
--[[
    {
        {1, 2, 3, 4},
        {5, 6, 7, 8},
        {9, 10}
    }
]]

sum([key])

Description: Returns the sum of items in the collection

Returns: number

Arguments:

# Type Name Description
1 string key (Optional) Key to be used in an associative table

Example:

collect({1, 2, 3, 4, 5}):sum()
-- 15

collect({ {pages = 176}, {pages = 1096} }):sum('pages')
-- 1272

take(count)

Description: Returns a collection with the specified number of items.

Returns: New Collection

Arguments:

# Type Name Description
1 number count The number of items to take. If the count is negative, it will take the the specified number of items from the end of the collection

Example:

collect({1, 2, 3, 4, 5}):take(2):all()
-- {1, 2}

collect({1, 2, 3, 4, 5}):take(-2):all()
-- {4, 5}

tap(callback)

Description: Executes the given callback, passing the collection as an argument, without affecting the collection itself.

Returns: New Collection

Arguments:

# Type Name Description
1 function callback The function to be executed

Example:

collect({1, 2, 3, 4, 5}):tap(function(collection)
    print('There are ' .. collection:count() .. ' items in the collection.')
end)

times(count, callback)

Description: Creates a new collection by invoking the callback a given amount of times.

Returns: New Collection

Arguments:

# Type Name Description
1 number count Number of times the callback should be executed
2 function callback The callback function to execute a number of times

Example:

Collection:times(10, function(count)
    return count * 9
end):all()
-- {9, 18, 27, 36, 45, 54, 63, 72, 81, 90}

toJSON()

Description: Returns a JSON string representation of the collection's values

Returns: string

Example:

collect({
    {name = 'Desk', colors = {'Black', 'Mahogany'}},
    {name = 'Chair', colors = {'Black'}},
    {name = 'Bookcase', colors = {'Red', 'Beige', 'Brown'}}
}):toJSON()

-- '[{"name" : 'Desk', "colors" : ['Black', 'Mahogany']},{"name" : 'Chair', "colors" : ['Black']},{"name" : 'Bookcase', "colors" : ['Red', 'Beige', 'Brown']}]'

toString()

Description: Returns a string representation of a Lua table, to be used by the native Lua load() function.

Returns: string

Example:

collect({
    {name = 'Desk', colors = {'Black', 'Mahogany'}},
    {name = 'Chair', colors = {'Black'}},
    {name = 'Bookcase', colors = {'Red', 'Beige', 'Brown'}}
}):toString()

-- '{{name = "Desk", colors = {"Black", "Mahogany"}},{name = "Chair", colors = {"Black"}},{name = "Bookcase", colors = {"Red", "Beige", "Brown"}}}'

toTable()

Description: Returns a reference to the underlying table of the collection.

Returns: table

Example:

collect({1, 2, 3, 4, 5}):toTable()
-- {1, 2, 3, 4, 5}

transform(callback)

Description: Iterates over the collection and calls the given callback with each item in the collection, replacing the values in the collection with the response.

Returns: New Collection

Arguments:

# Type Name Description
1 function callback The function to execute to determine the new value of a collection's current iteration

Example:

collect({1, 2, 3, 4, 5}):transform(function(key, value)
    return value * 2
end):all()
-- {2, 4, 6, 8, 10}

union(tbl)

Description: Adds the given table to the collection. If the given table contains keys that are in the collection, the original collection's values will be kept.

Returns: New Collection

Arguments:

# Type Name Description
1 table tbl The table to add to the collection

Example:

collect({a = 'Hello', b = 'Goodbye'})
        :union({a = 'Howdy', c = 'Pleasure to meet you'})
        :all()
-- {a = 'Hello', b = 'Goodbye', c = 'Pleasure to meet you'}

unique(callback)

Description: Returns all of the unique items in the collection

Returns: New Collection

Arguments:

# Type Name Description
1 string, number callback The key to be checked for uniqueness in an associative table
1 function callback A callback that returns a custom uniqueness value

Example:

collect({1, 1, 2, 2, 3, 4, 2}):unique():all()
-- {3, 4}



collect({
    {name = 'iPhone 6', brand = 'Apple', type = 'phone'},
    {name = 'iPhone 5', brand = 'Apple', type = 'phone'},
    {name = 'Apple Watch', brand = 'Apple', type = 'watch'},
    {name = 'Galaxy S6', brand = 'Samsung', type = 'phone'},
    {name = 'Galaxy Gear', brand = 'Samsung', type = 'watch'},
    {name = 'Pixel', brand = 'Google', type = 'phone'}
}):unique('brand'):all()
--[[
    {
        {name = 'Pixel', brand = 'Google', type = 'phone'}
    }
]]



collect({
    {name = 'iPhone 6', brand = 'Apple', type = 'phone'},
    {name = 'iPhone 5', brand = 'Apple', type = 'phone'},
    {name = 'Apple Watch', brand = 'Apple', type = 'watch'},
    {name = 'Galaxy S6', brand = 'Samsung', type = 'phone'},
    {name = 'Galaxy Gear', brand = 'Samsung', type = 'watch'},
    {name = 'Pixel', brand = 'Google', type = 'phone'}
}):unique(function(key, value)
    return value['brand'] .. value['type']
end):all()
--[[
    {
        {name = 'Galaxy Gear', brand = 'Samsung', type = 'watch'},
        {name = 'Apple Watch', brand = 'Apple', type = 'watch'},
        {name = 'Pixel', brand = 'Google', type = 'phone'},
        {name = 'Galaxy S6', brand = 'Samsung', type = 'phone'}
    }
]]

values()

Description: Alias for the Collection:resort() method


when(condition, callback)

Description: Executes the given callback when a condition is met.

Returns: New Collection

Arguments:

# Type Name Description
1 boolean condition The condition to check, if true, the callback function will be executed
2 function callback The function to be executed when the condition is met

Example:

collect({1, 2, 3}):when(true, function(collection)
    return collection:push(4)
end):all()
-- {1, 2, 3, 4}

where(filterKey, filterValue)

Description: Filters the collection by a given key / value pair.

Returns: New Collection

Arguments:

# Type Name Description
1 string, number filterKey The key in the collection to check
2 string, number filterValue The value in the collection to compare

Example:

collect({
    {name = 'iPhone 6', brand = 'Apple', type = 'phone'},
    {name = 'iPhone 5', brand = 'Apple', type = 'phone'},
    {name = 'Apple Watch', brand = 'Apple', type = 'watch'},
    {name = 'Galaxy S6', brand = 'Samsung', type = 'phone'},
    {name = 'Galaxy Gear', brand = 'Samsung', type = 'watch'}
}):where('type', 'watch'):all()
--[[
    {
        {name = 'Apple Watch', brand = 'Apple', type = 'watch'},
        {name = 'Galaxy Gear', brand = 'Samsung', type = 'watch'}
    }
]]

whereIn(filterKey, filterValues)

Description: Filters the collection by a given key / value pair contained within the given table.

Returns: New Collection

Arguments:

# Type Name Description
1 string, number filterKey The key in the collection to check
2 table filterValues The list of values in the collection to compare

Example:

collect({
    {name = 'iPhone 6', brand = 'Apple', type = 'phone'},
    {name = 'iPhone 5', brand = 'Apple', type = 'phone'},
    {name = 'Apple Watch', brand = 'Apple', type = 'watch'},
    {name = 'Galaxy S6', brand = 'Samsung', type = 'phone'},
    {name = 'Galaxy Gear', brand = 'Samsung', type = 'watch'}
}):whereIn('name', {'iPhone 6', 'iPhone 5', 'Galaxy S6'}):all()
--[[
    {
        {name = 'iPhone 6', brand = 'Apple', type = 'phone'},
        {name = 'iPhone 5', brand = 'Apple', type = 'phone'},
        {name = 'Galaxy S6', brand = 'Samsung', type = 'phone'}
    }
]]

whereNotIn(filterKey, filterValues)

Description: Filters the collection by a given key / value pair not contained within the given table.

Returns: New Collection

Arguments:

# Type Name Description
1 string, number filterKey The key in the collection to check
2 table filterValues The list of values in the collection to compare

Example:

collect({
    {name = 'iPhone 6', brand = 'Apple', type = 'phone'},
    {name = 'iPhone 5', brand = 'Apple', type = 'phone'},
    {name = 'Apple Watch', brand = 'Apple', type = 'watch'},
    {name = 'Galaxy S6', brand = 'Samsung', type = 'phone'},
    {name = 'Galaxy Gear', brand = 'Samsung', type = 'watch'}
}):whereNotIn('name', {'iPhone 6', 'iPhone 5', 'Galaxy S6'}):all()
--[[
    {
        {name = 'Apple Watch', brand = 'Apple', type = 'watch'},
        {name = 'Galaxy Gear', brand = 'Samsung', type = 'watch'}
    }
]]

zip(values)

Description: Merges the value of the given table to the value of the original collection at the same index, if it exists in the original collection.

Returns: New Collection

Arguments:

# Type Name Description
1 table values The list of values to merge into the collection

Example:

collect({'Chair', 'Desk'}):zip({100, 200}):all()
--[[
    {
        {'Chair', 100},
        {'Desk', 200}
    }
]]

collect({'Chair', 'Desk'}):zip({100, 200, 300}):all()
--[[
    {
        {'Chair', 100},
        {'Desk', 200}
    }
]]
You can’t perform that action at this time.