From 3afd4a01bc43f804b1eb77c5ba41974c9a1563e7 Mon Sep 17 00:00:00 2001 From: "Alex A. Naanou" Date: Fri, 8 Jul 2022 18:58:23 +0300 Subject: [PATCH] docs... Signed-off-by: Alex A. Naanou --- README.md | 29 ++++++++++++++++++++++++++++- 1 file changed, 28 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 55e178a..bebc234 100644 --- a/README.md +++ b/README.md @@ -2,7 +2,12 @@ Utility library implementing tooling to make stoppable functions... -XXX concept and theory of operation... +This library enables the user to drop out of a function/generator without the +need to thread the result through the call stack. This is in concept similar to +executing `return ..` from a nested loop to terminate and return from a function +but `stoppable.js` allows us to do the same from a nested set of function calls. +This is also similar to _Python_'s `raise StopIteration` approach to stopping +iteration. - [stoppable.js](#stoppablejs) - [Install / import](#install--import) @@ -86,6 +91,28 @@ var func = stoppable(function(){ var value = func() // -> 'something' ``` +Dropping out of recursion avoiding threading the result up the chain: +```javascript + +// Note that we split the recursive part and the interface part, this is done +// to keep the STOP catching only to the top level and thus avoid threading +// the result back up the recursion... +var _find = function(L, e){ + if(L.length == 0){ + throw stoppable.STOP(false) } + if(L[0] == e){ + throw stoppable.STOP(true) } + // look further down... + _find(L.slice(1), e) } + +var find = stoppable(_find) + +find([1,2,3,4,5,6,7], 6) // -> true +``` + +For more examples see [`type.js`' `Array.prototype.smap(..)` and friends](https://github.com/flynx/types.js#arraysmap--arraysfilter--arraysreduce--arraysforeach). + + ### Async function ```javascript