Differences

This shows you the differences between two versions of the page.

--- api:transforms [2016/06/20 17:25]
payonel
+++ api:transforms [2017/10/19 20:42]
payonel [Methods]
@@ Line 6: / Line 6: @@
 Methods
 ---------------------------
-  * ''transforms.sub(tbl: table, first: number, last: number or nil) table''
-  Functions identically to `string.sub`, even supporting negative indexes. Returns a sub table of `tbl` from `first` to `last`. Like `string.sub`, `first` and `last` can be negative indexes, and `last` can be omitted to include "the rest".
+All transforms methods expect to iterate over sequences (a.k.a lists, or arrays).
-  * ''transforms.first''
-  * ''transforms.find''
+All `first` and `last` arguments act in the same fashion as the `first` and `last` arguments used in `string` methods such as `string.sub`. That is, it accepts negative values, which work relative from the end. `first` defaults to 1, and `last` defaults to -1.
-  * ''transformas.partition''
-  * ''transformas.begins''
+  * `transforms.sub(tbl: table, first: number, last: number or nil): table`
-  * ''transforms.foreach'' or ''transforms.select''
-  * ''transforms.where''
+  Behaves similarly to `string.sub`. Returns a sub table of `tbl` from `first` to `last`.
-  * ''transforms.at''
+  * `transforms.first(tbl: table, predicate: function or table, first: number or nil, last: number or nil): number, number`
+  Returns the first index in `tbl` (between indexes `first` and `last`, inclusively) where `predicate` is satisfied. The 2nd return is also the ending index of the match. General examples will have the same two values, i.e. a match of 1. Technically, the `predicate` can return a 2nd return value to indicate where the pattern matching completed.
+** Note the predicate signature **
+  *  `predicate(element: any, index: number, tbl: table): any, number`
+  The predicate is called on each index. A falsely return means the predicate failed. A predicate generally returns true when `element` matches what is looked for. But the implementation of the predicate can choose to search later in `tbl` from `index`. The predicate can also choose to return the size of the match (for example it can return 1 is only 1 element matched, or return 2 if tbl[i+1] was also used to satisfy the predicate). `transforms.find` will then use the size returned in the range it returns.
+    example:
+```lua
+local tx = require("transforms")
+print( tx.first ( { 1, 1, 3, 2, 4, 7 }, function(e, i, tbl)
+  local evens = 0
+  for i=i,#tbl do
+    if tbl[i] % 2 == 0 then
+      evens = evens + 1
+    else
+      break
+    end
+  end
+  return evens > 0, evens
+end))
+```
+Result: `4    5`
+  * 'transformas.partition'
+  * 'transformas.begins'
+  * 'transforms.foreach' or 'transforms.select'
+  * 'transforms.where'
+  * 'transforms.at'
 Contents
 -----------
 {{page>api:contents&noheader&noeditbutton&nouser&nofooter}}