This shows you the differences between two versions of the page.
| Next revision | Previous revision Next revision Both sides next revision | ||
|
api:transforms [2016/06/20 17:24] payonel created |
api:transforms [2017/10/19 20:42] payonel [Methods] |
||
|---|---|---|---|
| Line 4: | Line 4: | ||
| The transforms library is set of utilities for working with indexed tables. It provides highly reusable special iterators that are at the core of `text` and `sh` command parsing. | The transforms library is set of utilities for working with indexed tables. It provides highly reusable special iterators that are at the core of `text` and `sh` command parsing. | ||
| - | * ''transforms.sub(tbl, first, last) table'' | + | Methods |
| + | --------------------------- | ||
| - | 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'' | + | |
| - | * ''transformas.partition'' | + | |
| - | * ''transformas.begins'' | + | |
| - | * ''transforms.foreach'' or ''transforms.select'' | + | |
| - | * ''transforms.where'' | + | |
| - | * ''transforms.at'' | + | |
| + | 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. | ||
| + | |||
| + | * `transforms.sub(tbl: table, first: number, last: number or nil): table` | ||
| + | |||
| + | Behaves similarly to `string.sub`. Returns a sub table of `tbl` from `first` to `last`. | ||
| + | |||
| + | * `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}} | ||