@thi.ng/pointfree/array.d.ts

Pointfree functional composition / Forth style stack execution engine

import type { StackContext, StackFn } from "./api.js";
/**
 * Pushes a new empty array on the d-stack.
 *
 * @remarks
 * While it's easily possible to use `[]` as part of a stack program, the `list`
 * word is intended to be used as part of re-usuable {@link defWord} definitions
 * to ensure a new array is being created for every single invocation of the
 * word (else only a single instance is created due to the mutable nature of JS
 * arrays).
 *
 * Compare:
 *
 * ```js
 * import * as pf from "@thi.ng/pointfree";
 *
 * // using array literal within word definition
 * foo = pf.word([ [], 1, pf.pushl ])
 * pf.runU(foo)
 * // [ 1 ]
 * pf.runU(foo)
 * // [ 1, 1 ] // wrong!
 *
 * // using `list` instead
 * bar = pf.word([ pf.list, 1, pf.pushl ])
 * pf.runU(bar)
 * // [ 1 ]
 * pf.runU(bar)
 * // [ 1 ] // correct!
 * ```
 *
 * Stack effect: `( -- [] )`
 *
 * @param ctx -
 */
export declare const list: (ctx: StackContext) => StackContext;
/**
 * Pushes new empty JS object on d-stack.
 * Same reasoning as for {@link list}.
 *
 * Stack effect: `( -- {} )`
 *
 * @param ctx -
 */
export declare const obj: (ctx: StackContext) => StackContext;
/**
 * Pushes `val` on the LHS of array.
 *
 * Stack effect: `( val arr -- arr )`
 *
 * @param ctx -
 */
export declare const pushl: (ctx: StackContext) => StackContext;
/**
 * Pushes `val` on the RHS of array.
 *
 * Stack effect: `( arr val -- arr )`
 *
 * @param ctx -
 */
export declare const pushr: (ctx: StackContext) => StackContext;
/**
 * Removes RHS from array as new TOS on d-stack.
 * Throws error is `arr` is empty.
 *
 * Stack effect: `( arr -- arr arr[-1] )`
 *
 * @param ctx -
 */
export declare const popr: (ctx: StackContext) => StackContext;
export declare const pull: StackFn;
export declare const pull2: StackFn;
export declare const pull3: StackFn;
export declare const pull4: StackFn;
export declare const vadd: (ctx: StackContext) => StackContext;
export declare const vsub: (ctx: StackContext) => StackContext;
export declare const vmul: (ctx: StackContext) => StackContext;
export declare const vdiv: (ctx: StackContext) => StackContext;
/**
 * Splits vector / array at given index `x`.
 *
 * Stack effect: `( arr x -- [...] [...] )`
 *
 * @param ctx -
 */
export declare const split: (ctx: StackContext) => StackContext;
/**
 * Concatenates `arr2` onto `arr1`:
 *
 * Stack effect: `( arr1 arr2 -- arr )`
 *
 * @param ctx -
 */
export declare const cat: (ctx: StackContext) => StackContext;
/**
 * Similar to {@link cat}, but concatenates `arr1` onto `arr2`:
 *
 * Stack effect: `( arr1 arr2 -- arr )`
 *
 * @param ctx -
 */
export declare const catr: (ctx: StackContext) => StackContext;
/**
 * Generic array transformer.
 *
 * Stack effect: `( arr q -- ? )`
 *
 * Pops both args from d-stack, then executes quotation for each array
 * item (each pushed on d-stack prior to calling quotation). Can produce
 * any number of results and therefore also be used as filter, mapcat,
 * reduce...
 *
 * ```js
 * import { mapl, mul, run } from "@thi.ng/pointfree";
 *
 * // each item times 10
 * run([[1, 2, 3, 4], [10, mul], mapl])
 * // [ [ 10, 20, 30, 40 ], [], {} ]
 * ```
 *
 * Use for filtering:
 *
 * ```js
 * import { cond, drop, dup, even, mapl, run } from "@thi.ng/pointfree";
 *
 * // drop even numbers, duplicate odd ones
 * run([[1, 2, 3, 4], [dup, even, cond(drop, dup)], mapl])
 * // [ [ 1, 1, 3, 3 ], [], {} ]
 * ```
 *
 * Reduction:
 *
 * ```js
 * import { add, mapl, runU } from "@thi.ng/pointfree";
 *
 * // the `0` is the initial reduction result
 * runU([0, [1, 2, 3, 4], [add], mapl])
 * // 10
 * ```
 *
 * **Important**: {@link mapl} does not produce a result array. However,
 * there're several options to collect results as array, e.g.
 *
 * Use {@link mapll} to transform:
 *
 * @example
 * ```js
 * import { runU, mapll, mul } from "@thi.ng/pointfree";
 *
 * runU([[1, 2, 3, 4], [10, mul], mapll])
 * // [ 10, 20, 30, 40]
 * ```
 *
 * Collecting results as array is a form of reduction, so we can use
 * {@link list} to produce an initial new array and {@link pushr} to push each new
 * interim value into the result:
 *
 * @example
 * ```js
 * import { list, mapl, mul, pushr, runU } from "@thi.ng/pointfree";
 *
 * runU([list, [1, 2, 3, 4], [10, mul, pushr], mapl])
 * // [ 10, 20, 30, 40 ]
 * ```
 *
 * If the array size is known & not changed by transformation:
 *
 * @example
 * ```js
 * import { collect, mapl, mul, runU } from "@thi.ng/pointfree";
 *
 * runU([[1, 2, 3, 4], [10, mul], mapl, 4, collect])
 * // [ 10, 20, 30, 40 ]
 * ```
 *
 * @param ctx -
 */
