Module pl.list

Python-style list class. Based on original code by Nick Trout.
Please note: methods that change the list will return the list.
This is to allow for method chaining, but please note that ls = ls:sort()
does not mean that a new copy of the list is made. In-place (mutable) methods
are marked as returning 'the list' in this documentation.

Functions

List.range (start, finish) Emulate Python's range(x) function.
List.split (s, delim) split a string using a delimiter.
List:__call () can iterate over a list directly.
List:__concat (L) concatenation operator ..
List:__eq (L) equality operator ==.
List:__tostring () how our list should be rendered as a string.
List:append (i) Add an item to the end of the list.
List:chop (i1, i2) Remove a subrange of elements.
List:clear () empty the list.
List:concat (delim) join a list of strings.
List:contains (x) does this list contain the value?.
List:count (x) Return the number of times value appears in the list.
List:extend (L) Extend the list by appending all the items in the given list.
List:filter (fun) create a list of all elements which match a function.
List:foreach (fun, ...) call the function for each element of the list.
List:index (x, idx) Return the index in the list of the first item whose value is given.
List:insert (i, x) Insert an item at a given position.
List:iter () return an iterator over all values.
List:join (delim) join the elements of a list using a delimiter.
This method uses tostring on all elements.
List:len () list:len() is the same as #list.
List:map (fun, ..., arg1) apply a function to all elements.
List:map2 (fun, ls, ...) apply a function to elements of two lists.
List:mapm (name, ...) apply a named meethod to all elements.
List:minmax () calculate the minimum and maximum values.
List:new (t) Create a new list.
List:partition (fun, ...) partition a list using a classifier function.
List:pop (i) Remove the item at the given position in the list, and return it.
List:put (x) Insert an item at the begining of the list.
List:reduce (fun) 'reduce' a list using a binary function.
List:remove (i) Remove an element given its index.
List:remove_value (x) Remove the first item from the list whose value is given.
List:reverse () Reverse the elements of the list, in place.
List:slice (first, last) Emulate list slicing.
List:slice_assign (i1, i2, seq) general slice assignment s[i1:i2] = seq.
List:sort (cmp) Sort the items of the list, in place.
List:splice (idx, list) Insert a sublist into a list equivalent to 's[idx:idx] = list' in Python
List:sum (res) sum the elements.
List:transform (fun, ...) apply a function to all elements, in-place.
List:transform (fun, ...) apply a function to all elements, in-place.
iter (seq) Create an iterator over a seqence.


Functions

List.range (start, finish)
Emulate Python's range(x) function. Include it in List table for tidiness

Parameters:

  • start: A number
  • finish: A number greater than start; if zero, then 0..start-1

Usage:

    List.range(0,3) == List {0,1,2,3}
List.split (s, delim)
split a string using a delimiter.

Parameters:

  • s: the string
  • delim: the delimiter (default spaces)

Return value:

    a List of strings

See also:

List:__call ()
can iterate over a list directly.

Usage:

    for v in ls do print(v) end
List:__concat (L)
concatenation operator .. .

Parameters:

  • L: another List

Return value:

    a new list consisting of the list with the elements of the new list appended
List:__eq (L)
equality operator ==. True iff all elements of two lists are equal.

Parameters:

  • L: another List

Return value:

    true or false
List:__tostring ()
how our list should be rendered as a string. Uses join().

See also:

List:append (i)
Add an item to the end of the list.

Parameters:

  • i: An item

Return value:

    the list
List:chop (i1, i2)
Remove a subrange of elements. equivalent to 'del s[i1:i2]' in Python.

Parameters:

  • i1: start of range
  • i2: end of range

Return value:

    the list
List:clear ()
empty the list.

Return value:

    the list
List:concat (delim)
join a list of strings.
Uses table.concat directly.

Parameters:

  • delim: a delimiter

Return value:

    a string
List:contains (x)
does this list contain the value?.

Parameters:

  • x: A data value

Return value:

    true or false
List:count (x)
Return the number of times value appears in the list.

Parameters:

  • x: A data value

Return value:

    number of times x appears
List:extend (L)
Extend the list by appending all the items in the given list. equivalent to 'a[len(a):] = L'.

Parameters:

  • L: Another List

Return value:

    the list
List:filter (fun)
create a list of all elements which match a function.

Parameters:

  • fun: a boolean function

Return value:

    a new filtered list.
List:foreach (fun, ...)
call the function for each element of the list.

Parameters:

  • fun: a function or callable object
  • ...:
List:index (x, idx)
Return the index in the list of the first item whose value is given. Return nil if there is no such item.

Parameters:

  • x: A data value
  • idx: where to start search (default 1)

Return value:

    the index, or nil if not found.
