# Module `pl.seq`

Manipulating iterators as sequences.

See The Guide

Dependencies: pl.utils, pl.types, debug

## Functions

matching (s) | given a string, return a function(y) which matches y against the string.
list (t) | sequence adaptor for a table.
keys (t) | return the keys of the table.
range (start, finish) | create an iterator over a numerical range.
minmax (iter) | return the minimum and the maximum value of the sequence.
sum (iter, fn) | return the sum and element count of the sequence.
copy (iter) | create a table from the sequence.
copy2 (iter, i1, i2) | create a table of pairs from the double-valued sequence.
copy_tuples (iter) | create a table of 'tuples' from a multi-valued sequence.
random (n, l, u) | return an iterator of random numbers.
sort (iter, comp) | return an iterator to the sorted elements of a sequence.
zip (iter1, iter2) | return an iterator which returns elements of two sequences.
count_map (iter) | Makes a table where the key/values are the values and value counts of the sequence.
printall (iter, sep, nfields, fmt) | print out a sequence iter with a separator.
map (fn, iter, arg) | return a sequence where every element of a sequence has been transformed by a function.
filter (iter, pred, arg) | filter a sequence using a predicate function.
reduce (fn, iter, initval) | 'reduce' a sequence using a binary function.
take (iter, n) | take the first n values from the sequence.
skip (iter, n) | skip the first n values of a sequence
enum (iter) | a sequence with a sequence count and the original value.
mapmethod (iter, name, arg1, arg2) | map using a named method over a sequence.
last (iter) | a sequence of (last,current) values from another sequence.
foreach (iter, fn) | call the function on each element of the sequence.
lines (f, ...) | create a wrapped iterator over all lines in the file.

## Functions

matching (s)
  given a string, return a function(y) which matches y against the string.

  ### Parameters:

  - s a string
list (t)
  sequence adaptor for a table. Note that if any generic function is passed a table, it will automatically use seq.list()

  ### Parameters:

  - t a list-like table

  ### Usage:

  -     sum(list(t)) is the sum of all elements of t

  -     for x in list(t) do...end

keys (t)
  return the keys of the table.

  ### Parameters:

  - t an arbitrary table

  ### Returns:

  iterator over keys
range (start, finish)
  create an iterator over a numerical range. Like the standard Python function xrange.

  ### Parameters:

  - start a number
  - finish a number greater than start
minmax (iter)
  return the minimum and the maximum value of the sequence.

  ### Parameters:

  - iter a sequence

  ### Returns:

  1. minimum value
  2. maximum value
sum (iter, fn)
  return the sum and element count of the sequence.

  ### Parameters:

  - iter a sequence
  - fn an optional function to apply to the values
copy (iter)
  create a table from the sequence. (This will make the result a List.)

  ### Parameters:

  - iter a sequence

  ### Returns:

  a List

  ### Usage:

  -     copy(list(ls)) is equal to ls

  -     copy(list {1,2,3}) == List{1,2,3}

copy2 (iter, i1, i2)
  create a table of pairs from the double-valued sequence.

  ### Parameters:

  - iter a double-valued sequence
  - i1 used to capture extra iterator values
  - i2 as with pairs & ipairs

  ### Returns:

  a list-like table

  ### Usage:

      copy2(ipairs{10,20,30}) == {{1,10},{2,20},{3,30}}

copy_tuples (iter)
  create a table of 'tuples' from a multi-valued sequence. A generalization of copy2 above

  ### Parameters:

  - iter a multiple-valued sequence

  ### Returns:

  a list-like table
random (n, l, u)
  return an iterator of random numbers.

  ### Parameters:

  - n the length of the sequence
  - l same as the first optional argument to math.random
  - u same as the second optional argument to math.random

  ### Returns:

  a sequence
sort (iter, comp)
  return an iterator to the sorted elements of a sequence.

  ### Parameters:

  - iter a sequence
  - comp an optional comparison function (comp(x,y) is true if x < y)
zip (iter1, iter2)
  return an iterator which returns elements of two sequences.

  ### Parameters:

  - iter1 a sequence
  - iter2 a sequence

  ### Usage:

      for x,y in seq.zip(ls1,ls2) do....end

count_map (iter)
  Makes a table where the key/values are the values and value counts of the sequence. This version works with 'hashable' values like strings and numbers. pl.tablex.count_map is more general.

  ### Parameters:

  - iter a sequence

  ### Returns:

  1. a map-like table
  2. a table

  ### See also:

  pl.tablex.count_map
printall (iter, sep, nfields, fmt)
  print out a sequence iter with a separator.

  ### Parameters:

  - iter a sequence
  - sep the separator (default space)
  - nfields maximum number of values per line (default 7)
  - fmt optional format function for each value
map (fn, iter, arg)
  return a sequence where every element of a sequence has been transformed by a function. If you don't supply an argument, then the function will receive both values of a double-valued sequence, otherwise behaves rather like tablex.map.

  ### Parameters:

  - fn a function to apply to elements; may take two arguments
  - iter a sequence of one or two values
  - arg optional argument to pass to function.
filter (iter, pred, arg)
  filter a sequence using a predicate function.

  ### Parameters:

  - iter a sequence of one or two values
  - pred a boolean function; may take two arguments
  - arg optional argument to pass to function.
reduce (fn, iter, initval)
  'reduce' a sequence using a binary function.

  ### Parameters:

  - fn function a function of two arguments
  - iter a sequence
  - initval optional initial value

  ### Usage:

  -     seq.reduce(operator.add,seq.list{1,2,3,4}) == 10

  -     seq.reduce('-',{1,2,3,4,5}) == -13

take (iter, n)
  take the first n values from the sequence.

  ### Parameters:

  - iter a sequence of one or two values
  - n number of items to take

  ### Returns:

  a sequence of at most n items
skip (iter, n)
  skip the first n values of a sequence

  ### Parameters:

  - iter a sequence of one or more values
  - n number of items to skip
enum (iter)
  a sequence with a sequence count and the original value. enum(copy(ls)) is a roundabout way of saying ipairs(ls).

  ### Parameters:

  - iter a single or double valued sequence

  ### Returns:

  sequence of (i,v), i = 1..n and v is from iter.
mapmethod (iter, name, arg1, arg2)
  map using a named method over a sequence.

  ### Parameters:

  - iter a sequence
  - name the method name
  - arg1 optional first extra argument
  - arg2 optional second extra argument
last (iter)
  a sequence of (last,current) values from another sequence. This will return S(i-1),S(i) if given S(i)

  ### Parameters:

  - iter a sequence
foreach (iter, fn)
  call the function on each element of the sequence.

  ### Parameters:

  - iter a sequence with up to 3 values
  - fn a function
lines (f, ...)
  create a wrapped iterator over all lines in the file.

  ### Parameters:

  - f either a filename, file-like object, or 'STDIN' (for standard input)
  - ... for Lua 5.2 only, optional format specifiers, as in io.read.

  ### Returns:

  a sequence wrapper

generated by LDoc 1.5.0