export declare const mapl: (ctx: StackContext) => StackContext;
/**
 * Similar to {@link mapl}, but produces new array of transformed values.
 *
 * Stack effect: `( arr q -- arr )`
 *
 * @example
 * ```js
 * import { mapll, mul, runU } from "@thi.ng/pointfree";
 *
 * runU([[1, 2, 3, 4], [10, mul], mapll])
 * // [ 10, 20, 30, 40]
 * ```
 *
 * Filter / mapcat:
 *
 * ```js
 * import { cond, drop, dup, even, mapll, run } from "@thi.ng/pointfree";
 *
 * // drop even numbers, duplicate odd ones
 * run([[1, 2, 3, 4], [dup, even, cond(drop, dup)], mapll])
 * // [ [ [ 1, 1, 3, 3 ] ], [], {} ]
 * ```
 *
 * @param ctx -
 */
export declare const mapll: (ctx: StackContext) => StackContext;
/**
 * Convenience wrapper for {@link mapl} to provide an alternative stack layout
 * for reduction purposes:
 *
 * Stack effect: `( arr q init -- reduction )`
 */
export declare const foldl: StackFn;
/**
 * Pops TOS (a number) and then forms a tuple of the top `n` remaining
 * values and pushes it as new TOS. The original collected stack values
 * are removed from d-stack.
 *
 * Stack effect: `( ... n --- ... [...] )`
 *
 * @param ctx -
 */
export declare const collect: (ctx: StackContext) => StackContext;
/**
 * Higher order helper word to {@link collect} tuples of pre-defined size
 * `n`. The size can be given as number or a stack function producing a
 * number.
 *
 * Stack effect: `( ... -- [...])`
 *
 * @param n -
 */
export declare const defTuple: (n: number | StackFn) => StackFn;
export declare const vec2: StackFn;
export declare const vec3: StackFn;
export declare const vec4: StackFn;
/**
 * Higher order helper word to convert a TOS tuple/array into a string
 * using `Array.join()` with given `sep`arator.
 *
 * @param sep -
 */
export declare const defJoin: (sep?: string) => (ctx: StackContext) => StackContext;
export declare const join: (ctx: StackContext) => StackContext;
/**
 * Pushes length of TOS on d-stack.
 *
 * Stack effect: `( x -- x.length )`
 *
 * @param ctx -
 */
export declare const length: (ctx: StackContext) => StackContext;
/**
 * Replaces TOS with its shallow copy. MUST be an array or plain object.
 *
 * Stack effect: `( x -- copy )`
 */
export declare const copy: (ctx: StackContext) => StackContext;
/**
 * Reads key/index from object/array.
 *
 * Stack effect: `( obj k -- obj[k] )`
 *
 * @param ctx -
 */
export declare const at: (ctx: StackContext) => StackContext;
/**
 * Writes `val` at key/index in object/array.
 *
 * Stack effect: `( val obj k -- obj )`
 *
 * @param ctx -
 */
export declare const setat: (ctx: StackContext) => StackContext;
/**
 * Takes an array of keys and target object, then pops & binds deeper
 * stack values to respective keys in object. Pushes result object back
 * on stack at the end. Throws error if there're less stack values than
 * keys in given array.
 *
 * @example
 * ```js
 * import { bindkeys, runU } from "@thi.ng/pointfree";
 *
 * runU([1,2,3, ["a","b","c"], {}, bindkeys])
 * // { c: 3, b: 2, a: 1 }
 * ```
 *
 * Stack effect: `(v1 v2 .. [k1 k2 ..] obj -- obj )`
 *
 * @param ctx -
 */
export declare const bindkeys: (ctx: StackContext) => StackContext;
//# sourceMappingURL=array.d.ts.map