Lambda Words

In zeptoforth the user can define lightweight anonymous functions, known as lambdas, inline in other words with [: and ;], where [: starts compiling a lambda, and ;] finishes it. compiling the xt for the lambda as a literal into the containing word. Multiple lambdas can be nested. Note that lambdas have no headers, making them lighter-weight than normal words. Provided that all words compiled into them are themselves inlined, they can be inlined into other words.

[: and ;] are defined in src/common/forth/basic.fs, but the other words discussed here are defined in src/common/forth/lambda.fs.

lambda

These words are in the lambda module`.

There are two simple conditional combinators, namely:

qif

( ??? flag true-xt – ??? )

which takes f and true-xt, which is executed when f is non-zero; true-xt has the following signature:

( ??? – ??? )

qifelse

( ??? flag true-xt false-xt – ??? )

which takes f, true-xt, and false-xt; true-xt is executed when f is non-zero and false-xt is executed when f is zero. These have the following signature:

( ??? – ??? )

There are three simple looping combinators:

quntil

( ??? xt – ??? )

which takes xt and executes it repeatedly until it returns a non-zero value; xt has the following signature:

( ??? – ??? flag )

qagain

( ??? xt – ??? )

which takes xt and executes it repeatedly forever until an exception is raised; xt has the following signature:

( ??? – ??? )

qwhile

( ??? while-xt body-xt – ??? )

which in a loop first executes while-xt and, if it returns a non-zero value, then it executes body-xt and continues looping, else it exits the loop; while-xt has the signature:

( ??? – ??? flag )

and body-xt has the signature:

( ??? – ??? )

There are two counted looping combinators:

qcount

( ??? limit init xt – ??? )

which counts up with an increment of one from init until it reaches limit, not including it, executing xt at each step, passing it the current count; xt has the signature:

( ??? i – ??? )

qcount+

( ??? limit init xt – ??? )

which counts up or down with a variable increment from init until it reaches limit, not including it for counting up but including it for counting down, executing xt at each step, passing it the current count and receiving the increment/decrement for the next step; xt has the signature:

( ??? i – ??? increment )

There are the following combinators for iterating over arrays with with different-sized members:

citer

( ??? c-addr count xt – ??? )

which iterates over the byte array specified by c-addr and count, passing each byte from the lowest address to the highest to xt, which has the signature:

( ??? c – ??? )

hiter

( ??? h-addr count xt – ??? )

which iterates over the halfword array specified by h-addr and count, passing each halfword from the lowest address to the highest to xt, which has the signature:

( ??? h – ??? )

iter

( ??? addr count xt – ??? )

which iterates over the cell array specified by addr and count, passing each cell from the lowest address to the highest to xt, which as the signature:

( ??? x – ??? )

2iter

( ??? addr count xt – ??? )

which iterates over the double-cell array specified by addr and count, passing each double cell from the lowest address to the highest to xt, which as the signature:

( ??? d – ??? )

There are the following combinators for iterating over values from getters:

iter-get

( ??? get-xt count iter-xt – ??? )

which iterates over the cell values returned by get-xt when passed an index starting from 0 up to but not including count, passing them to iter-xt; get-xt has the signature:

( ??? i – ??? x )

and xt has the signature:

( ??? x – ??? )

2iter-get

( ??? get-xt count iter-xt – ??? )

which iterates over the double-cell values returned by get-xt when passed an index starting from 0 up to but not including count, passing them to iter-xt; get-xt has the signature:

( ??? i – ??? d )

and xt has the signature:

( ??? d – ??? )

There are the following combinators for finding indices of values in arrays:

citeri

( ??? c-addr count xt – ??? )

which iterates over the byte array specified by c-addr and count, passing each byte from the lowest address to the highest along with its index to xt, which has the signature:

( ??? c i – ??? )

hiteri

( ??? h-addr count xt – ??? )

which iterates over the halfword array specified by h-addr and count, passing each halfword from the lowest address to the highest along with its index to xt, which has the signature:

( ??? h i – ??? )

iteri

( ??? addr count xt – ??? )

which iterates over the cell array specified by addr and count, passing each cell from the lowest address to the highest along with its index to xt, which as the signature:

( ??? x i – ??? )

2iteri

( ??? addr count xt – ??? )

which iterates over the double-cell array specified by addr and count, passing each double cell from the lowest address to the highest along with its index to xt, which as the signature:

( ??? d i – ??? )

There are the following combinators for iterating over values from getters:

iteri-get

( ??? get-xt count iter-xt – ??? )

which iterates over the cell values returned by get-xt when passed an index starting from 0 up to but not including count, passing them along with their index to iter-xt; get-xt has the signature:

( ??? i – ??? x )

and xt has the signature:

( ??? x i – ??? )

2iteri-get

( ??? get-xt count iter-xt – ??? )

which iterates over the double-cell values returned by get-xt when passed an index starting from 0 up to but not including count, passing them along with their index to iter-xt; get-xt has the signature:

( ??? i – ??? d )

and xt has the signature:

( ??? d i – ??? )

There are the following combinators for mapping from one array to another array with different-sized members; note that two arrays may be the same array:

cqmap

( ??? src-addr dst-addr count xt – ??? )

which maps from one byte array src-addr to another byte array dst-addr with count elements using xt, where xt has the signature:

( ??? c – ??? c’ )

hqmap

( ??? src-addr dst-addr count xt – ??? )

which maps from one halfword array src-addr to another halfword array dst-addr with count elements using xt, where xt has the signature:

( ??? h – ??? h’ )

qmap

( ??? src-addr dst-addr count xt – ??? )

which maps from one cell array src-addr to another cell array dst-addr with count elements using xt, where xt has the signature:

( ??? x – ??? x’ )

2qmap

( ??? src-addr dst-addr count xt – ??? )

which maps from one double-cell array src-addr to another double-cell array dst-addr with count elements using xt, where xt has the signature:

( ??? d – ??? d’ )

qmap-get-set

( ??? get-xt count map-xt set-xt – ??? )

which maps from count single-cell elements generated by the getter get-xt with map-xt, and then passing the resulting values and their indices to set-xt, where get-xt has the signature:

( ??? i – ??? x )

and map-xt has the signature:

( ??? x – ??? x’ )

and set-xt has the signature

( ??? x’ i – ??? )

2qmap-get-set

( ??? get-xt count map-xt set-xt – ??? )

which maps from count double-cell elements generated by the getter get-xt with map-xt, and then passing the resulting values and their indices to set-xt, where get-xt has the signature:

( ??? i – ??? d )

and map-xt has the signature:

( ??? d – ??? d’ )

and set-xt has the signature

( ??? d’ i – ??? )

cqmapi

( ??? src-addr dst-addr count xt – ??? )

which maps from one byte array src-addr to another byte array dst-addr with count elements using xt with both each element and its index, where xt has the signature:

( ??? c i – ??? c’ )

hqmapi

( ??? src-addr dst-addr count xt – ??? )

which maps from one halfword array src-addr to another halfword array dst-addr with count elements using xt with both each element and its index, where xt has the signature:

( ??? h i – ??? h’ )

qmapi

( ??? src-addr dst-addr count xt – ??? )

which maps from one cell array src-addr to another cell array dst-addr with count elements using xt with both each element and its index, where xt has the signature:

( ??? x i – ??? x’ )

2qmapi

( ??? src-addr dst-addr count xt – ??? )

which maps from one double-cell array src-addr to another double-cell array dst-addr with count elements using xt with both each element and its index, where xt has the signature:

( ??? d i – ??? d’ )

There are the following combinators for filtering from one array to another array with different-sized members; note that the two arrays may be the same array:

qmapi-get-set

( ??? get-xt count map-xt set-xt – ??? )

which maps from count single-cell elements generated by the getter get-xt and their indices with map-xt, and then passing the resulting values and their indices to set-xt, where get-xt has the signature:

( ??? i – ??? x )

and map-xt has the signature:

( ??? x i – ??? x’ )

and set-xt has the signature

( ??? x’ i – ??? )

2qmapi-get-set

( ??? get-xt count map-xt set-xt – ??? )

which maps from count double-cell elements generated by the getter get-xt and their indices with map-xt, and then passing the resulting values and their indices to set-xt, where get-xt has the signature:

( ??? i – ??? d )

and map-xt has the signature:

( ??? d i – ??? d’ )

and set-xt has the signature

( ??? d’ i – ??? )

cfilter

( ??? src-addr dst-addr count xt – ??? count’ )

which filters from one byte array src-addr to another byte array dst-addr with count elements using xt, returning count’ elements filtered, where xt has the signature:

( ??? c – ??? flag )

hfilter

( ??? src-addr dst-addr count xt – ??? count’ )

which filters from one halfword array src-addr to another halfword array dst-addr with count elements using xt, returning count’ elements filtered, where xt has the signature:

( ??? h – ??? flag )

filter

( ??? src-addr dst-addr count xt – ??? count’ )

which filters from one cell array src-addr to another cell array dst-addr with count elements using xt, returning count’ elements filtered, where xt has the signature:

( ??? x – ??? flag )

2filter

( ??? src-addr dst-addr count xt – ??? count’ )

which filters from one double-cell array src-addr to another double-cell array dst-addr with count elements using xt, returning count’ elements filtered, where xt has the signature:

( ??? d – ??? flag )

filter-get-set

( ??? get-xt count filter-xt set-xt – ??? count’ )

which filters count single-cell elements from getter get-xt with filter-xt, and passes the filtered values and their ultimate indices to set-xt, returnining count’ elements filtered, where get-xt has the signature:

( ??? i – ??? x )

and filter-xt has the signature

( ??? x – ??? flag )

and set-xt has the signature

( ??? x i’ – ??? )

2filter-get-set

( ??? get-xt count filter-xt set-xt – ??? count’ )

which filters count double-cell elements from getter get-xt with filter-xt, and passes the filtered values and their ultimate indices to set-xt, returnining count’ elements filtered, where get-xt has the signature:

( ??? i – ??? d )

and filter-xt has the signature

( ??? d – ??? flag )

and set-xt has the signature

( ??? d i’ – ??? )

cfilteri

( ??? src-addr dst-addr count xt – ??? count’ )

which filters from one byte array src-addr to another byte array dst-addr with count elements using xt with both each element and its index, returning count’ elements filtered, where xt has the signature:

( ??? c i – ??? flag )

hfilteri

( ??? src-addr dst-addr count xt – ??? count’ )

which filters from one halfword array src-addr to another halfword array dst-addr with count elements using xt with both each element and its index, returning count’ elements filtered, where xt has the signature:

( ??? h i – ??? flag )

filteri

( ??? src-addr dst-addr count xt – ??? count’ )

which filters from one cell array src-addr to another cell array dst-addr with count elements using xt with both each element and its index, returning count’ elements filtered, where xt has the signature:

( ??? x i – ??? flag )

2filteri

( ??? src-addr dst-addr count xt – ??? count’ )

which filters from one double-cell array src-addr to another double-cell array dst-addr with count elements using xt with both each element and its index, returning count’ elements filtered, where xt has the signature:

( ??? d i – ??? flag )

filteri-get-set

( ??? get-xt count filter-xt set-xt – ??? count’ )

which filters count single-cell elements from getter get-xt along with their indices with filter-xt, and passes the filtered values and their ultimate indices to set-xt, returnining count’ elements filtered, where get-xt has the signature:

( ??? i – ??? x )

and filter-xt has the signature

( ??? x i – ??? flag )

and set-xt has the signature

( ??? x i’ – ??? )

2filteri-get-set

( ??? get-xt count filter-xt set-xt – ??? count’ )

which filters count double-cell elements from getter get-xt along with their indices with filter-xt, and passes the filtered values and their ultimate indices to set-xt, returnining count’ elements filtered, where get-xt has the signature:

( ??? i – ??? d )

and filter-xt has the signature

( ??? d i – ??? flag )

and set-xt has the signature

( ??? d i’ – ??? )

There are the following combinators for finding indices of values in arrays:

cfind-index

( ??? c-addr count xt – ??? i|-1 )

which iterates over the byte array specified by c-addr and count, passing each byte from the lowest address to the highest to xt, until it either reaches a value for which it returns a non-zero value, where then it returns the index of that byte, or if it reaches the end of the array, where then it returns -1; xt as the signature:

( ??? c – ??? flag )

hfind-index

( ??? h-addr count xt – ??? i|-1 )

which iterates over the halfword array specified by h-addr and count, passing each halfword from the lowest address to the highest to xt, until it either reaches a value for which it returns a non-zero value, where then it returns the index of that halfword, or if it reaches the end of the array, where then it returns -1; xt has the signature:

( ??? h – ??? flag )

find-index

( ??? addr count xt – ??? i|-1 )

which iterates over the cell array specified by addr and count, passing each cell from the lowest address to the highest to xt, until it either reaches a value for which it returns a non-zero value, where then it returns the index of that cell, or if it reaches the end of the array, where then it returns -1; xt has the signature:

( ??? x – ??? flag )

2find-index

( ??? addr count xt – ??? i|-1 )

which iterates over the double-cell array specified by addr and count, passing each double cell from the lowest address to the highest to xt, until it either reaches a value for which it returns a non-zero value, where then it returns the index of that double cell, or if it reaches the end of the array, where then it returns -1; xt has the signature:

( ??? d – ??? flag )

There are the following combinators for finding indices of values from getters:

find-get-index

( ??? get-xt count pred-xt – ??? i|-1 )

which iterates over the cell values returned by get-xt when passed indices starting from zero up to but not including count, passing each cell to xt, until it either reaches a value for which it returns a non-zero value, where then it returns the index of that cell, or if it reaches count, where then it returns -1; get-xt has the signature:

( ??? i – ??? x )

and pred-xt has the signature:

( ??? x – ??? flag )

2find-get-index

( ??? get-xt count pred-xt – ??? i|-1 )

which iterates over the double-cell values returned by get-xt when passed indices starting from zero up to but not including count, passing each double cell to xt, until it either reaches a value for which it returns a non-zero value, where then it returns the index of that double cell, or if it reaches count, where then it returns -1; get-xt has the signature:

( ??? i – ??? d )

and pred-xt has the signature:

( ??? d – ??? flag )

There are the following combinators for finding values in arrays:

cfind-value

( ??? c-addr count xt – ??? b|0 flag )

which iterates over the byte array specified by c-addr and count, passing each byte from the lowest address to the highest to xt, until it either reaches a value for which it returns a non-zero value, where then it returns the value of that byte and true, or if it reaches the end of the array, where then it returns 0 and false; xt as the signature:

( ??? c – ??? flag )

hfind-value

( ??? h-addr count xt – ??? h|0 flag )

which iterates over the halfword array specified by h-addr and count, passing each halfword from the lowest address to the highest to xt, until it either reaches a value for which it returns a non-zero value, where then it returns the value of that halfword and true, or if it reaches the end of the array, where then it returns 0 and false; xt has the signature:

( ??? h – ??? flag )

find-value

( ??? addr count xt – ??? x|0 flag )

which iterates over the cell array specified by addr and count, passing each cell from the lowest address to the highest to xt, until it either reaches a value for which it returns a non-zero value, where then it returns the value of that cell and true, or if it reaches the end of the array, where then it returns 0 and false; xt has the signature:

( ??? x – ??? flag )

2find-value

( ??? addr count xt – ??? d|0 flag )

which iterates over the double-cell array specified by addr and count, passing each double cell from the lowest address to the highest to xt, until it either reaches a value for which it returns a non-zero value, where then it returns the value of that double cell and true, or if it reaches the end of the array, where then it returns 0 and false; xt has the signature:

( ??? d – ??? flag )

There are the following combinators for finding values from getters:

find-get-value

( ??? get-xt count pred-xt – ??? x|0 flag )

which iterates over the cell values returned by get-xt when passed indices starting from zero up to but not including count, passing each cell to xt, until it either reaches a value for which it returns a non-zero value, where then it returns the value of that cell and true, or if it reaches count, where then it returns 0 and false; get-xt has the signature:

( ??? i – ??? x )

and pred-xt has the signature:

( ??? x – ??? flag )

2find-get-value

( ??? get-xt count pred-xt – ??? d|0 flag )

which iterates over the double-cell values returned by get-xt when passed indices starting from zero up to but not including count, passing each double cell to xt, until it either reaches a value for which it returns a non-zero value, where then it returns the value of that double cell and true, or if it reaches count, where then it returns 0 and false; get-xt has the signature:

( ??? i – ??? d )

and pred-xt has the signature:

( ??? d – ??? flag )