# Module `std.functional`

Functional programming.

A selection of higher-order functions to enable a functional style of programming in Lua.

## Functions

bind (fn, argt) | Partially apply a function.
callable (x) | Identify callable types.
case (with, branches) | A rudimentary case statement.
collect ([ifn=std.npairs], ...) | Collect the results of an iterator.
compose (...) | Compose functions.
cond (expr, branch, ...) | A rudimentary condition-case statement.
curry (fn, n) | Curry a function.
filter (pfn[, ifn=std.pairs], ...) | Filter an iterator with a predicate.
foldl (fn[, d=t[1]], t) | Fold a binary function left associatively.
foldr (fn[, d=t[1]], t) | Fold a binary function right associatively.
id (...) | Identity function.
lambda (s) | Compile a lambda string into a Lua function.
map (fn[, ifn=std.pairs], ...) | Map a function over an iterator.
map_with (fn, tt) | Map a function over a table of argument lists.
memoize (fn[, normfn=std.tostring]) | Memoize a function, by wrapping it in a functable.
nop () | No operation.
reduce (fn, d[, ifn=std.pairs], ...) | Fold a binary function into an iterator.
zip (tt) | Zip a table of tables.
zip_with (fn, tt) | Zip a list of tables together with a function.

## Types

normalize (...) | Signature of a memoize argument normalization callback function.
predicate (...) | Signature of a filter predicate callback function.

## Functions

Methods

bind (fn, argt)
  Partially apply a function.

  ### Parameters:

  - fn func function to apply partially
  - argt table table of fn arguments to bind

  ### Returns:

  function with argt arguments already bound

  ### Usage:

      cube = bind (std.operator.pow, {[2] = 3})

callable (x)
  Identify callable types.

  ### Parameters:

  - x an object or primitive

  ### Returns:

  `true` if x can be called, otherwise `false`

  ### Usage:

      if callable (functable) then functable (args) end

case (with, branches)
  A rudimentary case statement. Match with against keys in branches table.

  ### Parameters:

  - with expression to match
  - branches table map possible matches to functions

  ### Returns:

  the value associated with a matching key, or the first non-key value if no key matches. Function or functable valued matches are called using with as the sole argument, and the result of that call returned; otherwise the matching value associated with the matching key is returned directly; or else `nil` if there is no match and no default.

  ### See also:

  cond

  ### Usage:

       return case (type (object), {
         table  = "table",
         string = function ()  return "string" end,
                  function (s) error ("unhandled type: " .. s) end,
       })

collect ([ifn=std.npairs], ...)
  Collect the results of an iterator.

  ### Parameters:

  - ifn func iterator function (default std.npairs)
  - ... ifn arguments

  ### Returns:

  table of results from running ifn on args

  ### See also:

  - filter
  - map

  ### Usage:

       --> {"a", "b", "c"}
       collect {"a", "b", "c", x=1, y=2, z=5}

compose (...)
  Compose functions.

  ### Parameters:

  - ... func functions to compose

  ### Returns:

  function composition of fnN .. fn1: note that this is the reverse of what you might expect, but means that code like:

       functional.compose (function (x) return f (x) end,
                           function (x) return g (x) end))

  can be read from top to bottom.

  ### Usage:

       vpairs = compose (table.invert, ipairs)
       for v, i in vpairs {"a", "b", "c"} do process (v, i) end

cond (expr, branch, ...)
  A rudimentary condition-case statement. If expr is "truthy" return branch if given, otherwise expr itself. If the return value is a function or functable, then call it with expr as the sole argument and return the result; otherwise return it explicitly. If expr is "falsey", then recurse with the first two arguments stripped.

  ### Parameters:

  - expr a Lua expression
  - branch a function, functable or value to use if expr is "truthy"
  - ... additional arguments to retry if expr is "falsey"

  ### See also:

  case

  ### Usage:

       -- recursively calculate the nth triangular number
       function triangle (n)
         return cond (
           n <= 0, 0,
           n == 1, 1,
                   function () return n + triangle (n - 1) end)
       end

curry (fn, n)
  Curry a function.

  ### Parameters:

  - fn func function to curry
  - n int number of arguments

  ### Returns:

  function curried version of fn

  ### Usage:

       add = curry (function (x, y) return x + y end, 2)
       incr, decr = add (1), add (-1)

filter (pfn[, ifn=std.pairs], ...)
  Filter an iterator with a predicate.

  ### Parameters:

  - pfn predicate predicate function
  - ifn func iterator function (default std.pairs)
  - ... iterator arguments

  ### Returns:

  table elements e for which `pfn (e)` is not "falsey".

  ### See also:

  - collect
  - map

  ### Usage:

       --> {2, 4}
       filter (lambda '|e|e%2==0', std.elems, {1, 2, 3, 4})

foldl (fn[, d=t[1]], t)
  Fold a binary function left associatively. If parameter d is omitted, the first element of t is used, and t treated as if it had been passed without that element.

  ### Parameters:

  - fn func binary function
  - d initial left-most argument (default t[1])
  - t table a table

  ### Returns:

  result

  ### See also:

  - foldr
  - reduce

  ### Usage:

      foldl (std.operator.quot, {10000, 100, 10}) == (10000 / 100) / 10

