Module pl.tablex
Extended operations on Lua tables.
 See the Guide
 Dependencies: pl.utils, pl.types
	
	| size (t) | total number of elements in this table. | 
	
	| index_by (tbl, idx) | return a list of all values in a table indexed by another list. | 
	
	| transform (fun, t, ...) | apply a function to all values of a table, in-place. | 
	
	| range (start, finish[, step=1]) | generate a table of all numbers in a range. | 
	
	| reduce (fun, t, memo) | 'reduce' a list using a binary function. | 
	
	| index_map (t) | create an index map from a list-like table. | 
	
	| makeset (t) | create a set from a list-like table. | 
	
	| union (t1, t2) | the union of two map-like tables. | 
	
	| intersection (t1, t2) | the intersection of two map-like tables. | 
	
	| count_map (t, cmp) | A table where the key/values are the values and value counts of the table. | 
	
	| set (t, val[, i1=1[, i2=#t]]) | set an array range to a value. | 
	
	| new (n, val) | create a new array of specified size with initial value. | 
	
	| clear (t, istart) | clear out the contents of a table. | 
	
	| removevalues (t, i1, i2) | remove a range of values from a table. | 
	
	| readonly (t) | modifies a table to be read only. | 
	
	| update (t1, t2) | copy a table into another, in-place. | 
	
	| copy (t) | make a shallow copy of a table | 
	
	| deepcopy (t) | make a deep copy of a table, recursively copying all the keys and fields. | 
	
	| icopy (dest, src[, idest=1[, isrc=1[, nsrc=#src]]]) | copy an array into another one, clearing destafteridest+nsrc, if necessary. | 
	
	| move (dest, src[, idest=1[, isrc=1[, nsrc=#src]]]) | copy an array into another one. | 
	
	| insertvalues (t[, position], values) | insert values into a table. | 
	
	| map (fun, t, ...) | apply a function to all values of a table. | 
	
	| imap (fun, t, ...) | apply a function to all values of a list. | 
	
	| map_named_method (name, t, ...) | apply a named method to values from a table. | 
	
	| map2 (fun, t1, t2, ...) | apply a function to values from two tables. | 
	
	| imap2 (fun, t1, t2, ...) | apply a function to values from two arrays. | 
	
	| mapn (fun, ..., fun) | Apply a function to a number of tables. | 
	
	| pairmap (fun, t, ...) | call the function with the key and value pairs from a table. | 
	
	| filter (t, pred, arg) | filter an array's values using a predicate function | 
	
	| keys (t) | return all the keys of a table in arbitrary order. | 
	
	| values (t) | return all the values of the table in arbitrary order | 
	
	| sub (t, first, last) | Extract a range from a table, like  'string.sub'. | 
    
    
    - 
    
    size (t)
    
- 
    total number of elements in this table.
 Note that this is distinct from #t, which is the number
 of values in the array part; this value will always
 be greater or equal. The difference gives the size of
 the hash part, for practical purposes. Works for any
 object with a __pairs metamethod.Parameters:Returns:
        the size
     
- 
    
    index_by (tbl, idx)
    
- 
    return a list of all values in a table indexed by another list.
    Parameters:
        - tbl
            table
         a table
        
- idx
            array
         an index table (a list of keys)
        
 Returns:
        a list-like table
     Usage:
        - index_by({10,20,30,40},{2,4}) == {20,40}
- index_by({one=1,two=2,three=3},{'one','three'}) == {1,3}
 
- 
    
    transform (fun, t, ...)
    
- 
    apply a function to all values of a table, in-place.
 Any extra arguments are passed to the function.
    Parameters:
        - fun
            function
         A function that takes at least one argument
        
- t
            table
         a table
        
- ...
         extra arguments passed to fun
 See also:
- 
    
    range (start, finish[, step=1])
    
- 
    generate a table of all numbers in a range.
 This is consistent with a numerical for loop.
    Parameters:
        - start
            integer
          number
        
- finish
            integer
         number
        
- step
            integer
          make this negative for start < finish
         (default 1)
        
 
- 
    
    reduce (fun, t, memo)
    
- 
    'reduce' a list using a binary function.
    Parameters:
        - fun
            function
         a function of two arguments
        
- t
            array
         a list-like table
        
- memo
            array
         optional initial memo value. Defaults to first value in table.
        
 Returns:
        the result of the function
     Usage:reduce('+',{1,2,3,4}) == 10
- 
    
    index_map (t)
    
- 
    create an index map from a list-like table.  The original values become keys,
 and the associated values are the indices into the original list.
    Parameters:
        - t
            array
         a list-like table
        
 Returns:
        a map-like table
     
- 
    
    makeset (t)
    
- 
    create a set from a list-like table.  A set is a table where the original values
 become keys, and the associated values are all true.
    Parameters:
        - t
            array
         a list-like table
        
 Returns:
        a set (a map-like table)
     
- 
    
    union (t1, t2)
    
- 
    the union of two map-like tables.
 If there are duplicate keys, the second table wins.
    Parameters:Returns:
           tab
     See also:
- 
    
    intersection (t1, t2)
    
- 
    the intersection of two map-like tables.
    Parameters:Returns:
           tab
     See also:
- 
    
    count_map (t, cmp)
    
- 
    A table where the key/values are the values and value counts of the table.
    Parameters:
        - t
            array
         a list-like table
        
- cmp
            function
         a function that defines equality (otherwise uses ==)
        
 Returns:
        a map-like table
     See also:
- 
    
    set (t, val[, i1=1[, i2=#t]])
    
- 
    set an array range to a value.  If it's a function we use the result
 of applying it to the indices.
    Parameters:
        - t
            array
         a list-like table
        
- val
         a value
        
- i1
            integer
         start range
         (default 1)
        
- i2
            integer
         end range
         (default #t)
        
 
- 
    
    new (n, val)
    
- 
    create a new array of specified size with initial value.
    Parameters:
        - n
            integer
         size
        
- val
         initial value (can be nil, but don't expect#to work!)
 Returns:
        the table
     
- 
    
    clear (t, istart)
    
- 
    clear out the contents of a table.
    Parameters:
        - t
            array
         a list
        
- istart
         optional start position
        
 
- 
    
    removevalues (t, i1, i2)
    
- 
    remove a range of values from a table.
 End of range may be negative.
    Parameters:
        - t
            array
         a list-like table
        
- i1
            integer
         start index
        
- i2
            integer
         end index
        
 Returns:
        the table
     
- 
    
    readonly (t)
    
- 
    modifies a table to be read only.
 This only offers weak protection. Tables can still be modified with
 table.insert and rawset.
 NOTE: for Lua 5.1 length, pairs and ipairs will not work, since the
 equivalent metamethods are only available in Lua 5.2 and newer.
     Parameters:Returns:
        the table read only (a proxy).
     
    - 
    
    update (t1, t2)
    
- 
    copy a table into another, in-place.
    Parameters:
        - t1
            table
         destination table
        
- t2
            table
         source (actually any iterable object)
        
 Returns:
        first table
     
- 
    
    copy (t)
    
- 
    make a shallow copy of a table
    Parameters:
        - t
            table
         an iterable source
        
 Returns:
        new table
     
- 
    
    deepcopy (t)
    
- 
    make a deep copy of a table, recursively copying all the keys and fields.
 This supports cycles in tables; cycles will be reproduced in the copy.
 This will also set the copied table's metatable to that of the original.
    Parameters:Returns:
        new table
     
- 
    
    icopy (dest, src[, idest=1[, isrc=1[, nsrc=#src]]])
    
- 
    copy an array into another one, clearing destafteridest+nsrc, if necessary.Parameters:
        - dest
            array
         a list-like table
        
- src
            array
         a list-like table
        
- idest
            integer
         where to start copying values into destination
         (default 1)
        
- isrc
            integer
         where to start copying values from source
         (default 1)
        
- nsrc
            integer
         number of elements to copy from source
         (default #src)
        
 
- 
    
    move (dest, src[, idest=1[, isrc=1[, nsrc=#src]]])
    
- 
    copy an array into another one.
    Parameters:
        - dest
            array
         a list-like table
        
- src
            array
         a list-like table
        
- idest
            integer
         where to start copying values into destination
         (default 1)
        
- isrc
            integer
         where to start copying values from source
         (default 1)
        
- nsrc
            integer
         number of elements to copy from source
         (default #src)
        
 
- 
    
    insertvalues (t[, position], values)
    
- 
    insert values into a table.
 similar to table.insert but inserts values from given table values,
 not the object itself, into table tat positionpos.Parameters:
        - t
            array
         the list
        
- position
            integer
         (default is at end)
         (optional)
        
- values
            array
        
 
    - 
    
    deepcompare (t1, t2[, ignore_mt[, eps]])
    
- 
    compare two values.
 if they are tables, then compare their keys and fields recursively.
    Parameters:
        - t1
         A value
        
- t2
         A value
        
- ignore_mt
            boolean
         if true, ignore __eq metamethod (default false)
         (optional)
        
- eps
            number
         if defined, then used for any number comparisons
         (optional)
        
 Returns:
        true or false
     
- 
    
    compare (t1, t2, cmp)
    
- 
    compare two arrays using a predicate.
    Parameters:
        - t1
            array
         an array
        
- t2
            array
         an array
        
- cmp
            function
         A comparison function; bool = cmp(t1_value, t2_value)
 Returns:
        true or false
     Usage:assert(tablex.compare({ 1, 2, 3 }, { 1, 2, 3 }, "=="))
assert(tablex.compare(
   {1,2,3, hello = "world"},     {1,2,3}, function(v1, v2) return v1 == v2 end)
- 
    
    compare_no_order (t1, t2, cmp)
    
- 
    compare two list-like tables using an optional predicate, without regard for element order.
    Parameters:
        - t1
            array
         a list-like table
        
- t2
            array
         a list-like table
        
- cmp
         A comparison function (may be nil)
        
 
    - 
    
    find (t, val, idx)
    
- 
    return the index of a value in a list.
 Like string.find, there is an optional index to start searching,
 which can be negative.
    Parameters:
        - t
            array
         A list-like table
        
- val
         A value
        
- idx
            integer
         index to start; -1 means last element,etc (default 1)
        
 Returns:
        index of value or nil if not found
     Usage:
        - find({10,20,30},20) == 2
- find({'a','b','a','c'},'a',2) == 3
 
- 
    
    rfind (t, val, idx)
    
- 
    return the index of a value in a list, searching from the end.
 Like string.find, there is an optional index to start searching,
 which can be negative.
    Parameters:
        - t
            array
         A list-like table
        
- val
         A value
        
- idx
         index to start; -1 means last element,etc (default #t)
 Returns:
        index of value or nil if not found
     Usage:rfind({10,10,10},10) == 3
- 
    
    find_if (t, cmp, arg)
    
- 
    return the index (or key) of a value in a table using a comparison function. 
 NOTE: the 2nd return value of this function, the value returned
 by the comparison function, has a limitation that it cannot be false.
 Because if it is, then it indicates the comparison failed, and the
 function will continue the search. See examples.
 Parameters:
        - t
            table
         A table
        
- cmp
            function
         A comparison function
        
- arg
         an optional second argument to the function
        
 Returns:
        - 
        index of value, or nil if not found
- 
        value returned by comparison function (cannot be false!)
 Usage:local lst = { "Rudolph", true, false, 15 }
local idx, cmp_result = tablex.rfind(lst, "==", "Rudolph")
assert(idx == 1)
assert(cmp_result == true)
local idx, cmp_result = tablex.rfind(lst, "==", false)
assert(idx == 3)
assert(cmp_result == true)       
local cmp = function(v1, v2) return v1 == v2 and v2 end
local idx, cmp_result = tablex.rfind(lst, cmp, "Rudolph")
assert(idx == 1)
assert(cmp_result == "Rudolph")  
local idx, cmp_result = tablex.rfind(lst, cmp, false)
assert(idx == nil)               assert(cmp_result == nil)
- 
    
    search (t, value[, exclude])
    
- 
    find a value in a table by recursive search.
    Parameters:
        - t
            table
         the table
        
- value
         the value
        
- exclude
            array
         any tables to avoid searching
         (optional)
        
 Returns:
        a fieldspec, e.g. 'a.b' or 'math.sin'
     Usage:search(_G,math.sin,{package.path}) == 'math.sin'
    - 
    
    map (fun, t, ...)
    
- 
    apply a function to all values of a table.
 This returns a table of the results.
 Any extra arguments are passed to the function.
    Parameters:
        - fun
            function
         A function that takes at least one argument
        
- t
            table
         A table
        
- ...
         optional arguments
        
 Usage:map(function(v) return v*v end, {10,20,30,fred=2}) is {100,400,900,fred=4}
- 
    
    imap (fun, t, ...)
    
- 
    apply a function to all values of a list.
 This returns a table of the results.
 Any extra arguments are passed to the function.
    Parameters:
        - fun
            function
         A function that takes at least one argument
        
- t
            array
         a table (applies to array part)
        
- ...
         optional arguments
        
 Returns:
        a list-like table
     Usage:imap(function(v) return v*v end, {10,20,30,fred=2}) is {100,400,900}
- 
    
    map_named_method (name, t, ...)
    
- 
    apply a named method to values from a table.
    Parameters:
        - name
            string
         the method name
        
- t
            array
         a list-like table
        
- ...
         any extra arguments to the method
        
 Returns:
        a List with the results of the method (1st result only)
     Usage:local Car = {}
Car.__index = Car
function Car.new(car)
  return setmetatable(car or {}, Car)
end
Car.speed = 0
function Car:faster(increase)
  self.speed = self.speed + increase
  return self.speed
end
local ferrari = Car.new{ name = "Ferrari" }
local lamborghini = Car.new{ name = "Lamborghini", speed = 50 }
local cars = { ferrari, lamborghini }
assert(ferrari.speed == 0)
assert(lamborghini.speed == 50)
tablex.map_named_method("faster", cars, 10)
assert(ferrari.speed == 10)
assert(lamborghini.speed == 60)
- 
    
    map2 (fun, t1, t2, ...)
    
- 
    apply a function to values from two tables.
    Parameters:
        - fun
            function
         a function of at least two arguments
        
- t1
            table
         a table
        
- t2
            table
         a table
        
- ...
         extra arguments
        
 Returns:
        a table
     Usage:map2('+',{1,2,3,m=4},{10,20,30,m=40}) is {11,22,23,m=44}
- 
    
    imap2 (fun, t1, t2, ...)
    
- 
    apply a function to values from two arrays.
 The result will be the length of the shortest array.
    Parameters:
        - fun
            function
         a function of at least two arguments
        
- t1
            array
         a list-like table
        
- t2
            array
         a list-like table
        
- ...
         extra arguments
        
 Usage:imap2('+',{1,2,3,m=4},{10,20,30,m=40}) is {11,22,23}
- 
    
    mapn (fun, ..., fun)
    
- 
    Apply a function to a number of tables.
 A more general version of map
 The result is a table containing the result of applying that function to the
 ith value of each table. Length of output list is the minimum length of all the lists
    Parameters:
        - fun
         A function that takes as many arguments as there are tables
        
- ...
            table
         n tables
        
- fun
         A function that takes as many arguments as there are tables
        
 Usage:
        - mapn(function(x,y,z) return x+y+z end, {1,2,3},{10,20,30},{100,200,300}) is {111,222,333}
- mapn(math.max, {1,20,300},{10,2,3},{100,200,100}) is    {100,200,300}
 
- 
    
    pairmap (fun, t, ...)
    
- 
    call the function with the key and value pairs from a table.
 The function can return a value and a key (note the order!). If both
 are not nil, then this pair is inserted into the result: if the key already exists, we convert the value for that
 key into a table and append into it. If only value is not nil, then it is appended to the result.
    Parameters:
        - fun
            function
         A function which will be passed each key and value as arguments, plus any extra arguments to pairmap.
        
- t
            table
         A table
        
- ...
         optional arguments
        
 Usage:
        - pairmap(function(k,v) return v end,{fred=10,bonzo=20}) is {10,20} _or_ {20,10}
- pairmap(function(k,v) return {k,v},k end,{one=1,two=2}) is {one={'one',1},two={'two',2}}
 
- 
    
    filter (t, pred, arg)
    
- 
    filter an array's values using a predicate function
    Parameters:
        - t
            array
         a list-like table
        
- pred
            function
         a boolean function
        
- arg
         optional argument to be passed as second argument of the predicate
        
 
    - 
    
    foreach (t, fun, ...)
    
- 
    apply a function to all elements of a table.
 The arguments to the function will be the value,
 the key and finally any extra arguments passed to this function.
 Note that the Lua 5.0 function table.foreach passed the key first.
    Parameters:
        - t
            table
         a table
        
- fun
            function
         a function on the elements; function(value, key, ...)
- ...
         extra arguments passed to fun
 See also:
- 
    
    foreachi (t, fun, ...)
    
- 
    apply a function to all elements of a list-like table in order.
 The arguments to the function will be the value,
 the index and finally any extra arguments passed to this function
    Parameters:
        - t
            array
         a table
        
- fun
            function
         a function with at least one argument
        
- ...
         optional arguments
        
 
- 
    
    sort (t, f)
    
- 
    return an iterator to a table sorted by its keys
    Parameters:
        - t
            table
         the table
        
- f
            function
         an optional comparison function (f(x,y) is true if x < y)
        
 Returns:
        an iterator to traverse elements sorted by the keys
     Usage:for k,v in tablex.sort(t) do print(k,v) end 
- 
    
    sortv (t, f)
    
- 
    return an iterator to a table sorted by its values
    Parameters:
        - t
            table
         the table
        
- f
            function
         an optional comparison function (f(x,y) is true if x < y)
        
 Returns:
        an iterator to traverse elements sorted by the values
     Usage:for k,v in tablex.sortv(t) do print(k,v) end 
    - 
    
    keys (t)
    
- 
    return all the keys of a table in arbitrary order.
    Parameters:
        - t
            table
         A list-like table where the values are the keys of the input table
        
 
- 
    
    values (t)
    
- 
    return all the values of the table in arbitrary order
    Parameters:
        - t
            table
         A list-like table where the values are the values of the input table
        
 
- 
    
    sub (t, first, last)
    
- 
    Extract a range from a table, like  'string.sub'.
 If first or last are negative then they are relative to the end of the list
 eg. sub(t,-2) gives last 2 entries in a list, and
 sub(t,-4,-2) gives from -4th to -2nd
    Parameters:
        - t
            array
         a list-like table
        
- first
            integer
         An index
        
- last
            integer
         An index
        
 Returns:
        a new List
     
    - 
    
    merge (t1, t2, dup)
    
- 
    combine two tables, either as union or intersection.  Corresponds to
 set operations for sets () but more general. Not particularly
 useful for list-like tables.
    Parameters:
        - t1
            table
         a table
        
- t2
            table
         a table
        
- dup
            boolean
         true for a union, false for an intersection.
        
 See also:Usage:
        - merge({alice=23,fred=34},{bob=25,fred=34}) is {fred=34}
- merge({alice=23,fred=34},{bob=25,fred=34},true) is {bob=25,fred=34,alice=23}
 
- 
    
    difference (s1, s2, symm)
    
- 
    a new table which is the difference of two tables.
 With sets (where the values are all true) this is set difference and
 symmetric difference depending on the third parameter.
    Parameters:
        - s1
            table
         a map-like table or set
        
- s2
            table
         a map-like table or set
        
- symm
            boolean
         symmetric difference (default false)
        
 Returns:
        a map-like table or set
     
- 
    
    zip (...)
    
- 
    return a table where each element is a table of the ith values of an arbitrary
 number of tables.  It is equivalent to a matrix transpose.
    Parameters:
        - ...
            array
         arrays to be zipped
        
 Usage:zip({10,20,30},{100,200,300}) is {{10,100},{20,200},{30,300}}