Class 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, pl.class

Functions

List.new ([t]) Create a new list.
List:clone () Make a copy of an existing 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=1]) 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=1]]) 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:join ([delim='']) join the elements of a list using a delimiter.
List:concat ([delim='']) join a list of strings.
List:foreach (fun, ...) call the function on each element of the list.
List:foreachm (name, ...) call the named method on 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.

metamethods

List:__concat (L) concatenation operator.
List:__eq (L) equality operator ==.
List:__tostring () how our list should be rendered as a string.


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; this will return a plain table with an appropriate metatable. we pass anything which isn’t a simple table to iterate() to work out an appropriate iterator

Parameters:

  • t An optional list-like table (optional)

Returns:

    a new List

See also:

Usage:

    ls = List();  ls = List {1,2,3,4}
List:clone ()
Make a copy of an existing list. The difference from a plain ‘copy constructor’ is that this returns the actual List subtype.
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 List 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 int 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 int 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 int An index (optional)

Returns:

    the item
List:index (x[, idx=1])
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 int 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 func an optional comparison function (default '<')

Returns:

    the list
List:sorted ([cmp='<'])
return a sorted copy of this list.

Parameters:

  • cmp func 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=1]])
Emulate Python’s range(x) function. Include it in List table for tidiness

Parameters:

  • start int A number
  • finish int A number greater than start; if absent, then start is 1 and finish is start (optional)
  • incr int an increment (may be less than 1) (default 1)

Returns:

    a List from start .. finish

Usage:

  • List.range(0,3) == List{0,1,2,3}
  • List.range(4) = List{1,2,3,4}
  • List.range(5,1,-1) == List{5,4,3,2,1}
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 int start of range
  • i2 int 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 int index
  • list List list to insert

Returns:

    the list

Usage:

    l = List{10,20}; l:splice(2,{21,22});  assert(l == List{10,21,22,20})
List:slice_assign (i1, i2, seq)
general slice assignment s[i1:i2] = seq.

Parameters:

  • i1 int start index
  • i2 int end index
  • seq List a list

Returns:

    the list
List:join ([delim=''])
join the elements of a list using a delimiter.
This method uses tostring on all elements.

Parameters:

  • delim string a delimiter string, can be empty. (default '')

Returns:

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

Parameters:

  • delim string a delimiter (default '')

Returns:

    a string
List:foreach (fun, ...)
call the function on each element of the list.

Parameters:

  • fun func a function or callable object
  • ... optional values to pass to function
List:foreachm (name, ...)
call the named method on each element of the list.

Parameters:

  • name string the method name
  • ... optional values to pass to function
List:filter (fun[, arg])
create a list of all elements which match a function.

Parameters:

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

Returns:

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

Parameters:

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

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.

Parameters:

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

Returns:

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

See also:

Usage:

    List{'one','two'}:map(string.upper) == {'ONE','TWO'}
List:transform (fun, ...)
apply a function to all elements, in-place. Any extra arguments are passed to the function.

Parameters:

  • fun func A function that takes at least one argument
  • ... arbitrary extra arguments.

Returns:

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

Parameters:

  • fun func a function of at least two arguments
  • ls List 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 string 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 func 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 func a function of at least one argument
  • ... will also be passed to the function

Returns:

    MultiMap a table where the keys are the returned values, and the values are Lists of values where the function returned that key.

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

metamethods

List:__concat (L)
concatenation operator.

Parameters:

  • L List 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 List another List

Returns:

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

See also:

generated by LDoc 1.4.6 Last updated 2017-07-18 16:28:41