foldr (fn[, d=t[1]], t)
  Fold a binary function right associatively. If parameter d is omitted, the last element of t is used, and t treated as if it had been passed without that element.

  ### Parameters:

  - fn func binary function
  - d initial right-most argument (default t[1])
  - t table a table

  ### Returns:

  result

  ### See also:

  - foldl
  - reduce

  ### Usage:

      foldr (std.operator.quot, {10000, 100, 10}) == 10000 / (100 / 10)

id (...)
  Identity function.

  ### Parameters:

  - ... arguments

  ### Returns:

  arguments
lambda (s)
  Compile a lambda string into a Lua function.

  A valid lambda string takes one of the following forms:

  1. `'=expression'`: equivalent to `function (...) return expression end`
  2. `'|args|expression'`: equivalent to `function (args) return expression end`

  The first form (starting with `'='`) automatically assigns the first nine arguments to parameters `'_1'` through `'_9'` for use within the expression body. The parameter `'_1'` is aliased to `'_'`, and if the first non-whitespace of the whole expression is `'_'`, then the leading `'='` can be omitted.

  The results are memoized, so recompiling a previously compiled lambda string is extremely fast.

  ### Parameters:

  - s string a lambda string

  ### Returns:

  functable compiled lambda string, can be called like a function

  ### Usage:

       -- The following are equivalent:
       lambda '= _1 < _2'
       lambda '|a,b| a<b'

map (fn[, ifn=std.pairs], ...)
  Map a function over an iterator.

  ### Parameters:

  - fn func map function
  - ifn func iterator function (default std.pairs)
  - ... iterator arguments

  ### Returns:

  table results

  ### See also:

  - filter
  - map_with
  - zip

  ### Usage:

       --> {1, 4, 9, 16}
       map (lambda '=_1*_1', std.ielems, {1, 2, 3, 4})

map_with (fn, tt)
  Map a function over a table of argument lists.

  ### Parameters:

  - fn func map function
  - tt table a table of fn argument lists

  ### Returns:

  table new table of fn results

  ### See also:

  - map
  - zip_with

  ### Usage:

       --> {"123", "45"}, {a="123", b="45"}
       conc = bind (map_with, {lambda '|...|table.concat {...}'})
       conc {{1, 2, 3}, {4, 5}}, conc {a={1, 2, 3, x="y"}, b={4, 5, z=6}}

memoize (fn[, normfn=std.tostring])
  Memoize a function, by wrapping it in a functable.

  To ensure that memoize always returns the same results for the same arguments, it passes arguments to fn. You can specify a more sophisticated function if memoize should handle complicated argument equivalencies.

  ### Parameters:

  - fn func pure function: a function with no side effects
  - normfn normalize function to normalize arguments (default std.tostring)

  ### Returns:

  functable memoized function

  ### Usage:

      local fast = memoize (function (...) --[[ slow code ]] end)

nop ()
  No operation. This function ignores all arguments, and returns no values.

  ### See also:

  id

  ### Usage:

      if unsupported then vtable["memrmem"] = nop end

reduce (fn, d[, ifn=std.pairs], ...)
  Fold a binary function into an iterator.

  ### Parameters:

  - fn func reduce function
  - d initial first argument
  - ifn func iterator function (default std.pairs)
  - ... iterator arguments

  ### Returns:

  result

  ### See also:

  - foldl
  - foldr

  ### Usage:

       --> 2 ^ 3 ^ 4 ==> 4096
       reduce (std.operator.pow, 2, std.ielems, {3, 4})

zip (tt)
  Zip a table of tables. Make a new table, with lists of elements at the same index in the original table. This function is effectively its own inverse.

  ### Parameters:

  - tt table a table of tables

  ### Returns:

  table new table with lists of elements of the same key from tt

  ### See also:

  - map
  - zip_with

  ### Usage:

       --> {{1, 3, 5}, {2, 4}}, {a={x=1, y=3, z=5}, b={x=2, y=4}}
       zip {{1, 2}, {3, 4}, {5}}, zip {x={a=1, b=2}, y={a=3, b=4}, z={a=5}}

zip_with (fn, tt)
  Zip a list of tables together with a function.

  ### Parameters:

  - fn function function
  - tt table table of tables

  ### Returns:

  table a new table of results from calls to fn with arguments made from all elements the same key in the original tables; effectively the "columns" in a simple list of lists.

  ### See also:

  - map_with
  - zip

  ### Usage:

       --> {"135", "24"}, {a="1", b="25"}
       conc = bind (zip_with, {lambda '|...|table.concat {...}'})
       conc {{1, 2}, {3, 4}, {5}}, conc {{a=1, b=2}, x={a=3, b=4}, {b=5}}

## Types

normalize (...)
  Signature of a memoize argument normalization callback function.

  ### Parameters:

  - ... arguments

  ### Returns:

  string normalized arguments

  ### Usage:

       local normalize = function (name, value, props) return name end
       local intern = std.functional.memoize (mksymbol, normalize)

predicate (...)
  Signature of a filter predicate callback function.

  ### Parameters:

  - ... arguments

  ### Returns:

  boolean "truthy" if the predicate condition succeeds, "falsey" otherwise

  ### Usage:

       local predicate = lambda '|k,v|type(v)=="string"'
       local strvalues = filter (predicate, std.pairs, {name="Roberto", id=12345})

generated by LDoc 1.4.3 Last updated 2018-09-03 17:48:42