# 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 beginning 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 sequence.

## 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:

  List.iterate

  ### 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 integer index of element before whichh to insert
  - x A data item

  ### Returns:

  the list
List:put (x)
  Insert an item at the beginning 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 integer 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 integer 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 integer 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 function an optional comparison function (default '<')

  ### Returns:

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

  ### Parameters:

  - cmp function 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 integer A number
  - finish integer A number greater than start; if absent, then start is 1 and finish is start (optional)
  - incr integer 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 integer start of range
  - i2 integer 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 integer 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 integer start index
  - i2 integer 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 function 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 function 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:

  pl.utils.split
List:map (fun, ...)
  Apply a function to all elements. Any extra arguments will be passed to the function.

  ### Parameters:

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

  ### Returns:

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

  ### See also:

  pl.tablex.imap

  ### 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 function 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 function 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:

  pl.tablex.imap2
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:

  pl.seq.mapmethod
List:reduce (fun)
  'reduce' a list using a binary function.

  ### Parameters:

  - fun function a function of two arguments

  ### Returns:

  result of the function

  ### See also:

  pl.tablex.reduce
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 function 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:

  pl.MultiMap
List:iter ()
  return an iterator over all values.
List.iterate (seq)
  Create an iterator over a sequence. 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:

  List:join

generated by LDoc 1.5.0