sequences

Overview

Module containing methods shared across sequence implementations.

Summary

`first`	Returns the first element of the sequence, or nil if the sequence is empty.
`last`	Returns the last element of the sequence, or nil if the sequence is emtpty.
`removeAll`	Calls sequence:removeElement(e) for e in iter(elements).
`removeElement`	Removes the first instance of element from sequence and returns it, or if not found, nil.
`shuffle`	Permutes the input sequence in place, using the optionally supplied rng (by default math.random).
`sort`	Sorts the sequence in place using the built-in table.sort function and the ordering specified (default is increasing order).
`swap`	Exchanges the elements stored in sequence at the two supplied indices.
`toString`	Returns a string representation of sequence.

Detail

`sequences.first(sequence)`

Returns the first element of the sequence, or nil if the sequence is empty.

`sequences.last(sequence)`

Returns the last element of the sequence, or nil if the sequence is emtpty.

`sequences.removeAll(sequence, elements)`

Calls sequence:removeElement(e) for e in iter(elements).

`sequences.removeElement(sequence, element)`

Removes the first instance of element from sequence and returns it, or if not found, nil.

`sequences.shuffle(sequence [,rng])`

Permutes the input sequence in place, using the optionally supplied rng (by default math.random).

rng can be any function which can takes two integer arguments a,b and returns a random integer in the range [a..b] (inclusive on both sides).

The algorithm runs in linear time and generates all permutations with equal probability, assuming the rng is perfectly uniform. It is implemented using an algorithm proposed by Knuth, see http://en.wikipedia.org/wiki/Shuffle#Shuffling_algorithms

`Sequence:sort([orderFn])`

Sorts the sequence in place using the built-in table.sort function and the ordering specified (default is increasing order).

If seq is a Vector or Tuple, no auxilliary table is created for the sort. If seq is any other collection, a copy of seq is created, sorted, and the results copied back to seq.

`sequences.swap(sequence, index1, index2)`

Exchanges the elements stored in sequence at the two supplied indices.

`sequences.toString(sequence)`

Returns a string representation of sequence.

This method is used for the __tostring metamethod of Vector, SkipVector, QueueVector, and LinkedList. Example:

> print(SkipVector:make(1,2,3,4,5))
[1, 2, 3, 4, 5]