. @ Amend, Amend At
Modify one or more items in a list.
| syntax | rank | semantics |
|---|---|---|
.[d; i; v; my] |
4 | amend items at depth with value v rank ≥2 |
@[d; i; v; my] |
4 | amend items at depth 1 with value v rank ≥2 |
.[d; i; u] |
3 | amend items at depth with unary value u |
@[d; i; u] |
3 | amend items at depth 1 with unary value u |
.[d; i; :; y] |
4 | replace items at depth |
@[d; i; :; y] |
4 | replace items at depth 1 |
Where
dis a list or a dictionary or a handle to oneiis a list of items in the domain ofdvis a value of rank n, andmyan atom, or list conformable toi, of rank n-1 with items in the right domain/s ofmuis a unary valueyis an atom or list conformable toi
if d is a
- variable, returns a copy of it with the items at
imodified - handle, modifies the items of its reference at
i, and returns the handle
Selection
The items in d that are to be replaced are selected by i just as in Apply, i.e. d . i and d@i.
Call the items selected by d . i or d@i the selection.
Amend Entire
If d is an atom other than a dictionary or a handle and i is an empty list, then all of d is modified.
If d is a list and i is nil, then all of d is amended, but one item at a time, as if i were key d.
In the case of a non-empty list i, the value u or v is evaluated once for every path generated from i, just as the above definition indicates.
However, if the index i is the empty list, i.e. (), then Amend is Amend Entire. That is, the entire value in d is replaced, in the quaternary .[d;();v;y] with v[d;y], or in .[d;();:;y] with y, as in d:y, and in the ternary .[d;();u] with u[d].
.[2 3; (); ,; 4 5 6]
2 3 4 5 6
Amend At
Exactly as for Apply At, @[d;i;… is everywhere syntactic sugar for .[d;enlist i;….
In the general case of a one-item list i
.[d;i;u;y]is identical to@[d;first i;u;y].[d;i;u]is identical to@[d;first i;u]
Definitions and examples that follow are written for . – adapt them for @.
Modification
In the quaternary, each item in the selection is replaced by the result of evaluating v on itself as the left argument and the corresponding item in y as the right argument.
In the Replace form (with the colon as third argument) each item in the selection is replaced by the corresponding item in y.
Replacement
The colon : acts here as syntactic sugar for the the function {[x;y] y} or, more simply, {y}.
In the ternary, each item in the selection is replaced by the result of evaluating u on it.
The new value/s of d . i are determined by the third argument, and whether i denotes a single path:
| 3rd argument | single path | general |
|---|---|---|
: |
y |
y . i |
u |
u[d . i] |
u'[d . i] |
v |
v[d . i; y . i] |
v'[d . i; y . i] |
Examples
Single path
If i is a non-negative integer vector then the selection is a single item at depth count i in d.
q)(5 2.14; "abc") . 1 2 / Index at depth 2
"c"
q).[(5 2.14; "abc"); 1 2; :; "x"] / replace at depth 2
5 2.14
"abx"
Cross sections
Where the items of i are non-negative integer vectors, they define a cross section.
The result can be understood as a series of single-path amends.
q)d
(1 2 3;4 5 6 7)
(8 9;10;11 12)
(13 14;15 16 17 18;19 20)
q)i:(2 0; 0 1 0)
q)y:(100 200 300; 400 500 600)
q)r:.[d; i; ,; y]
The following display of d adjacent to r provides easy comparison:
q)d q)r
(1 2 3;4 5 6 7) (1 2 3 400 600;4 5 6 7 500)
(8 9;10;11 12) (8 9;10;11 12)
(13 14;15 16 17 18;19 20) (13 14 100 300;15 16 17 18 200;19 20)
The shape of y is 2 3, the same shape as the cross-section selected by d . i. The (j;k)th item of y corresponds to the path (i[0;j];i[1;k]). The first single-path Amend is equivalent to:
d: .[d; (i . 0 0; i . 1 0); ,; y . 0 0]
(since the amends are being done individually, and the assignment serves to capture the individual results as we go), or:
d: .[d; 2 0; ,; 100]
and item d . 2 0 becomes 13 14,100, or 13 14 100.
The next single-path Amend is:
d: .[d; (i . 0 0; i . 1 1); ,; y . 0 1]
or
d: .[d; 2 1; ,; 200]
and item d . 2 1 becomes 15 16 17 18 200.
Continuing in this manner:
- item
d . 2 0becomes13 14 100 300, modifying the previously modified value13 14 100 - item
d . 0 0becomes1 2 3 400 - item
d . 0 1becomes4 5 6 7 500 - item
d . 0 0becomes1 2 3 400 600, modifying the previously modified value1 2 3 400
Replacement
d:((1 2 3; 4 5 6 7)
(8 9; 10; 11 12)
(13 14; 15 16 17 18; 19 20))
i:(2 0; 0 1 0)
y:(100 200 300; 400 500 600)
r:.[d; i; :; y]
The following display of d next to r provides easy comparison.
q)d q)r
(1 2 3;4 5 6 7) 600 500 / replaced twice; once
(8 9;10;11 12) (8 9;10;11 12)
(13 14;15 16 17 18;19 20) (300;200;19 20) / replaced twice; once; not
Note multiple replacements of some items-at-depth in d, corresponding to the multiple updates in the earlier example.
Unary value
The ternary replaces the selection with the results of applying u to them.
q)d
(1 2 3;4 5 6 7)
(8 9;10;11 12)
(13 14;15 16 17 18;19 20)
q)i
2 0
0 1 0
q)y
100 200 300
400 500 600
q)r:.[d; i; neg]
The following display of d next to r provides easy comparison.
q)d q)r
(1 2 3;4 5 6 7) (1 2 3;-4 -5 -6 -7)
(8 9;10;11 12) (8 9;10;11 12)
(13 14;15 16 17 18;19 20) (13 14;-15 -16 -17 -18;19 20)
Note multiple applications of neg to some items-at-depth in d, corresponding to the multiple updates in the first example.
The general case
In general, i can be
- an atom that is a valid index of
d, e.g. one ofkey d - a list representing paths to items at depth
count iind
The function proceeds recursively through i[0] and y as if they were the arguments of a binary atomic function, except that when arriving at an atom in i[0], that value is retained as the first item in a path and the recursion continues on with i[1] and the item-at-depth in y that had been arrived at the same time as the atom in i[0].
And so on, until arriving at an atom in the last item of i. At that point a path p into d has been created and the item at depth count i selected by p, namely d . p, is replaced by m[d . p;z] for binary m, or u[d . p] for unary u, where z is the item-at-depth in y that had been arrived at the same time as the atom in the last item of i.
The general case for binary v can be defined recursively by partitioning the index list into its first item and the rest:
Amend:{[d;F;R;v;y]
$[ nil ~ F; Amend[d; key d; R; v; y];
0 = count R; @[d; F; v; y];
@ F; Amend[d @ F; first R; 1_R; v; y];
Amend[;; R;;]/[d; F; v; y]}
Note the application of Over to Amend, which requires that whenever F is not an atom, either y is an atom or count F equals count y. Over is used to accumulate all changes in the first argument d.
Accumulate
Cases of Amend with a value u or v are sometimes called Accumulate because the new items-at-depth are computed in terms of the old, as in .[x; 2 6; +; 1], where item 6 of item 2 is incremented by 1.
Errors
| error | cause |
|---|---|
| domain | d is a symbol atom but not a handle |
| index | a path in i is not a valid path of d |
| length | i and y are not conformable |
| type | an atom of i is not an integer, symbol or nil |
Functional Amend
Integrate following with preceding!
Syntax: @[x;i;f]
Syntax: @[x;i;f;a]
Syntax: @[x;i;f;v]
Where
xis a list (or file symbol, see Tip)iis an int vector of indexes ofxfis a functionais an atom in the domain of the second argument offvis a vector in the domain of the second argument off
returns x with its values at indexes i changed.
For ind in til count i, x[i ind] becomes
expression x[i ind]
-----------------------------
@[x;i;f] f[x i ind]
@[x;i;f;a] f[x i ind][a]
@[x;i;f;v] f[x i ind][v ind]
q)d:("quick";"";"brown";"fox")
q)@[d;where"b"$count each d;,[;"..."]] / unary f
"quick..."
""
"brown..."
"fox..."
q)d:((1 2 3;4 5 6 7);(8 9;10;11 12);(13 14;15 16 17 18;19 20))
q)@[d;1 1 1;+;3] / binary f
((1 2 3;4 5 6 7);(17 18;19;20 21);(13 14;15 16 17 18;19 20))
Functions of rank higher than 2 can be applied by enlisting their arguments and using Apply.
Projections
For a general list x, omitting a or v when f is binary returns projections at the indexes i:
q)0N!@[("ssd";"bsd");0;+];
(+["ssd"];"bsd")
Do it on disk
Since V3.4 certain vectors can be updated directly on disk without the need to fully rewrite the file. Such vectors must have no attribute, be of a mappable type, not nested, and not compressed. e.g.
q)`:data set til 20;
q)@[`:data;3 6 8;:;100 200 300];
q)get`:data
0 1 2 100 4 5 200 7 300 9 10 11 12 13 14 15 16 17 18 19