Vocabulary/curlyrt
>> << Down to: Dyad Back to: Vocabulary Thru to: Dictionary
m} y Composite Item Adverb
Rank Infinity -- operates on x and y as a whole -- WHY IS THIS IMPORTANT?
Create an array having the shape of an item of y that's a composite of the items of y.
Each atom of operand m selects an atom from the corresponding positions of the items of y
] y=: 'abcde' ,: 'ABCDE' abcde ABCDE 0 1 0 0 1 } y NB. for each atom of m, choose an atom from the items of y aBcdE
- Operand m must have the same shape as an item of y.
- Argument y meanwhile is of course a list of items of the same shape as m.
- Phrase m}y has the shape of m, but it is a composite:
Phrase m} y is equivalent to m {"0 1&.|: y , with the restriction that m must be numeric.
Common Uses
The only reason to use m} y is one of efficiency:
- either you want to avoid the transposes of m {"0 1&.|: y
- or you want to use one of the Special Combinations.
1. Create a composite item in place
a =: 'ABC' b =: 'abc' a =: 0 1 1} a ,: b a Abc
This form, where m} y appears in an assignment, is handled by special code that modifies a without first making a copy. Sentences taking advantage of this feature are very restricted in form.
Some other assignments using m} y are not in-place but avoid copying arguments. They are likewise very restricted in form.
2. Create a composite item without transposing m and y
] a =: i. 2 3
0 1 2
3 4 5
] b =: 100 + a NB. Two arrays
100 101 102
103 104 105
] c =: 0 1 0 ,: 1 1 0 NB. selector
0 1 0
1 1 0
c} a ,: b NB. composite item
0 101 2
103 104 5
c {"0 1&.|: a,:b NB. equivalent
0 101 2
103 104 5
3. Scatter-point replace using a Boolean selector:
]mat=. _5]\'abcdefghijklmnopqrstuvwxy' abcde fghij klmno pqrst uvwxy (mat e. 'aeiou') } mat,:'*' NB. Replace vowels *bcd* fgh*j klmn* pqrst *vwxy (mat e. 'aeiou') } mat,:toupper mat NB. Upper-case vowels AbcdE fghIj klmnO pqrst Uvwxy
Details
1. Operand m can be a gerund (v0`v1`v2) or (v1`v2), in which case m}y is executed as (v1 y)} (v2 y) . This form is not executed in place.
2. In-place assignment requires that 1 = 3!:0 myphrase , that is, the internal type of myphrase is Boolean.
It does not suffice for the atoms of myphrase to consist only of 0 or 1 — the actual type must be Boolean!
3. An obsolete form of Composite Items: (u} y) was used in early versions of J.
where operand u is a verb. Its use is deprecated in favor of m} y.
Oddities
1. Verb m} gives index error when y has only 1 item
(,0)} ,. 5 |index error | (,0)},.5 (,0)} 2 $ ,. 5 5
Use These Combinations
Combinations using m} y that have exceptionally good performance include:
What it does Type;
Precisions;
RanksSyntax Variants;
Restrictions
Benefits;
Bug Warnings
Composite item the x arrays are the same precision and not boxed, extended integer, or rational name =: i} x0,x1,...,xm,:xn =. in place of =:
If there are 2 x's, i may be Boolean or integer, but if more than 2 x's, i must be integer.
No parentheses allowedavoids catenation and lamination Composite item in place b is Boolean; x and name are the same precision and not boxed, extended integer, or rational name =: b} x,:name
name =: b} name,: x
Must be same name either side.
No parentheses allowed
avoids making a new copy of name
x m} y Amend Adverb
Rank Infinity -- operates on [x and] y as a whole -- WHY IS THIS IMPORTANT?
x m} y amends y by creating a new noun that is a copy of y with the locations m replaced by new values x
'gw' 0 3} 'cross' NB. Replace items 0 and 3 with 'g' and 'w' respectively grows
Because } is an adverb creating a verb,
the amendment process uses the operand m and the arguments x and y.
Thus there are 3 parts to the amendment.
m} is executed to produce an anonymous verb that is executed on the arguments x and y.
The anonymous verb has access to the value of m.
This resembles assignment to an index of an array in other languages. But x m} y can assign many indexes at once.
It also creates a new copy of the entire array y.If you modify only a small portion of a very large array, use the in-place form given below.
x m} y is used in J much less than you would think, considering the importance of in-place array modification in other languages.
Operand m gives the positions to be modified, and argument x the values to put there. In the simplest case there is only one position
y =: 'abcdefghijklmnop' y =: '*' 2} y NB. Modify position 2 y ab*defghijklmnop
Note, however, that a single atom in m refers to an item of y
] y =: _4 ]\ 'abcdefghijklmnop' abcd efgh ijkl mnop y =: '*' 2} y NB. Now position 2 is a list y abcd efgh **** mnop
Operand m may specify more than one target item of y
y =: 'abcdefghijklmnop' y =: '*' 0 2 4 6} y y *b*d*f*hijklmnop
Each atom of m specifies a selection from y, just as with x { y . Thus the above m has 4 selections: 0 2 4 6 .
Each selected item can be assigned a different value. The values in x must have the same shape as a cell of the selected portion of the array y. If x has lower rank than the selected part of y, it is replicated as needed.
Details below. In the previous example x (an atom) matched the shape of a 0-cell of the selection.
y =: 'abcdefghijklmnop' y =: 'ABCD' 0 2 4 6} y y AbBdCfDhijklmnop
Operand m can select from multiple axes
This is like multidimensional indexing in other languages.
] y =: _4 ]\ 'abcdefghijklmnop' abcd efgh ijkl mnop y =: '*' (<2 1)} y y abcd efgh i*kl mnop
Operand m can make multiple selections from multiple axes to select a region of the array to be modified
y =: _4 ]\ 'abcdefghijklmnop' y =: '*' (<0 2;3 1)} y NB. Modify rows 0 &2, columns 3&1 y a*c* efgh i*k* mnop
If operand m is a numeric array of rank > 1, it specifies a scatter-modify: each 1-cell of m is the index list of a cell of y. All the cells addressed by rows of m are replaced by cells of x.
Thus the 1-frame of m gives the frame of the selection.
y =: _4 ]\ 'abcdefghijklmnop' y =: '*' (2 2$3 2 1 1)} y NB. Multidimensional m; each row selects a cell. Selection is 2 0-cells y abcd e*gh ijkl mn*p
Argument x can give the new value for atoms independently
y =: _4 ]\ 'abcdefghijklmnop' y =: 'AB' (<0 2;3 1)} y NB. Store 'AB' into position 3&1 of each of rows 0&2 y aBcA efgh iBkA mnop y =: _4 ]\ 'abcdefghijklmnop' ]x =: 2 2$ 'ABCD' NB. A different value for each modified atom AB CD y =: x (<0 2;3 1)} y y aBcA efgh iDkC mnop
y =: _4 ]\ 'abcdefghijklmnop' y =: 'AB' (2 2$3 2 1 1)} y NB. Multidimensional m; each row selects a cell. Selection is 2 0-cells. A cell of x goes into each y abcd eBgh ijkl mnAp
The examples so far have used assignment in place, where the result of x m} y is assigned back to the original y. But this is not essential. The result of (x m} y) is a new modified array, always having the same shape as y, that can be used like any other array
'*' 2} 'abcdefgh' NB. Create an array and modify it. The modified array is the result. ab*defgh
Common uses
1. When converting seconds to hours/minutes/seconds, replace the first number in the base (HMS) with 0 to allow unlimited hours
HMS =: 24 60 60 HMS #: 96400 NB. this gives hours mod 24 2 46 40 ((0) 0} HMS) #: 96400 NB. unlimited hours... 26 46 40 (0) 0} HMS NB. ...by using modified base 0 60 60
2. Force a 1 into the last position of a list of frets, to avoid losing text
text =. 'Mr. Jones and Mr. Smith are here. Let them in.' ] frets =. '. ' E. text NB. Find the ends of sentences 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 1 0 0 0 0 0 0 0 0 0 0 0 0 0 0 frets <;.2 text NB. Box the sentences. Unfortunately the bit at the end is lost. +---------------------------------+ |Mr. Jones and Mr. Smith are here.| +---------------------------------+ ((1) _1} frets) <;.2 text NB. Stuff a 1 into the last position +---------------------------------+--------------+ |Mr. Jones and Mr. Smith are here.| Let them in.| +---------------------------------+--------------+ (1) _1} frets 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 1 0 0 0 0 0 0 0 0 0 0 0 0 0 1
3. Replace a single box in a list of boxes
]w =: ;:'The quick brown fox rested.'
+---+-----+-----+---+-------+
|The|quick|brown|fox|rested.|
+---+-----+-----+---+-------+
(,&'ish' each 2 { w) 2} w
+---+-----+--------+---+-------+
|The|quick|brownish|fox|rested.|
+---+-----+--------+---+-------+
4. Replace a subarray with another of the same shape
]a=. i.6 6
0 1 2 3 4 5
6 7 8 9 10 11
12 13 14 15 16 17
18 19 20 21 22 23
24 25 26 27 28 29
30 31 32 33 34 35
]b=. 3 3$100 200 300 400 500 600
100 200 300
400 500 600
100 200 300
b (<2 3 4;1 2 3)}a NB. specifying the perimeter of b's new location within a
0 1 2 3 4 5
6 7 8 9 10 11
12 100 200 300 16 17
18 400 500 600 22 23
24 100 200 300 28 29
30 31 32 33 34 35
am=. {{ x (<m <@(+i.)"0 $x)} y }} NB. abstracting the logic
b 2 1 am a NB. and specifying only the coordinate of b's lowest corner, yielding the same result
0 1 2 3 4 5
6 7 8 9 10 11
12 100 200 300 16 17
18 400 500 600 22 23
24 100 200 300 28 29
30 31 32 33 34 35
am works for x and y with any rank.
More Information
1. You can change portions of a noun in place (that is, without making a new copy of the noun), when no harm can come from doing so. The most common example of this is modification to a name that is about to be reassigned. Our examples have emphasized that form.
In this form of in-place modification you immediately assign the result of x m} namedy to the same name, so that the previous value of namedy can never again be used. Only in that case is it safe for J to create the new noun in the same location in memory as the old one.
With big arrays, amendment without in-place assignment can be colossally inefficient
bigarray =: ] 5 (5)} bigarray NB. same result as above, but 100,000 times slower
Other places where in-place modification can be performed are discussed here.
2. If m is a numeric array of rank > 1, each row of m gives the index list of a cell of y to be modified. In other words, m is interpreted as if it were (<m).
3. If operand m is boxed, it must be an atom.
For compatibility, select other forms are also recognized.
The locations of y that will be altered are those that would be selected by m { y .
subject to the rule above that numeric arrays m are boxed first
4. Argument x must have the shape of a cell of m{y
x is replicated as needed to the shape of m{y
y =: i. 2 3
100 (0}) y NB. `x` (an atom) has the shape of a 0-cell of m{y, and is replicated
100 100 100
3 4 5
100 101 (0}) y NB. `x` is a 2-atom list, but m{y is a 3-atom list
|length error
| 100 101 (0})y
100 101 102 (0}) y NB. `x` is a 3-atom list, and so is m{y
100 101 102
3 4 5
100 101 102 (0 2}) i. 3 3 NB. `x` is a 3-atom list, m{y has shape 2 3, so x is replicated
100 101 102
3 4 5
100 101 102
100 101 (<(i. 2 2);0)} i. 4 4 NB. m{y has shape 2 2, x is replicated
100 1 2 3
101 5 6 7
100 9 10 11
101 13 14 15
5. If the selections specified by the atoms of m overlap, the amendments are applied in order, leaving the last one as the survivor
(Don't rely on this behavior in future versions of J!)
(100 200) (<1;2 2)} i. 3 3 0 1 2 3 4 200 6 7 8
6. Operand m may be a gerund v0`v1[`v2], in which case x v0`v1[`v2]} y executes as
(x v0 y) (x v1 y)} (x v2 y)
Note: all the verbs v0 v1 v2 are executed dyadically. v2 is usually omitted, in which case ] is used so that the entire y is amended.
This form of x m} y is often useful in tacit verbs. The modification is performed in-place if possible.
Apply a "substring;position couple": x (x -: substring;starting-position) to a given string y
CASE 1:
X=: 'CDEFG' M=: 2 3 4 5 6 Y=: 'abcdefghijklmnopqrstuvwxyz' X M} Y abCDEFGhijklmnopqrstuvwxyz
CASE 2:
x =: 'CDEFG';2 NB. the "substring;starting-position" couple
y =: 'abcdefghijklmnopqrstuvwxyz' NB. the target string
v0=: 4 : '0 {:: x' NB. return the substring from the couple: x
v1=: 4 : 0 NB. return the list of indexes in y to amend
'substring startpos' =. x
startpos + i. #substring
)
v2=: ] NB. simply return y from the phrase: x v2 y
(x v0 y) ; (x v1 y) ; (x v2 y) NB. <--> X;M;Y in CASE 1 (Just checking for equivalence)
+-----+---------+--------------------------+
|CDEFG|2 3 4 5 6|abcdefghijklmnopqrstuvwxyz|
+-----+---------+--------------------------+
g =: v0`v1`v2 NB. assign the gerund to a pronoun: 'g'
type 'g'
+----+
|noun|
+----+
x g} y NB. do the amend
abCDEFGhijklmnopqrstuvwxyz
x v0`v1`v2} y NB. --or use gerund phrase itself directly
abCDEFGhijklmnopqrstuvwxyz
7. If argument y has rank = 1 and operand m is a numeric array of rank > 1, then to avoid interpreting an amend operation as scatter-modify, box m twice.
x=. 'ABC'
y =: 25 $ '.'
m1=. 2 3 4 ,: 8 11 13 NB. rank(m)=2
x m1} y NB. not supported since J903
|length error
| x m1}y
x (<<m1)} y NB. selects m1 from the first axis
..ABC...A..B.C...........
] m2=. _2 3 {."2 i. 2 3 4 NB. rank(m)=3
4 5 6
8 9 10
16 17 18
20 21 22
x m2} y NB. not supported since J903
|length error
| x m2}y
x (<<m2)} y NB. a workaround
....ABC.ABC.....ABC.ABC..
<^:2"_1 m2 NB. valid location
+--------+----------+
|+------+|+--------+|
||4 5 6|||16 17 18||
||8 9 10|||20 21 22||
|+------+|+--------+|
+--------+----------+
8. For compatibility with earlier versions of J, in two special forms boxed m may be an array. These forms are
- (x (<"0 array)} y) which is treated as (x (<<array)} y)
- (x (<"1 array)} y) which is treated as (x (<array)} y)
These forms are deprecated and are slower than the equivalents.
Details
1. A verb form of Amend: (x u} y) was used in early versions of J.
where operand u is a verb. x m} y is normally used instead, except in cases where operations on individual atoms are needed.
2. x (<<<m)} y, which specifies complementary indexing, sorts m. Because m is usually short or in order, insertion sort is used. If you have large unordered m, you should sort it first.
3. To modify a contiguous section of y, use u&.(m&{) y where m selects the portion of y to be modified. The modification is done in place if possible.
Use These Combinations
Combinations using x m} y that have exceptionally good performance include:
What it does Type;
Precisions;
RanksSyntax Variants;
Restrictions
Benefits;
Bug Warnings
Amend in place not boxed, extended integer, or rational name =. x i} name
name =. x (i}) name
name =. name i}~ x
or if y is an unnamed intermediate result=: in place of =.
Must be same name either side.
Parentheses allowed around x and i onlyavoids making a new copy of name