From 42ec7286b2d36a9ba22925f816a17cb1cc2aa5ce Mon Sep 17 00:00:00 2001 From: chai Date: Sat, 30 Oct 2021 11:32:16 +0800 Subject: + Penlight --- Data/Libraries/Penlight/docs/classes/pl.List.html | 1443 +++++++++++++++++++++ 1 file changed, 1443 insertions(+) create mode 100644 Data/Libraries/Penlight/docs/classes/pl.List.html (limited to 'Data/Libraries/Penlight/docs/classes/pl.List.html') diff --git a/Data/Libraries/Penlight/docs/classes/pl.List.html b/Data/Libraries/Penlight/docs/classes/pl.List.html new file mode 100644 index 0000000..b84209f --- /dev/null +++ b/Data/Libraries/Penlight/docs/classes/pl.List.html @@ -0,0 +1,1443 @@ + + + + + Penlight Documentation + + + + +
+ +
+ +
+
+
+ + +
+ + + + + + +
+ +

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. +
  2. + maximum value
    3. +
+ + + + +
+
+ + 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 +
+
+ + -- cgit v1.1-26-g67d0