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: