# 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]