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.

LuaRocks is a package manager for Lua projects, which can install the Collections library.
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} }