Vocabulary/zcapco

>> << Down to: Dyad Back to: Vocabulary

`Z: y`	Get Fold status

Rank Infinity -- operates on x and y as a whole -- WHY IS THIS IMPORTANT?

Returns information about the currently executing Fold.

Executed phrase	Meaning of result
`Z: 0`	The number of times `v` has started execution
`Z: 1`	The number of times `u` has started execution
`Z: 2`	The number of times a result of `u` has been moved to the overall result

`x Z: y`	Terminate Fold

Rank Infinity -- operates on x and y as a whole -- WHY IS THIS IMPORTANT?

Terminates Fold, in whole or part.

_2 Z: 0   NB. no-op
_2 Z: 1   NB. force termination of overrunning Fold

The phrases (x Z: 1) and (_3 Z: n) are the only ways to terminate F. and F: .

But the primitive Z: can prematurely terminate any Fold, or skip the production of wasted data in any given iteration of Fold.

Common Uses

1. Halt Unlimited Fold (F. or F:) after N iterations of Fold operand u or raise limit error.

   v=: {{
_3 Z: 20         NB. raise limit error if we've done 20 iterations (protect against infinite loop)
_2 Z: x <: Z:1   NB. terminate fold if we've done x iterations of u
>:y              NB. increment y
}}

   15 ] F: v 0   NB. increment y 15 times, collecting results
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15

   30 ] F: v 0   NB. here our "20 iterations" limit is exceeded
|fold limit, executing dyad ]F:(4 : ...)
|   30    ]F:v 0

2. Increase computational efficiency by aborting a wasteful computation.

Similar code to #1 except:

the x-argument of Z: should be an integer in the list: (_3 _2 _1 0 1).
the y-argument of Z: should be a boolean condition detecting a wasteful application of u and/or v.

More Information

The result of (x Z: y) is always $0 (an empty list).

If y is 0, no action is performed.
If y is 1, the action depends on x as shown in the table below.

Executed phrase	Effect
`_3 Z: n`	If the Fold has already started execution of `v` at least `n` times, abort the fold with a `fold limit` error. Otherwise continue. Useful to ensure that an unlimited fold (viz. `F.` or `F:`) does not run forever.
`_2 Z: 1`	Execution of the enclosing Fold terminates immediately, with the result being the result after the last execution of `u`. If nothing has been added to the overall result, `no result` is signaled.
`_1 Z: 1`	Execution of the current iteration terminates immediately. The next iteration begins with the next new value as `x`. The value of `y` in the next iteration is the result of the most recent execution of `v` that ran to completion. Nothing is added to the overall result for the current iteration.
`0 Z: 1`	Execution of the enclosing Fold continues, but the result of the current execution of `u` is ignored. For Fold Multiple, nothing is added to the overall result. For Fold Single, the overall result is left unchanged from the previous iteration.
`1 Z: 1`	Execution of the enclosing Fold continues but stops after the next completion of `u`.