Iterators¶
--------- maps -------- --------- accumulators ---------- ' Each each / Over over Converge, Do, While ': Each Parallel peach \ Scan scan Converge, Do, While ': Each Prior prior \: Each Left /: Each Right ' Case
The iterators (once known as adverbs) are native higher-order operators: they take applicable values as arguments and return derived functions. They are the primary means of iterating in q.
Applicable value
An applicable value is a q object that can be indexed or applied to arguments: a function (operator, keyword, lambda, or derived function), a list (vector, mixed list, matrix, or table), a file- or process handle, or a dictionary.
For example, the iterator Over (written /
) uses a value to reduce a list or dictionary.
q)+/[2 3 4] /reduce 2 3 4 with +
9
q)*/[2 3 4] /reduce 2 3 4 with *
24
Over is applied here postfix, with +
as its argument.
The derived function +/
returns the sum of a list; */
returns its product.
(Compare map-reduce in some other languages.)
Variadic syntax¶
Each Prior, Over, and Scan applied to binary values derive functions with both unary and binary forms.
q)+/[2 3 4] / unary
9
q)+/[1000000;2 3 4] / binary
1000009
Postfix application¶
Like all functions, the iterators can be applied with Apply or with bracket notation. But unlike any other functions, they can also be applied postfix. They almost always are.
q)'[count][("The";"quick";"brown";"fox")] / ' applied with brackets
3 5 5 3
q)count'[("The";"quick";"brown";"fox")] / ' applied postfix
3 5 5 3
Only iterators can be applied postfix.
Regardless of its rank, a function derived by postfix application is always an infix.
To apply an infix derived function in any way besides infix, you can use bracket notation, as you can with any function.
q)1000000+/2 3 4 / variadic function applied infix
1000009
q)+/[100000;2 3 4] / variadic function applied binary with brackets
1000009
q)+/[2 3 4] / variadic function applied unary with brackets
9
q)txt:("the";"quick";"brown";"fox")
q)count'[txt] / unary function applied with brackets
3 5 5 4
If the derived function is unary or variadic, you can also parenthesize it and apply it prefix.
q)(count')txt / unary function applied prefix
3 5 5 4
q)(+/)2 3 4 / variadic function applied prefix
9
Glyphs¶
Six glyphs are used to denote iterators. Some are overloaded.
Iterators
- in bold type derive uniform functions;
- in italic type, variadic functions.
Subscripts indicate the rank of the value; superscripts, the rank of the derived function. (Ranks 4-8 follow the same rule as rank 3.)
glyph | iterator/s |
---|---|
' |
₁ Case; Each |
\: |
₂ Each Left ² |
/: |
₂ Each Right ² |
': |
₁ Each Parallel ¹ ; ₂ Each Prior ¹ ² |
/ |
₁ Converge ¹ ; ₁ Do ² ; ₁ While ² ; ₂ Reduce ¹ ² ; ₃ Reduce ³ |
\ |
₁ Converge ¹ ; ₁ Do ² ; ₁ While ² ; ₂ Accumulate ¹ ² ; ₃ Accumulate ³ |
Over and Scan, with values of rank >2, derive functions of the same rank as the value.
The overloads are resolved according to the following table of syntactic forms.
Two groups of iterators¶
There are two kinds of iterators: maps and accumulators.
- Maps
-
distribute the application of their values across the items of a list or dictionary. They are implicitly parallel.
- Accumulators
-
apply their values successively: first to the entire (left) argument, then to the result of that evaluation, and so on. With values of rank ≥2 they correspond to forms of map reduce and fold in other languages.
Application¶
A derived function, like any function, can be applied by bracket notation. Binary derived functions can also be applied infix. Unary derived functions can also be applied prefix. Some derived functions are variadic and can be applied as either unary or binary functions.
This gives rise to multiple equivalent forms, tabulated here.
Any function can be applied with bracket notation or with Apply.
So to simplify, such forms are omitted here in favour of prefix or infix application.
For example, u'[x]
and @[u';x]
are valid, but only (u')x
is shown here.
(Iterators are applied here postfix only.)
The mnemonic keywords each
, over
, peach
, prior
and scan
are also shown.
value rank |
syntax | name | semantics |
---|---|---|---|
1 2 3+ |
(u')x , u each x x b'y v'[x;y;z;…] |
Each | apply u to each item of x apply g to corresponding items of x and y apply v to corresponding items of x , y , z … |
2 | x b\:d |
Each Left | apply b to d and items of x |
2 | d b/:y |
Each Right | apply b to d and items of y |
1 | (u':)x , u peach x |
Each Parallel | apply u to items of x in parallel tasks |
2 | (b':)y ,b prior y ,d b':y |
Each Prior | apply b to (d and) successive pairs of items of y |
1 | int'[x;y;…] |
Case | select from [x;y;…] |
1 | (u/)d , (u\)d |
Converge | apply u to d until result converges |
1 | n u/d , n u\d |
Do | apply u to d , n times |
1 | t u/d , t u\d |
While | apply u to d until t of result is 0 |
1 2 3+ |
(b/)y , b over y d b/y vv/[d;y;z;…] |
Over | reduce a list or lists |
1 2 3+ |
(g\)y , g scan y d g\y vv\[d;y;z;…] |
Scan | scan a list or lists |
Key:
d: data
int: int vector n: int atom ≥0
v: value t: test value
u: unary value y: list
b: binary value x: list