Module pl.List

Python-style list class.

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.

See the Guide for further discussion

See http://www.python.org/doc/current/tut/tut.html, section 5.1

Note: The comments before some of the functions are from the Python docs and contain Python code.

Written for Lua version Nick Trout 4.0; Redone for Lua 5.1, Steve Donovan.

Dependencies: pl.utils , pl.tablex

Functions

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


Functions

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 iterate() to work out an appropriate iterator @see List.iterate

Parameters:

  • t: An optional list-like table

Usage:

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

Returns:

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

Parameters:

  • i: An item

Returns:

    the list
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

Returns:

    the list
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

Returns:

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

Parameters:

  • x: a data item

Returns:

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

Parameters:

  • i: the index

Returns:

    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

Returns:

    the list
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

Returns:

    the item
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)

Returns:

    the index, or nil if not found.
List:contains (x)
does this list contain the value?.

Parameters:

  • x: A data value

Returns:

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

Parameters:

  • x: A data value

Returns:

    number of times x appears
List:sort (cmp)
Sort the items of the list, in place.

Parameters:

  • cmp: an optional comparison function, default ‘<’

Returns:

    the list
List:sorted (cmp)
return a sorted copy of this list.

Parameters:

  • cmp: an optional comparison function, default ‘<’

Returns:

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

Returns:

    the list
List:minmax ()
return the minimum and the maximum value of the list.

Returns:

  1. minimum value
  2. maximum value
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, and slice(-4,-2) gives from -4th to -2nd

Parameters:

  • first: An index
  • last: An index

Returns:

    a new List
List:clear ()
empty the list.

Returns:

    the list
List.range (start, finish, incr)
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
  • incr: an optional increment (may be less than 1)

Usage:

    List.range(0,3) == List {0,1,2,3}
List:len ()
list:len() is the same as #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

Returns:

    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})

Returns:

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

Parameters:

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

Returns:

    the list
List:__concat (L)
concatenation operator.

Parameters:

  • L: another List

Returns:

    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

Returns:

    true or false
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.

Returns:

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

Parameters:

  • delim: a delimiter

Returns:

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

see also:

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

Parameters:

  • fun: a function or callable object
  • ...: optional values to pass to function
List:filter (fun, arg)
create a list of all elements which match a function.

Parameters:

  • fun: a boolean function
  • arg: optional argument to be passed as second argument of the predicate

Returns:

    a new filtered list.
List.split (s, delim)
split a string using a delimiter.

Parameters:

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

Returns:

    a List of strings

see also:

List:map (fun, ...)
apply a function to all elements. Any extra arguments will be passed to the function; if the function is nil then map returns a mapper object that maps over a method of the items

Parameters:

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

Usage:

  • List{'one','two'}:map(string.upper) == {'ONE','TWO'}
  • List{'one','two'}:map():sub(1,2) == {'on','tw'}

Returns:

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

see also:

List:transform (fun, ...)
apply a function to all elements, in-place. Any extra arguments are passed to the function.

Parameters:

  • fun: A function that takes at least one argument
  • ...: arbitrary extra arguments.
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: another list
  • ...: arbitrary extra arguments.

Returns:

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

see also:

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

Parameters:

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

Returns:

    a new list of the results

see also:

List:reduce (fun)
‘reduce’ a list using a binary function.

Parameters:

  • fun: a function of two arguments

Returns:

    result of the function

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

Returns:

    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:iter ()
return an iterator over all values.
List.iterate (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 iterate {1,10,22,55} do io.write(x,',') end ==> 1,10,22,55
  • for ch in iterate 'help' do do io.write(ch,' ') end ==> h e l p
generated by LDoc 1.2