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:
- minimum value
- 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:
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: