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

Returns:

    a new List

Usage:

    ls = List();  ls = List {1,2,3,4}
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 absent, then start is 1 and finish is start
  • incr an optional increment (may be less than 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 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

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 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.

Returns:

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

see also:

Usage:

  • List{'one','two'}:map(string.upper) == {'ONE','TWO'}
  • List{'one','two'}:map():sub(1,2) == {'on','tw'}
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.

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 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 ''. of values where the function returned that key. It is given the type of Multimap.

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

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.3