List:insert (i, x)
Insert an item at a given position. i is the index of the element before which to insert.

Parameters:

  • i: index of element before whichh to insert
  • x: A data item

Return value:

    the list
List:iter ()
return an iterator over all values.
List:join (delim)
join the elements of a list using a delimiter.
This method uses tostring on all elements.

Parameters:

  • delim: a delimiter string, can be empty.

Return value:

    a string
List:len ()
list:len() is the same as #list.
List:map (fun, ..., arg1)
apply a function to all elements. Any extra arguments will be passed to the function

Parameters:

  • fun: a function of at least one argument
  • ...: arbitrary extra arguments.
  • arg1: an optional argument

Return value:

    a new list: {f(x) for x in self}

See also:

List:map2 (fun, ls, ...)
apply a function to elements of two lists. Any extra arguments will be passed to the function

Parameters:

  • fun: a function of at least two arguments
  • ls:
  • ...: arbitrary extra arguments.

Return value:

    a new list: {f(x,y) for x in self, for x in arg1}

See also:

List:mapm (name, ...)
apply a named meethod to all elements. Any extra arguments will be passed to the method.

Parameters:

  • name: name of method
  • ...: extra arguments

Return value:

    a new list of the results

See also:

List:minmax ()
calculate the minimum and maximum values.

Return values:

  1. minimum value
  2. maximum value
List:new (t)
Create a new list. Can optionally pass a table; passing another instance of List will cause a copy to be created we pass anything which isn't a simple table to iter() to work out

Parameters:

  • t: An optional list-like table

Usage:

    ls = List();  ls = List {1,2,3,4}

Return value:

    a new List

See also:

List:partition (fun, ...)
partition a list using a classifier function. The function may return nil, but this will be converted to the string key ''.

Parameters:

  • fun: a function of at least one argument
  • ...: will also be passed to the function

Return value:

    a table where the keys are the returned values, and the values are Lists of values where the function returned that key. It is given the type of Multimap.

See also:

List:pop (i)
Remove the item at the given position in the list, and return it. If no index is specified, a:pop() returns the last item in the list. The item is also removed from the list.

Parameters:

  • i: An index

Return value:

    the item
List:put (x)
Insert an item at the begining of the list.

Parameters:

  • x: a data item

Return value:

    the list
List:reduce (fun)
'reduce' a list using a binary function.

Parameters:

  • fun: a function of two arguments

Return value:

    result of the function

See also:

List:remove (i)
Remove an element given its index. (equivalent of Python's del s[i])

Parameters:

  • i: the index

Return value:

    the list
List:remove_value (x)
Remove the first item from the list whose value is given. (This is called 'remove' in Python; renamed to avoid confusion with table.remove) Return nil if there is no such item.

Parameters:

  • x: A data value

Return value:

    the list
List:reverse ()
Reverse the elements of the list, in place.

Return value:

    the list
List:slice (first, last)
Emulate list slicing. like 'list[first:last]' in Python. If first or last are negative then they are relative to the end of the list eg. _slice(-2)_ gives last 2 entries in a list, eg. _slice(-4,-2)_ gives from -4th to -2nd

Parameters:

  • first: An index
  • last: An index

Return value:

    a new List
List:slice_assign (i1, i2, seq)
general slice assignment s[i1:i2] = seq.

Parameters:

  • i1: start index
  • i2: end index
  • seq: a list

Return value:

    the list
List:sort (cmp)
Sort the items of the list, in place.

Parameters:

  • cmp: an optional comparison function; '<' is used if not given.

Return value:

    the list
List:splice (idx, list)
Insert a sublist into a list equivalent to 's[idx:idx] = list' in Python

Parameters:

  • idx: index
  • list: list to insert

Usage:

    l = List{10,20}; l:splice(2,{21,22});  assert(l == List{10,21,22,20})

Return value:

    the list
List:sum (res)
sum the elements. May provide an initial value, which is useful if you are applying a generalized sum operator.

Parameters:

  • res: initial value (default 0)
List:transform (fun, ...)
apply a function to all elements, in-place.

Parameters:

  • fun: a function of at least one argument.
  • ...: extra arguments for the function.
List:transform (fun, ...)
apply a function to all elements, in-place.

Parameters:

  • fun: a function of at least one argument.
  • ...: extra arguments for the function.
iter (seq)
Create an iterator over a seqence. This captures the Python concept of 'sequence'. For tables, iterates over all values with integer indices.

Parameters:

  • seq: a sequence; a string (over characters), a table, a file object (over lines) or an iterator function

Usage:

  • for x in iter {1,10,22,55} do io.write(x,',') end ==> 1,10,22,55
  • for ch in iter 'help' do do io.write(ch,' ') end ==> h e l p

Valid XHTML 1.0!