The A Project->Overview of A->Language Reference->Non-scalar Fns
Non-scalar Fns
Home
First Encounter
Current Status
Getting Started
Examples
Mississippi
Overview of A
Structure of Data
Syntax
Relation to other APLs
Language Reference
Non-scalar Fns
Numbers
Control Statements
Files
Timing
System Fns and Vars Functions Where next
Quibbles
Materials

Vector Home

Nonscalar Primitive Functions

This page has been reproduced from original A+ documentation provided by Morgan Stanley at www.aplusdev.org. Copyright remains with the authors.

As noted earlier, the term integer indicates here a domain of values and a particular internal representation. The term restricted whole number refers to the same domain of values when both integer and floating-point representations are allowed. The floating-point representations need only be tolerably equal to integers.

Classification of Nonscalar Primitive Functions

Although (except for Beam and Time) they are listed alphabetically in this chapter, for convenient reference, the A+ nonscalar primitive functions can be grouped, among many other ways, in these eight categories:

• informational functions: Shape, Count, Depth, Type;
• structural functions: Reshape, Interval, Restructure, Reverse, Rotate, Transpose, Transpose Axes, Ravel, Item Ravel, Enclose, Disclose, Rake, Raze, Partition, Take, Drop, Replicate, Expand, Catenate, Laminate;
• selection functions: Pick, Choose, Bracket Indexing, Right, Left, Null, Separate Symbols;
• computational functions: Matrix Inverse, Solve, Deal, Pack, Unpack, Encode, Decode;
• comparison functions: Match, Member, Find, Bins, Grade up, Grade down, Partition Count;
• format and representation functions: Format, Default Format, Cast;
• specificational functions: Assignment, Append, Bracket Indexing Selective Assignment, Replace All, Selective Assignment;  Beam;
• evaluative, display, and control functions: Execute, Execute in Context, Protected Execute, Value, Value in Context, Result, Signal, Print, Stop;  Time.

Common Error Reports

Multiple errors elicit but one report. If an error report in the following list is issued, then the ones preceding it do not apply. Five reports are common to all nonscalar primitive functions:

• parse: this error class includes valence errors that result from three or more arguments in braces;
• value: an argument has no value;
• nondata: an argument is a function or some other nondata object;
• wsfull: the workspace is currently not large enough to execute the function in; a bare left arrow (ű), which dictates resumption of execution, causes the workspace to be enlarged if possible;
• interrupt (not an error): the user pressed c twice (once if A+ was started from a shell) while holding the Control key down.
Except where noted, inappropriate omission or inclusion of a left argument results not in a valence error report but in the invocation of the function or operator that shares the function symbol.

Function Definitions

Assignment xűa and (x)űa

Arguments and Result
The right argument a is any array or function expression (see "Function Expressions"). The left argument is the target of the assignment. x represents a valid user name. The explicit result is equal to a; it is not displayed in an Emacs session, unlike other explicit results, unless it is the result of an expression group.

Definition
The explicit result is the value a if a is an array, and otherwise a function expression identical to a. The side effect is to assign the value or function expression a to the object x. For a function expression, note that it is the function that is assigned to the target, not the name of the function. See also "Selective Assignment".

The two forms of Assignment are equivalent when used outside function and operator definitions, but have different meanings inside if x is an unqualified name. Inside a function or operator definition, any appearance of xűa means that x will be a local variable, while, in the absence of that form, the form (x)űa can be used to assign a value to the global variable x, whose context will be the context in which the function was defined.

Assignment, in any form, cannot be the operand of an operator.

Strand Assignment

Several ordinary assignments can be incorporated into one by means of strand assignment. For example:

(a;c.b;f;d;d)ű('ABC';10+É3 4;+.«;2;5)
Each item of the right argument is disclosed and assigned to the corresponding name on the left. Note that f becomes a function scalar in this example, not a function, and that d ends up with the value 5. After all the individual assignments have been made, the saved values for any dependencies among the targets are marked valid. Strand assignment is important when working with dependencies. See the discussion of commit and cancel for sets of dependencies in "
Cyclic Dependencies". Strands are not permitted as targets of Selective Assignments.

The left argument must appear in strand notation. The right argument, therefore, must be a vector (of the same length as the left argument) or a scalar, but, since it is its value that is used, it can appear in any form, and, since Disclose accepts a simple argument, it can be a simple vector.

This example demonstrates that the righthand side is evaluated right to left and then the assignments are made left to right:

aű1; bű2;
f{s;d;i;p;c;v}:Őv
(a;b)ű(b Ý `a`b _scbˇ <(f;); aű3)
`a
`b
Strand Assignment does not trigger a screen update until the interpreter has made the assignments for all the variables involved. This is done in order to avoid problems which could occur when several columns of a displayed table object, including the first, are being updated, with changed lengths.

Value and Value in Context Assignment

Both Value and Value in Context can be used in targets, viz., (c%x)űa and (%x)űa, where c and x are any expressions producing simple scalar symbols. The form (k%ˇy)űa can also be used; it has the same effect as Strand Assignment, but is more flexible, since the statement does not involve a fixed number of variables with fixed names. The latter form cannot be combined with Selective Assignment in any way. See the Strand Assignment description regarding the timing of screen updates.

The context for the object of a Value Assignment is always the current context, so if the Assignment is in a function, the context is the one in which the function was called or the one which the function set before executing the Value Assignment. The use of these functions in assignment is important for working with callback functions; see the "Callback Functions" chapter.

Bins yčx

Arguments and Result
The left argument is a simple numeric or character array; its items must be in ascending order (no duplicates) for a meaningful result. (Ascending order has the Grade-up meaning: items compared lexicographically, i.e., leading elements in their ravels compared first, without comparison tolerance, and following elements compared only in the case of ties; and alphabetic characters sorted in accordance with their ASCII codes, which are shown in "Graphic Characters for Atomic Vector".) The right argument, x, is of the same general type as y, and its ˘1+ŇŇy trailing axes must have length 1ŐŇy. The result is an array of integers whose shape is defined by the A+ expression (-0Ó(ŇŇy)-1)ŐŇx.

Definition
The idea is to partition x into cells of the same shape as the items of y and then to find where each cell falls among those items. Specifically, partition x in the same way as for Find: viz., into cells of rank 0Ó(ŇŇy)-1. For each such cell, the result has one element, whose value is the number of items of y which the cell is greater than, in the sense described in the "Arguments and Result" subsection.

For a numeric vector y, each element of the result indicates the subinterval of y into which the corresponding element of x falls, without using comparison tolerance. That is, if i#r is an element of the result r, its value can be determined from the "Bins for Numeric Vectors" table.

One use for Bins is preparing data for a bar graph.

Each of the following reports is issued only if there is no parse or value error (see "Common Error Reports") and none of the reports preceding it on this list applies:

• a type error is reported if an argument is not simple or if the arguments are not of the same general type;
• a rank error is reported if the rank of x is less than that of the items of y, so the partitioning fails;
• a length error is reported if the items of y and the cells into which x is partitioned have different shapes.
Examples
˘1 0 1 č 0.3 ˘0.3 ˘2 .1 1 5
2 1 0 2 2 3

vű?5000Ň1000     ă sample set of random numbers
ă Put in cells; count how many in each cell, showing distribution of the random numbers:
+/((100«1+É10)čv)Ę.=É10
494 480 477 533 506 472 521 512 524 481
ă An equivalent but slightly faster way; shows distribution of the set:
Ř+/ˇ(<(100«1+É10)čv)=ˇÉ10
494 480 477 533 506 472 521 512 524 481

Bracket Indexing x[a;b;...;c]

Arguments and Result
x is any array, and a, b, ... , c are simple arrays of restricted whole numbers, or absent or the Null. The number of semicolons must be less than the rank of x, or zero. Roughly speaking, the shape of the result is the shape of x with the shapes of a, b, ... , c substituted for the corresponding dimensions.

More precisely: If x is a scalar, the form is x[], and the result is x. Otherwise, the shape of the result is determined as follows. Let Ra be Ňa, Rb be Ňb, etc., except that if the ith one, d, is absent or the Null, let Rd be i#Ňx. If there are k-1 semicolons, the shape of the result is Ra,Rb, ... ,Rc,kŐŇx.

Definition
Bracket Indexing is a way of selecting elements from an array. Semicolons separate indices for different axes. The result has the shape described above. For each axis, a corresponding argument can give an array of indices. For an axis for which no argument or a Null argument is given, the vector 0,1, ... ,n-1 is used, where n is the length of that axis. Elements are selected by taking one index from each index array. The order of selection is determined by running through the index arrays in odometer fashion: all of the rightmost for the first combination of the rest, then all of the rightmost for the second combination of the rest, and so on. Duplicate selections are permitted.

Each of the following reports is issued only if there is no parse or value error (see "Common Error Reports") and none of the reports preceding it on this list applies:

• rank: the number of unenclosed semicolons within the brackets is equal to or greater than the rank of x and x is nonscalar, or x is a scalar and there is something (anything) between the brackets;
• type: a member of the index group (a, b, ... , or c) is not a simple array of restricted whole numbers;
• maxrank: the rank of the result would be greater than nine;
• index: a number in the index group is negative or not less than the length of the axis it indexes.
Examples
(É2 3 4)[1;2;3]
23
'adrv'[2 3Ň0 0 2 3 0 2]
aar
var
(É5 5 5)[0;É2;É3]
0 1 2
5 6 7
(É5 5 5)[0;2 5Ň0 1;0]
0 5 0 5 0
5 0 5 0 5
(`a `b;5 1 9;<{+})
<  5 1 9
Ň(É2 3 4)[É0;'';()]
0 0 4

Arguments and Result
y is a scalar symbol and x is any simple character or numeric array or the Null.
The result has the type indicated by y. (Since the Null is already an empty symbol vector, if x is the Null then ©`sym©x is `null.)
The shape of the result is:
Ňx if x and the result are neither or both symbolic; else
˘1ŐŇx if y is `sym; and otherwise
(Ňx),n, where n is the number of characters (excluding `) in the representation of the "longest" symbol in x.

Definition
The value of y is one of the symbols `char `int `float or `sym (but see the last paragraph of the additional error reports section, below). The result is x with each element converted to the type specified by y.

Any character, integer, floating-point, or simple symbol array can be converted to any of these four types.

In the case of floating point to integer, the elements of x are rounded. For integer to character, 256|x is used. The conversion is based, of course, on the character codes used in the implementation, namely ASCII.

Related functions: Pack and Unpack convert between symbol and character. Format and Default Format convert numbers to characters and employ IEEE rounding; they also convert symbols, and Default Format handles function scalars. Floor and Ceiling round in specific directions to whole numbers and may perform type conversions. Fix Input and its variants and Execute convert characters to numbers. Bitwise Cast leaves the data part of the variable unchanged but changes the type indicator and (usually) shape.

The following reports are issued only if there is no parse or value error (see "Common Error Reports"), and a type error is reported only if a domain error is not:

• a domain error is reported if either argument is nested or y is Null or contains more than one element;
• a type error is reported if the arguments specify an impermissible conversion (but see note below) or y is not a symbol, unless the arguments are suitable for the function Or.

Examples
a
3 5 6
`abcd

Catenate y,x

Arguments and Result
The arguments x and y are any arrays of the same general type, conforming in shape as described here:

• If x is a scalar then y can be any shape, and the shape of the result is (1+#y),1ŐŇy. Similarly if y is a scalar.
• If the rank of x is one less than the rank of y, then the shape of x must equal the shape of the items of y, and the shape of the result is (1+#y),Ňx. Similarly if the rank of y is one less than the rank of x.
• If the rank of x is equal to the rank of y, then the items of x and y must have the same shape, and so do the items of the result: 1ŐŇx is equal to 1ŐŇy and the shape of result is ((#x)+#y),1ŐŇx.
The result has the same type as:

• the floating-point argument, if the other one is integer; else
• the left argument, if neither argument is empty; else
• the nonempty argument, if exactly one argument is empty; else
• the right argument.
Definition
If x and y are the same rank, the items of y and the items of x are joined in the result. That is, item i of y equals item i of the result and item j of x equals item j+#y of the result.

If the arguments differ in rank by one, the argument of lower rank is treated as though it had an additional leading axis of length one. If one argument is a scalar, it is treated as though it had been reshaped to have the shape of the items of the other argument with an additional leading axis of length one.

Each of the following reports is issued only if there is no parse or value error (see "Common Error Reports") and none of the reports preceding it on this list applies:

• a type error is reported if the arguments are not of the same general type;
• a rank error is reported if neither argument is a scalar and their ranks differ by more than 1;
• a length error is reported if either their ranks are equal and the shapes of their items are not the same or their ranks differ by 1 and the argument of lesser rank is not the same shape as the items of the other.
Examples
(É2 3),(100+É4 3)       ă Same rank.
0   1   2
3   4   5
100 101 102
103 104 105
106 107 108
109 110 111
'Treasury ','note'      ă Same rank.
'Treasury note'

(É3),(100+É4 3) ă Ranks differ by 1. 0 1 2 100 101 102 103 104 105 106 107 108 109 110 111

3,É2 3 4 ă A scalar argument is extended to the size of an item 3 3 3 3 3 3 3 3 3 3 3 3 0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23

Choose y#x

Arguments and Result
y is either a simple array of restricted whole numbers, or a nested scalar or vector whose elements are enclosed, simple arrays of restricted whole numbers, or the Null. x is any array. If y is nested then Ňy is less than or equal to ŇŇx. The result has the same type as x if x is numeric or character, and otherwise the same general type.

Definition
If x is scalar, y must be the Null, and the result is x. Assume x is nonscalar for the rest of the definition.

If y is simple the result is

x[y;;...;]
In particular, if y is Null the result equals x. If y is not Null the shape of the result is (Ňy),1ŐŇx.

If y is nested, the result is

x[0Řy;1Řy;...;(˘1+#y)Řy]
If iŘy is Null then it is treated as if it were É(Ňx)[i]. Bracket Indexing treats any omitted trailing axes in a similar fashion, so the result can also be written as
x[0Řy;...;(˘1+#y)Řy;É(Ňx)[#y];...;É(Ňx)[˘1+ŇŇx]]
If no element of y is Null, the shape of the result is (ŘŇˇy),(Ňy)ŐŇx.

Each of the following reports is issued only if there is no parse or value error (see "Common Error Reports") and none of the reports preceding it on this list applies:

• a rank error is reported if (1) the left argument is nested and of length greater than the rank of the right argument, or (2) the right argument is a scalar and the left argument is other than a simple Null;
• a type error is reported if the left argument (1) is not a simple array or a nested scalar or vector of enclosed, simple arrays, or (2) contains a simple scalar which is not a restricted whole number;
• a maxrank error is reported if the rank of the result would be greater than nine;
• an index error is reported if an element of the left argument is not an appropriate index for the corresponding axis of the right argument, i.e., it is negative or equal to or greater than the length of that axis.
Examples
2 0 # 3 3Ň'abcdefghi'      ă Row 2 and row 0.
ghi
abc
(0;0 2) # 3 3Ň'abcdefghi'  ă Row 0, columns 0 2.
ac
(;0) # 3 3Ň'abcdefghi'     ă All rows, column 0.
(1;0) # É2 3 4             ă Plane 1, row 0, all columns.
12 13 14 15

Count #x

Argument and Result
The argument is any array. The result is a scalar integer.

Definition
The result is the number of items of x. If x is a scalar the result is 1, while if x is a nonscalar the result is the length of the leading axis, i.e., (Ňx) (see "Shape").

Examples
#É5000
5000
#168 3 4Ň0
168
#,12
1
#12
1

Deal y?x

Arguments and Result
Both x and y are simple one-element numeric arrays of nonnegative restricted whole numbers, with y¤x. The result is a vector of integers of length y.

Dependency
The value of the Random Link system variable, `rl, which is changed each time a random integer is chosen.

Definition
The result is a vector of integers of length y, chosen at random from Éx without duplication, or, in mathematical terms, without replacement. The result is dependent upon the random link, `rl, which is set when the system command \$rl is executed and each time a random integer is chosen.

Each of the following reports is issued only if there is no parse or value error (see "Common Error Reports"), and a domain error report is issued only if a type error report is not:

• a type error is reported if an argument is nested or has an element that is not a restricted whole number;
• a domain error is reported if either argument has a negative element or has more than one element, or if the left argument exceeds the right argument.
Example
10?10
3 1 5 4 2 0 8 6 9 7
10?10
7 6 3 8 9 2 4 5 0 1

Decode yÂx

Arguments and Result
y is a simple numeric scalar or vector, and x is any simple numeric array. If y has more than one element, then #y must equal #x. The result is a simple numeric array whose shape equals 1ŐŇx and whose type is integer if the arguments are of type integer and every element of the result can be faithfully represented that way and otherwise floating point.

Definition
If x and y are vectors with the same number of elements, the result is the evaluation of x in the number base system with radices y,y, ... , y[˘1+#y]. If y has one element it is treated as if it were (#x)Ňy. If x is a matrix, each element i#r of the result r is the evaluation of the column x[;i] in the number base system represented by y. More generally, if x has rank greater than 2, each element of the result is the evaluation of the corresponding vector along the first axis of x, in the number system represented by y.

Each of the following reports is issued only if there is no parse or value error (see "Common Error Reports") and none of the reports preceding it on this list applies:

• a type error is reported if either argument is not a simple numeric array;
• a rank error is reported if the left argument is not a scalar or vector;
• a length error is reported if #y is not equal to either 1 or #x.
Examples
ă Convert 2 hours, 5 minutes, and 59 seconds to seconds.
24 60 60Â2 5 59
7559
ă Present value (price) from interest rate and cash flows.
cfű0 100 100 100 100 1000
7.2î pv ű (ß1+i) Â ÷cf Ý iű.05
1138.12
ă Present value at various interest rates.
8.2î pv ű (ß1.03+.01«É5) Â@0 1 ÷cf
1234.32 1184.92 1138.12 1093.77 1051.71

Default Format îx

Argument and Result
x is a simple numeric or a simple character array, a simple symbol scalar, a function scalar, or a simple symbol array. The result is a simple character array of rank less than or equal to 2.

Dependency
For numeric x, the value of Printing Precision, `pp.

Definition
If x is numeric or character, the result is an array containing x in default format. That is, if the expression x is entered in an A+ session, a display of the value of x appears; this primitive function captures that display in its result. In particular, if x is a character array of rank less than or equal to 2, the result equals x. If x is numeric, the number of digits shown and the format (fixed or exponential) used are dependent on the printing precision system variable `pp. A nonscalar symbol array displays the symbols as described in the next paragraph, and for arrays of rank 2 or greater, are padded with blanks on the right to match the length of the longest (unpadded) symbol involved.

If x is a scalar symbol, the result is a character vector, giving the display of that symbol, with a blank preceding the backquote.

When x is a function scalar, the result is a character vector. If x is primitive, the result is its symbol. If x is a defined function, the result is its definition. If the definition has more than one line, the lines are separated by newlines in the result. If the function is derived (e.g., Éˇ), then the result is *derived*. (Note that Default Format shows that expressions such as +.« are not derived functions strictly speaking.)

If there is no parse or value error (see "Common Error Reports"),

• a rank error is reported if the argument is enclosed (nested or function scalar) and is not a scalar; and otherwise
• a type error is reported if the argument is not a simple character or numeric array, a simple symbol scalar, or a function scalar.
Examples
_gsv `pp
10
ă The Printing Precision is now 10. Digits after an e don't count. If there would
ă be too many digits in ordinary notation, e-notation is used in a display.
'(',(îĎ1),')',î12345.678912e24 1234567891 12345678912
( 3.141592654) 1.234567891e+28 1234567891 1.234567891e+10
ă A function definition, to be shown by Default Format.
cube x:x*3
'cube fn ý ',î<{cube}
cube fn ý cube x:x*3
ă Indentation of first line of definition is always ignored by Default Format.

Depth ˝x

Argument and Result
The argument is any array; if it is a function expression it must be in braces. The result is a scalar integer.

Definition
The result is the maximum depth of nesting in the argument. All simple arrays (and so all empty arrays) are depth 0, except for function expressions, whose depth is -1. (The Enclose of a function expression, which is called a function scalar, is simple and depth 0.) The depth of a nested scalar is 1 plus the depth of the disclosed scalar (see Disclose, below). The depth of a nonscalar nested array is the greatest of the depths of its elements.

Examples
˝'abc'
0
˝{+}           ă The parser needs the braces as a hint
˘1                 ă when two functions are juxtaposed.
˝(2;3;<(4;5))  ă Three enclosings: strand, Enclose, strand.
3

Disclose >x

Argument and Result
The argument x is a simple array, a nested scalar, or a uniform nested array (see Definition, Case 3, for the meaning of uniform). Letting s and t be the shape and type of the first element of x with that element's top level of nesting (if any) removed, the shape of the result is (Ňx),s and its type is floating point if some element of x is a nonempty floating-point array after its top level of nesting (if any) is removed, else its type is t.

Definition
Case 1. Simple Array x

If x is a simple array, perhaps a simple scalar, then the result is x. Note that function scalars are simple arrays; to turn a function scalar fnsc into the corresponding function you can use fnscˇ or %_name{fnsc}.

Case 2. Nested Scalar x

If x is a nested scalar, then its depth is at least one. The result is x with the top level of nesting removed, and it may or may not be a scalar.

Case 3. Nested Vector x

The elements of x must all be nested - i.e., each element of x must have a depth of at least one (remember that function scalars have depth zero) -, and the Discloses of all these elements must have the same shape and the same general type. Arrays with this property are called uniform in this definition.

Disclose of a nested vector x is defined in terms of Disclose of a nested scalar, as follows. The array >x has depth one less than the depth of x. The number of items of >x equals the number of elements of x, i.e., #x. For each index i of x, the ith item of >x equals the Disclose of the nested scalar i#x, i.e., >i#x.

Case 4. Nested Array x

Disclose of a nested array x is defined in terms of Disclose of a nested vector, as follows. As in the vector case, x must be uniform. Let s denote the common shape of all the Discloses of the scalar elements of x. Then >x is ((Ňx),s)Ň>,x. That is, ravel x, apply Disclose to this vector, and reshape the disclosed vector to have x's shape for its leading axes and the shape of a disclosed element for its trailing axes.

Each of the following reports is issued only if there is no parse or value error (see "Common Error Reports") and none of the reports preceding it on this list applies:

• a maxrank error is reported if the result would have more than nine dimensions;
• a domain error is reported if x contains both nested and nonnested elements other than symbols and function scalars;
• a rank error is reported if the Discloses of the elements of x have different ranks;
• a mismatch error is reported if the Discloses of the elements of x have different shapes;
• a type error is reported if the Discloses of the elements of x have different general types.
Example
>(É3;10«É3)
0  1  2
0 10 20

Drop yŐx

Arguments and Result
The argument y is a simple one-element array whose value is a restricted whole number, and x is any array. The shape of the result equals the shape of the right argument x along all but the first axis, while the length of the first axis is the larger of #x minus the absolute value of y and 0, i.e., 0Ó(#x)-|y.

Definition
The result is x without its first y items if y is nonnegative, or its last -y items if y is negative. If |y is greater than #x then the number of items in the result is 0.

Each of the following reports is issued only if there is no parse or value error (see "Common Error Reports"), and nonce only if there is no type error:

• a type error is reported if the left argument is not simple or has an element that is not a restricted whole number;
• a nonce error is reported if the left argument has more than one element.
Examples
3ŐÉ5 2
6 7
8 9
˘4Ő'15 January'
15 Jan

Enclose <x

Argument and Result
The argument is any array; if it is a function expression, it must be enclosed in braces, to aid the parser. The result is a nested scalar unless the argument is a function expression, in which case it is a simple scalar.

Definition
The result is a scalar that contains the argument x. The depth of the result is the depth of the argument plus one. If f is a function expression, <{f} is a function scalar. Note that strand notation is equivalent to the concatenation of the Enclose of each of its components.

Examples
2Ň<É3
<  0 1 2
<  0 1 2
ă Functional notation required for + .
(˝`sym),˝{+},(˝'abc'),(˝2 3 4),(˝5.5),˝()
0 ˘1 0 0 0 0
ă Strand encloses each element.
˝@0(`sym;+;'abc';2 3 4;5.5;)
1 0 1 1 1 1
ă Depths increased by Enclose.
˝@0(<`sym;<{+};<'abc';<2 3 4;<5.5;<())
2 1 2 2 2 2

Encode yÎx

Arguments and Result
y is a simple numeric vector or scalar and x is any simple numeric array. The result has shape (Ňy),Ňx.

Definition
For positive elements of x, the result is the representation of that element, as far as is possible, in the number base system with radices y,y, ... ,y[˘1+#y]. That is, yÎx contains the #y low-order "digits" of its representation in this number base for each positive element of x. For a negative element n, the result is the representation, in the same way, of («/y)|n. No matter what the signs of the elements of x are, yÂyÎx equals («/y)|x. Thus Decode is the left inverse of Encode for any element p for which («/y)|p is equal to p.

The following reports are issued only if there is no parse or value error (see "Common Error Reports"), and a rank error report is issued only if a type error report is not:

• a type error is reported if either argument is not a simple numeric array;
• a rank error is reported if the left argument is not a vector or scalar.
Examples
24 60 60 Î 7559
2 5 59
100 Î 12345
45

Execute âx

Argument and Result
x is a character vector or scalar. The result is the explicit result of the A+ expression in x, except that it is the Null when the last function executed in x is a Specification (ordinary or selective), and when the argument is a system command or a definition of a function, operator, or dependency.

Definition
This function evaluates x as an A+ expression. It cannot be used to establish the target of an Assignment. See also "Execute in Context or Protected Execute", "Value", and "Value in Context". It can be used to execute a system command. It can be traced by \$dbg xeq.

Each of the following reports is issued only if there is no parse or value error (see "Common Error Reports") and none of the reports preceding it on this list applies:

• a type error is reported if the argument is not simple or is not of character type;
• a rank error is reported if the rank of the argument exceeds 1;
• any error from the execution of the argument is reported (and execution is suspended); entering ý produces a domain error for Execute and a second suspension. See example.
Examples
100«â'1 1.23 4.567'
100 123 456.7
â'aű14 23 34'
ă Result is Null. (â'a')ű14 23 34 not allowed.
a
14 23 34
â"(É10)Ň0"
ă[error] Ň: maxrank
*     ý
ă[error] â: domain

Execute in Context or Protected Execute yâx

Arguments and Result
y is a symbol or an integer or Null and x is a character vector or scalar. The result is the explicit result of the A+ expression in x under circumstances controlled by y, except that it is null when the last function executed is any Specification, and when x is a system command or a definition of a function, operator, or dependency.

Definition
If y is a symbol, then this function is Execute in Context and evaluates x as an A+ expression in the context y. If c is the context when the function is invoked, it is equivalent to {_cx y;âx;_cx c}, except that the explicit result is that of âx rather than _cx c. Note: an unqualified name z in x remains unqualified; it is not treated as a qualified name; x is just executed in the context y. In particular, the name of a local variable z in x remains unqualified. See "Execute", "Value", and "Value in Context".
`cxtâ'a:b+c'
and if you have a list c of contexts, then, for example,
câˇ<'a:b+c'
creates a whole set of dependencies in different contexts.

If the left argument is an integer or Null, the function is Protected Execute, in the current context (cf. "Do - Monadic (Protected Execution)"). If the execution fails, the result is the error code, as listed in the table "Error codes for Protected Execution", as a simple integer. There is no suspension - i.e., execution proceeds as if no error has occurred. (Actually, there are a few cases, such as an attempt to give a bound variable an impermissible value, that do result in a suspension, with a stop error message.)

If the execution is successful, the result is Enclose applied to the result of Execute for x, viz., <âx. Enclose is used to enable you to distinguish between the two cases.

If the Protected Execute Flag, `Gf, is 0, however, a suspension will occur if Protected Execute encounters an error in its right argument; entering ý clears the suspension and produces the error code as the result. (This behavior is different from that of an ordinary Execute: clearing a suspension in the execution of its argument causes a second suspension, on the Execute itself, and clearing that yields a null result.) See `Gf and \$Gf. It can be traced by \$dbg xeq.

Each of the following reports is issued only if there is no parse or value error (see "Common Error Reports") and none of the reports preceding it on this list applies:

• a type error is reported if the left argument is not a simple symbol or integer or Null, or if the right argument is not a simple character array;
• a rank error is reported if the rank of the right argument exceeds one;
• if the left argument is a symbol or if the protected execute flag, `Gf, is zero, any error from the execution of the argument is reported (and execution is suspended).
Example
try.xűÉ3
â'xß10'       ă try.x has a value, but x does not.
.x: value
*      ý
â: domain         ă Error gets passed on to Execute.
*      ý
0â'xß10'      ă Protected execute (`Gf is 1).
4                 ă Numeric code for the value error.
`tryâ'xß10'   ă Execute in Context okay; uses try.x.
0 0.1 0.2
ă Protected execute using the var that has a value:
0â'try.xß10'
<  0 0.1 0.2       ă Success shown by an enclosed result.

Expand y\x

Arguments and Result
y is a simple scalar or vector of restricted whole numbers whose elements are all 0 or 1, and x is any array.

Definition
The number of ones in y equals the number of items in x, i.e., +/y equals #x, or x is a scalar. If the ith item of y is 1, then the ith item of the result is the (+/(i+1)Ůy)th item of x, or x if it is a scalar. If the ith item of y is 0, then the ith item of the result is composed entirely of fill scalars. The table "Fill Elements" shows the fill scalars.

Each of the following reports is issued only if none of the reports preceding it on this list applies and there is no parse or value error (see "Common Error Reports") - except that token precedes value:

• a token error (like a parse error) is reported if there is a primitive function or operator symbol to the immediate left of \ that is not one of +«ÓÄ^©;
and, unless there is one of +«ÓÄ^© to the immediate left of \ (that is, unless you are thrown into Scan, a monadic operator):

• a valence error is reported if there is no argument to the immediate left of \;
• a type error is reported if the left argument is nested or does not consist of restricted whole numbers;
• a domain error is reported if any element of the left argument is not 0 or 1;
• a rank error is reported if the left argument is not a scalar or vector;
• a length error is reported if the number of ones in the left argument is unequal to the number of items in the right argument, unless the right argument is a one-element array.
Examples
1 0 1 1\É3 4
0  1  2  3
0  0  0  0
4  5  6  7
8  9 10 11
1 0 1\'a'
a a

Find yÉx

Arguments and Result
The arguments are any arrays (including scalars) of the same general type. The rank of the items of y must not exceed the rank of x, and the ˘1+ŇŇy trailing axes of x must have length 1ŐŇy. The result is an array of integers whose shape is defined by the A+ expression (-0Ó(ŇŇy)-1)ŐŇx - i.e., the shape of x with the last s dimensions omitted, where s is the rank of the items of y.

Dependency
Comparison tolerance, if an argument is in floating point.

Definition
Partition x into cells of rank 0Ó(ŇŇy)-1. The result has one element for each such cell. The value of that element is the index of the first item of y to which the cell is identical - in the sense of Match, i.e., at all levels the cell and the item are the same shape and type (except that integer and floating point match here) and all their simple scalar components, at whatever level, are tolerably equal. If the cell is not found among the items of y, the resulting element is #y. A scalar y is treated as a one-element vector.

Each of the following reports is issued only if there is no parse or value error (see "Common Error Reports") and none of the reports preceding it on this list applies:

• a type error is reported if the arguments are not of the same general type;
• a rank error is reported if the rank of x is less than that of the items of y, so the partitioning fails;
• a length error is reported if the items of y and the cells into which x is partitioned have different shapes.
Examples
(4 3Ň'fatbatcathat')É(2 3Ň'catpat')
2 4
(+;-;«;ß)É<{«}
2   ă Strand makes function expression a function scalar.

Format yîx

Arguments and Result
y is a simple numeric scalar or vector, and x is a simple numeric or symbol array. If #y is greater than 1 then it must equal ˘1ŮŇx - i.e., #x if x is a vector, and the number of columns if the rank of x is greater than 1. The result is a simple character array of rank less than or equal to 2.

Definition
The result is an array containing x in formatted form, with the format controlled by y. Negative numbers are formatted with an ordinary minus sign (-). Elements of y specify the appearance of certain elements in x:

• if #y equals 1, then the element of y applies to all elements of x;

• if #y is greater than 1, then element i#y applies to element i#x if x is a vector, to column x[;i] if x is a matrix, and to columns x[...;i] otherwise.
The format of every element of x is controlled by an element of y, which is of the form [-]width[.digits], where the digits specification is expected to be a single digit and any digits following it are ignored. The total number of characters in the format is width. If digits is present, it specifies the number of digits to appear to the right of the decimal point; if it is 0 or absent, the element is shown as an integer. If the minus sign is present, the format is in exponential format (e-notation).

Understanding how rounding works

Because Format is often used as a means of rounding numbers to some desired precision —and because that rounding often creates questions about the accuracy of the rounding— this seems to be a good place to discuss how rounding works, and why it is that we sometimes see some unexpected results.

There is nothing within A+ that imposes any special rules on the rounding of numbers. Rounding is done entirely using IEEE symmetric rounding rules. That is, if a number lies halfway between two other numbers to which it can legitimately be equally rounded either way, it is rounded to the one ending in an even digit. Therefore, a value of 22.5, for instance, could logically be rounded to either 22 or 23; the IEEE rules tell us that it should be rounded to 22, because that is the number which ends with an even digit. As further examples, if we are starting with values which are exactly halfway between two integers, and rounding them to integers:

• 0.5 should round down to an integer value of 0 (not to 1, because 1 is an odd number);
• 1.5 should round up to an even integer value of 2;
• 2.5 should round down to an even integer value of 2;
• 3.5 should round up to an even integer value of 4; and
• 4.5 should round down to an even integer value of 4.

In A+ terms, this would be shown as follows:

4î.5 1.5 2.5 3.5 4.5    ă This example shows IEEE rounding.
0   2   2   4   4

In actual practice, however, machine approximation of decimal numbers and machine rounding may obscure the regular IEEE rules.

For example, given the following vector:

vű1.055 1.155 1.255 1.355 1.455 1.555 1.655 1.755 1.855 1.955
IEEE rules dictate that rounding it to two decimal positions should cause the "n.n55" values to round to "n.n6" (and if we had "n.n45" values, they should round to "n.n4"). However, that's not necessarily what happens. Let's explore what happens, and why.

Original
Value
IEEE
Rounding
6.2îv
Rounding
Actual Internal
Value
1.0551.061.05    1.05499999999999994...
1.1551.161.161.15500000000000003...
1.2551.261.251.25499999999999989...
1.3551.361.351.35499999999999998...
1.4551.461.461.45500000000000007...
1.5551.561.551.55499999999999994...
1.6551.661.661.65500000000000003...
1.7551.761.751.75499999999999989...
1.8551.861.851.85499999999999998...
1.9551.961.961.95500000000000007...

Notice that using 6.2îv will round the values in v to two decimal places... but it doesn't necessarily give us what we expect from the IEEE rounding rules. Some of the results look okay, but realize that the internal values are imprecise for all of our values, and some of them just happen to round the way that we want them to.)

The reason for this is that we are doing decimal operations on a hexadecimal machine, so there will always be some errors in the internal representation of many of the numbers that we deal with every day. It is simply not possible to represent these values exactly on a digital machine.

In the same way that we simply cannot represent exactly one-third as a decimal number, we also cannot represent many other decimal numbers in hexadecimal and be able to convert them back to exactly the number that we started with. Therefore, a value of "1.055" actually gets represented within the machine as "1.05499999999999994...", so that value is correctly rounded down to "1.05", while a value of "1.155" is actually seen by the machine as "1.15500000000000003...", so that value is correctly rounded up to "1.16". Although the first value is rounded to "1.05" instead of the desired IEEE rounding value of "1.06", realize that the rounding is correct based upon the internal value that is seen by the hardware. These internal values are incorrect, but they are as close an approximation of the exact values as we can get on this hardware.

So why don't we see this imprecision at every step of our calculations? ...Simply because the printing precision normally masks this error, and over the course of normal work, these errors tend to cancel out.

Before you get too concerned about this imprecision, realize that the Comparison Tolerance in A+ (the amount by which two values may differ and still be considered to be equal) is set to 1e-13 (or 0.0000000000001); that is a tolerance of one part (of error) in ten trillion. To put this into perspective, if our measurements were to represent distance, a measurement of 250,000 miles (approximately the distance from the earth to the moon) could be carried out within an error of no more than one-third of the thickness of a piece of copier paper. For most operations, this is deemed to be "close enough."

Also realize that rounding of values through the use of the Format function is typically done just for display of final output (where 16 digits of precision would be inappropriate anyway). Calculations prior to that final rounding step are done at full precision.

Finally, we just want to emphasize again that none of the rounding that you see through A+ is any different than it would be in other environments. A point that may make it seem different is the ease with which you can adjust the precision and look at alternate views of the same values. This is a general hardware numeric conversion issue, not an A+ issue.

Creating the left argument to Format:

When a number has been formatted in the specified form the result is fitted in the specified width in one of two ways:

• exponential format: the result for a positive number is padded on the left with two blanks and for a negative with one, and this padded result is left justified within the width, after being truncated on the right if it is too long;

• otherwise: the result is right justified within the width, after being truncated on the right if it is too long.
Because these rules effectively handle inconsistent left arguments like 6.6, no error message is given for them. It is up to you to see that the widths you specify are sufficient, allowing for the padding in exponential format and for any blanks you want between adjacent numbers not in exponential format.

If the right argument consists of symbols, they are formatted in their displayed form with backquotes removed. Each of them is right justified in the specified width, after being truncated if it is too long. Any digits or exponential-format specification is ignored.

The following reports are issued only if there is no parse or value error (see "Common Error Reports"), and a length error is reported only if a type error is not:

• a type error is reported if the left argument is not simple and numeric, or if the right argument is not simple and either numeric or symbol;
• a length error is reported if the number of elements in the left argument is neither 1 nor equal to ˘1ŮŇx.
Examples

2 10.4 ˘12.2î2 3Ň1 ˘3.14159 123456 2 123.7 ˘55
1   -3.1416  1.23e+05
2  123.7000 -5.50e+01

4î.5 1.5 2.5 3.5 4.5   ă This example shows IEEE rounding.
0   2   2   4   4

16.12î1.123456789012   ă 16.12 on the left is equivalent to
1.1            ă 16.1: the 2 is ignored.

_gsv `pp
10                         ă Printing Precision is 10

12345.678912           ă See that ordinary display obeys Printing Precision:
12345.67891                ă 5 digits before the decimal point, so 5 (10-5) digits after.

14.7 î 12345.678912
12345.6789120              ă Format ignores Printing Precision and obeys the left argument.

Argument and Result
The argument x is either a simple numeric array or a simple character array or a simple symbol array. The result is a vector of integers of length #x, i.e., of length equal to the number of items in x.

Definition
The result r is a permutation of the vector É#x such that the items of r#x are in nonascending, lexicographic order. To determine whether or not one item is greater than or equal to another in the lexicographic sense, leading elements in their ravels are compared first, and only in the case of ties are the elements that follow compared. Alphabetic characters are sorted in accordance with their ASCII codes. The indices of equal items are in ascending order in r. That is, if i is less than j and r[i]#x is identical to r[j]#x, then r[i] is less than r[j]. Comparison tolerance is not used. If x is a symbol array, the result is the same as it would be for Îx.

Each of the following reports is issued only if there is no parse or value error (see "Common Error Reports"), and a type error is reported only if a valence error is not:

• a valence error is reported if there is a left argument;
• a type error is reported if the argument is not a simple numeric or character array.
Examples
ç 10.2 6 999 0 6
2 0 1 4 3
(ça)#aűÎ`apl `a `apple
apple
apl
a

Argument and Result
The argument x is either a simple numeric array or a simple character array or a simple symbol array. The result is a vector of integers of length #x, i.e., of length equal to the number of items in x.

Definition
The result r is a permutation of the vector É#x such that the items of r#x are in nondescending, lexicographic order. To determine whether or not one item is less than or equal to another in the lexicographic sense, leading elements in their ravels are compared first, and only in the case of ties are the elements that follow compared. Alphabetic characters are sorted in accordance with their ASCII codes. The indices of equal items are in ascending order in r. That is, if i is less than j and r[i]#x is identical to r[j]#x, then r[i] is less than r[j]. Comparison tolerance is not used. If x is a symbol array, the result is the same as it would be for Îx.

The following report is issued only if there is no parse or value error (see "Common Error Reports"):

• a type error is reported if the argument is not a simple numeric or character array.
Examples
č 10.2 6 999 0 6
3 1 4 0 2
(ča)#aűÎ`apl `a `apple
a
apl
apple

Interval Éx

Argument and Result
The argument is a simple scalar or vector of nonnegative restricted whole numbers. The result is an array of integers whose shape is x if x is a vector, or ,x if x is a scalar.

Definition
If the argument x is a scalar or one-element vector, the result is the vector of integers from 0 to x-1. If the argument x is a vector with 2 or more elements, the result is the vector of integers from 0 to («/x)-1, reshaped to shape x: viz., xŇÉ«/x (see "Reshape").

Each of the following reports is issued only if there is no parse or value error (see "Common Error Reports") and none of the reports preceding it on this list applies:

• a type error is reported if the argument is not simple or an element of it is not a restricted whole number;
• a rank error is reported if the argument is not a scalar or a vector;
• a domain error is reported if the argument has a negative element;
• a maxrank error is reported if the argument has more than nine elements.
Examples
É5
0 1 2 3 4
É2 3
0 1 2
3 4 5

Item Ravel !x

Argument and Result
The argument x is any array of rank at least 2. The result has shape («/2ŮŇx),2ŐŇx and the same type as the argument.

Definition
The result is ((«/2ŮŇx),2ŐŇx)Ňx, i.e., the ravel of the first two axes of x becomes the first axis of the result.

The following report is issued only if there is no parse or value error (see "Common Error Reports"):

• a rank error is reported if the argument is a scalar or vector.
Example
!É2 2 4
0  1  2  3
4  5  6  7
8  9 10 11
12 13 14 15

Laminate y~x

Arguments and Result
Either x and y have equal shapes, or one is a scalar. They also must have the same general type. If x is nonscalar, the shape of the result is 2,Ňx; otherwise, the shape of the result is 2,Ňy.

Definition
The result r always has two items. If x and y have equal shapes then item r equals y and item r equals x. If x is nonscalar and y is a scalar then item r equals (Ňx)Ňy and item r equals x. If x is scalar and y is a nonscalar then item r equals y and item r equals (Ňy)Ňx.

The result has the same type as:

• the floating-point argument, if the other one is integer; else
• the left argument, if neither argument is empty; else
• the nonempty argument, if exactly one argument is empty; else
• the right argument.
Each of the following reports is issued only if there is no parse or value error (see "Common Error Reports") and none of the reports preceding it on this list applies:

• a type error is reported if the arguments are not of the same general type;
• a rank error is reported if neither argument is a scalar and their ranks differ;
• a length error is reported if neither argument is a scalar and their shapes differ;
• a maxrank error is reported if the rank of either argument is 9.
Example
1 2 3~10 20 30
1  2  3
10 20 30

Left yÝx

Arguments and Result
y and x are any arrays. The result is the same shape and type as y.

Definition
The result is identical to the left argument. Left can be used to execute two expressions when you would only discard the explicit result of the first one anyway.

Examples
2 3Ý'abc'
2 3
ă Evaluate a dependency to keep its last value, then remove its definition:
_undef{`x} Ý %`x
a[ča] Ý aű0 2 4 5 1 3 7 6
0 1 2 3 4 5 6 7
((aÉa)=ÉŇa)/a Ý aű'keep only the unique characters'
keponlythuiqcars

Match y˝x

Arguments and Result
The arguments can be any arrays, including function arrays. The result is an integer, either 1 or 0.

Dependency
Comparison tolerance, if an argument is in floating point.

Definition
The result is 1 if at all levels y and x are the same shape and type (except that integer and floating point match here), and all their simple scalar components, at whatever level, are tolerably equal. The result is 0 otherwise.

Examples
'abc'˝'a','b','c'
1
''˝É0
0
(É2 4)˝'no match'
0              ă Unlike Equal to, never an error; always 0 or 1.

Matrix Inverse ­x

Argument and Result
x is a simple numeric array of rank less than or equal to 2 - if 2, then at least as many rows as columns. The result has shape ÷Ňx.

Definition
If x is a nonsingular matrix with the same number of rows as columns, then the result is its matrix inverse. If x is a matrix with more rows than columns, and if the columns are linearly independent, the result is the unique left matrix inverse of x. That is, (­x)+.«x equals an identity matrix, but x+.«­x may not. If x is a vector the result is ,­((Ňx),1)Ňx. If x is a scalar the result is ßx.

The following reports are issued only if there is no parse or value error (see "Common Error Reports"):

• a rank error is reported if the rank of the argument exceeds 2;
• a domain error is reported if (1) the argument is not a simple numeric array, (2) the argument is a matrix with more columns than rows, or (3) the argument is singular or very illconditioned.
Example
­ 2 2Ň 1 2 3 4
˘2    1
1.5 ˘0.5

Member yĹx

Arguments and Result
The arguments are any arrays of the same general type. The rank of the items of x must not exceed the rank of y, and the trailing ˘1+ŇŇx trailing axes of y must have length 1ŐŇx. The result is an array of integers whose shape is defined by the A+ expression (-0Ó(ŇŇx)-1)ŐŇy.

Dependency
Comparison tolerance, if an argument is in floating point.

Definition
Partition y into cells of rank 0Ó(ŇŇx)-1. The result has one element for each such cell. The value of that element is 1 if at all levels the cell and at least one of the items of x are the same shape and type (except that integer and floating point match here) and all their simple scalar components, at whatever level, are tolerably equal - i.e., if Match yields 1 for the cell and some item of x. The result is 0 otherwise.

Each of the following reports is issued only if there is no parse or value error (see "Common Error Reports") and none of the reports preceding it on this list applies:

• a type error is reported if the arguments are not of the same general type;
• a rank error is reported if the rank of y is less than that of the items of x, so the partitioning fails;
• a length error is reported if the items of x and the cells into which y is partitioned have different shapes.
Examples
(123+1e-10 1e-11)Ĺ123,1950+É50
0 1
1992 1991 1870 1992 2001Ĺ123,1950+É50
1 1 0 1 0
(2 3Ň'catpat')Ĺ(4 3Ň'fatbatcathat')
1 0

Null Ýx

Argument and Result
x is any array.

Definition
The result is Null, i.e., (), the empty symbol vector, whose type is `null.

Examples
Ý'junk'
()˝Ý9 10
1

Pack Âx

Argument and Result
x is a simple character array. The result is an array of symbols with shape ˘1ŐŇx.

Definition
If i#r is an element of the result r then i#x is a character vector along the last axis of x. Item i#r is the symbol that, when displayed, looks exactly like the character vector i#x except for the leading `. Trailing blanks in i#x are ignored, but included blanks are allowed. The null character, `char©0, is used by the interpreter to delimit symbols, so never try to include it in a symbol: it will exclude any characters following it from the symbol.

The following report is issued only if there is no parse or value error (see "Common Error Reports"):

• a type error is reported if the argument is not a simple character array.
Example
Â2 3Ň'a  abc'
`a `abc

Partition yÚx

Arguments and Result
y is a simple array of restricted whole numbers, and x is any array. The result is a nested vector whose length is Ó(#x)ßy if y consists of one element and that element is not zero, and otherwise a nested array of the same shape as y.

Definition
The elements of y are nonnegative. If y has one element and that element is not zero, then the first element of the result is Enclose of the first y items of x, the second element is Enclose of the next y items of x, and so on, until there are fewer than y items of x remaining. If there are no remaining elements, then the result is complete, and otherwise the last element of the result is Enclose of the remaining items of x.

If y has more than one element or is 0, then the result has the same shape as y, and the first element of the ravel of the result is Enclose of the first (,y) items of x, the second element is Enclose of the next (,y) items of x, and so on until y is exhausted. If for some element of the result there are fewer items remaining in x than y specifies for that element, then those remaining items of x are enclosed to form that element, and any remaining elements of the result are empty. On the other hand, not all items of x need appear in the result.

The following reports are issued only if there is no parse or value error (see "Common Error Reports"), and a domain error is reported only if a type error is not:

• a type error is reported if the left argument is nested or does not consist of restricted whole numbers;
• a domain error is reported if the left argument contains a negative number.
Examples
3 2 2 1ÚÉ6 3
<  0 1 2
3 4 5
6 7 8
<   9 10 11
12 13 14
<  15 16 17
<
3ÚÉ5
<  0 1 2
<  3 4
(Ú' '=x)Úxű' this is'     ă See Partition Count.
<  this
<  is

Partition Count Úx

Argument and Result
x is a simple vector or scalar of restricted whole numbers. The result is a numeric vector of integers.

Definition
In general, x is a vector or scalar of restricted whole numbers, but in the usual case it is a vector composed of zeros and ones. All nonzero numbers are treated alike, and the description assumes ones for simplicity.

The first element of x must be 1. The length of the result is the number of ones in x, i.e., +/x, and each element of the result corresponds to a 1 in x. The value of an element is the length of the subvector consisting of the 1 it corresponds to and all the zeros preceding the next 1. Put another way, the elements of the result are the lengths of the contiguous sequences of zeros starting at each 1 in x, plus 1.

Each of the following reports is issued only if there is no parse or value error (see "Common Error Reports"), and none of the reports preceding it on this list applies:

• a type error is reported if the argument is nested or does not consist of restricted whole numbers;
• a rank error is reported if the argument is not a scalar or vector;
• a domain error is reported if the argument begins with a zero.
Examples
Ú1 0 0 0 1 0
4 2
Ú1 0 0 0 1 1 0 1
4 1 2 1

Pick yŘx

Arguments and Result
The left argument y is the Null, or a simple scalar or vector of integers or symbols, or a nested scalar or vector whose items are simple scalars or vectors of integers. The right argument x is any array.

Definition
All permitted combinations of arguments are considered by turns.

Any valid right argument and empty left argument (É0 or the Null)

An empty vector y picks all of x. (Warning! A possible point of confusion: although Pick acts like Choose and Bracket Indexing for the Null, selecting all, for É0 it differs from those two functions, picking all whereas they select none.)

The result is the same as if the right argument were a one-element vector; if the left argument is not empty, it must be 0.

Slotfiller right argument and simple symbol left argument

A symbol is used to pick from a slotfiller, an array of the form (s;v), where s is a scalar or vector of symbols and v is any nested scalar or vector of the same length as s (see "Subtypes and Supertypes"). If y has one element and is identical to the ith element of s, i.e., i#s, (and not to any previous element - Pick does not check that the elements of s are distinct) then yŘ(s;v) is defined and equals >i#v. If x is a slotfiller composed of a pair of scalars, (`sym;<array) for example, and y equals 0Řx, then yŘx is defined and equals >1Řx.

If x is a nested slotfiller and y a simple vector of symbols (a path vector), the result is y[˘1+#y]Ř...ŘyŘyŘx where the scalar Picks are as just defined. Note that the order of the elements in the left argument corresponds to the depth of the selection from the right argument: element 0 in the left argument refers to the top level, element 1 refers to the second level, and so on.

Simple right argument and simple numeric left argument of length 1

A simple array can be picked from only when y is É0 or Null or a scalar or one-element vector. That is, there must be only one step to the Pick, and either a single item or all of x must be picked. An empty vector picks all of x, as stated above, and for a scalar or one-element vector and a simple right argument, Pick is the same as Choose:

yŘx űý y#x.
If y is a scalar or one-element vector, then the rank of x must not exceed 1. For example,
()Ř1    űý 1
()Ř1 2  űý (É0)Ř1 2 űý 1 2
1Ř1 2 3 űý 2
0ŘÉ2 3
is a rank error.

Nested vector right argument and simple left argument

If y has a single element, x is a vector and the result is the Disclose of the (scalar) yth element of x, i.e.,

>y#x.
A vector y is called a path vector, and yŘx (for a simple y) reaches into x with a series of Picks that select scalars and Disclose them, using one element of y at each step:
y[˘1+#y]Ř...ŘyŘyŘx.
The order of the elements in the left argument corresponds to the depth of the selection from the right argument: element 0 in the left argument refers to the top level, element 1 refers to the second level, and so on. The argument x and the result of each but the last scalar Pick must be a vector, since the left argument of each step of Pick is a scalar. Picking from a simple array is not allowed as a continuation step: a simple array can be produced only as the final step; 1 0Ř(1;2 3;4) is an error.

Nested right argument and nested left argument

If y is nested, its items are used in a way similar to the previous case and must each select a scalar, but the rank of x and any of its components can exceed 1. If y is scalar and x is of rank 2 or greater (to distinguish this case from the previous one), y must contain a full set of indices for x, as an enclosed simple vector. The result is the Disclose of a single element chosen from x, viz.,

>(<@0>y)#x
(A small complexity in this expression arises from the fact that Pick, in general picking a single element during each of several steps, requires all its indices for each depth to be in one box, whereas Choose, in general choosing several elements or cross sections but only at the top level, requires the indices for each axis to be in one box.) If y is a vector, then yŘx reaches into x with a series of scalar Picks of the same form as just shown for the simple case, but now each element of y is an enclosed simple vector and the corresponding component of x, from which y selects, need not be a vector.

Picking from a simple array is not allowed as a continuation step: a simple array can be produced only as the final step; (1;0)Ř(1;2 3;4) is an error.

By the way, ((j;i)Řa)űb is a valid Selective Assignment, although (iŘjŘa)űb is not.

The following reports are issued only if there is no parse or value error (see "Common Error Reports"):

• a type error is reported if y is not composed of symbols or integers (not just restricted whole numbers);
• a rank error is reported if (1) y or anything it contains is not a vector or a scalar, or (2) one of its items has a length unequal to the rank of the array to which it is applied;
• a domain error is reported if (1) y is symbolic and x is not (more or less) a slotfiller array, or (2) during the execution of Pick and not as its last step, an array is picked that is not nested;
• an index error is reported if an element of y is not in the range 0 to n-1, where n is the length of the axis it is applied to, or if y is a symbol and is not a member of the vector of symbols s in x.
Examples
1Ř('ab';(2 2Ň'cdef';10 20))
< cd
ef
<  10 20
0Ř1Ř('ab';(2 2Ň'cdef';10 20))
cd
ef
1 0Ř('ab';(2 2Ň'cdef';10 20))
cd
ef
(1;0;0 1)Ř('ab';(2 2Ň('c';'d';'e';'f');10 20))
d
`wasŘ(`this `was `that;(10;20;30))
20
`this `was `that É`was
1
1Ř(10;20;30)
20
`isŘ(`this `was `that;(10;20;30))
Ř: index
*    ý
`aŘ(`a;<10)
10

Print Őx

Argument and Result
x is any array and its value is also the result.

Definition
The result is x, but additionally the value of x is displayed in the A+ session.

Example
2+Ő3
3
5

Rake Ĺx

Argument and Result
x is any array. The result is a nested vector whose depth is one, or a function scalar or the Null.

Definition
If x is the Null, so is the result. If x is simple and not the Null, the result is ,<x. Otherwise, the result is a vector composed of the simple components of x, except that Nulls are discarded. The simple components of x are all those simple objects obtainable by repeated selection and disclosure. Each of these components is enclosed in the result, except that scalars of type symbol and function that were at depth zero remain so.

Examples
Ĺ`a `b
<  `a `b   ă A vector whose only element is of
ă depth 1 and, when disclosed, length 2.
Ĺ`a`b,(+;'ac';1 2;(3 4;(5;<(););6);7 8)
<  `a
<  `b      ă Despite the display,
<  +       ă the first three elements are simple: `a `b <{+}
<  ac      ă This and all the rest of the elements are each at depth 1.
<  1 2
<  3 4
<  5       ă Notice that two Nulls were discarded following this element.
<  6
<  7 8

Ravel ,x

Argument and Result
The argument x is any array. The result is a vector of shape «/Ňx.

Definition
The result is the vector of the elements in x, taken in row-major, or odometer, order. For a scalar, it is a one element vector.

Example
a
101   2
3 ˘45
34  21.5
,a
101 2 3 ˘45 34 21.5

Raze Řx

Argument and Result
The argument is either a simple array or a nested scalar or vector. If it is a nested vector, then the Discloses of its elements must all be conformable: they must be of the same general type and, treating scalars as one-element vectors, their ranks and the shapes of their items must be same.

The type of the result depends upon the Discloses of the elements of x. If one of them is a nonempty floating-point array, the result type is floating point. Otherwise, if any of them are nonempty, the result type is that of the first nonempty one; else it is the type of the first one.

The result shape is Ňx if x is simple, Ň>x if x is a nested scalar, Ň>''Ňx if x is a nested one-element vector, and otherwise (+/>@0#ˇx),s, where s is the common shape of the items of the disclosed elements of x.

Definition
If x is simple, then the result equals x. If x is a nested scalar, the result is >x. If x is a one-element nested vector, then if that one element is an enclosed scalar, the result is ,>x, and otherwise the result is >x. If x is a nested vector with more than one element, the result is the catenation of the Discloses of all elements of x, i.e.,
(>0#x),(>1#x),...,>(˘1+#x)#x
Note in the latter case that x is in the domain of Raze only if (1) this series of catenations can be formed and (2) the Discloses of all the elements are either all the same rank or a mixture of scalars and vectors.

Each of the following reports is issued only if there is no parse or value error (see "Common Error Reports") and none of the reports preceding it on this list applies:

• a domain error is reported if some elements of x are simple and some elements are nested;
• a rank error is reported if the Discloses of the elements of x have different ranks, unless they are all either vectors or scalars;
• a mismatch error is reported if the items of the Discloses of the elements of x have different shapes;
• a type error is reported if the Discloses of the elements of x have different general types.
Examples
Ř('ab';'cde';'f')
abcdef
Ř(É2 3;10«É2 3)
0  1  2
3  4  5
10 11 12
13 14 15

Replicate y/x

Arguments and Result
y is a simple vector or one-element array of nonnegative restricted whole numbers, and x is any array. If y is a vector of length unequal to one, then its length equals the number of items of x, i.e., #x, or x can be a scalar. The items of the result are items of x.

Definition
The items of the result are taken from the items of x. Each item i#x (or x itself if it is a scalar) is replicated y[i] times in the result. A scalar or other one-element array y is treated like (#x)Ňy, i.e., each item of x is replicated y times in the result. The number of items in the result is +/(#x)Ňy. When every element of y is 0 or 1, this function is called Compress.

Each of the following reports is issued only if there is no parse or value error (see "Common Error Reports"), except token precedes value, and none of the reports preceding it on this list applies:

• a token error (like a parse error) is reported if there is a primitive function or operator symbol to the immediate left of / that is not one of +«ÓÄ^©;
and, unless one of +«ÓÄ^© is to the immediate left of /, throwing you into Reduce, a monadic operator:

• a valence error is reported if there is no left argument to the immediate left of /;
• a type error is reported if the left argument is nested or does not consist of restricted whole numbers;
• a domain error is reported if the left argument contains a negative number;
• a rank error is reported if the left argument is not a vector or a one-element array;
• a length error is reported if the number of elements in the left argument equals neither one nor the number of items in the right argument, unless the right argument is a scalar.
Examples
3 0 1/3 2Ň'abcdef'
ab
ab
ab
ef
(a¦0)/aű4 ˘1 3 0 8 ˘5     ă Compress.
4 3 0 8
2 0 3 0/'a'
aaaaa

Reshape yŇx

Arguments and Result
The argument y is any simple array of nonnegative restricted whole numbers, and x is any array. The result is an array whose shape is ,y and whose type is that of x except in certain cases when the result is empty (see the definition, below).

Definition
The value is an array whose elements come from ,x (see "Ravel") in ascending index order. The number of elements of x needed for the result is «/,y. If x has at least «/,y elements, any excess is ignored. If x is nonempty but has fewer than «/,y elements, the elements of x are used cyclically. If x is empty, the resultant array is filled with zeros if x is numeric, blanks if x is character, or enclosed Nulls if x is nested, as shown in the table "Fill Elements".

If y is all zeros, the result is of course empty, and its type is the type of x if x is character, integer, floating point, or null, but its type is null if x is box, symbol, or function.

Each of the following reports is issued only if there is no parse or value error (see "Common Error Reports") and none of the reports preceding it on this list applies:

• a type error is reported if y is not simple or has an element that is not a restricted whole number;
• a domain error is reported if y has a negative element, or if «/,y is too large to be represented as an integer - i.e., is not a restricted whole number;
• a maxrank error is reported if y has more than nine elements.
Examples
2 3Ň'abcdefgh'
abc
def
10Ň'abcdefgh'
abcdefghab

Restructure y!x

Arguments and Result
The left argument y is a simple one-element array whose value is a restricted whole number, and the right argument x is any array, except that it must be nonscalar unless y is 1. The result has rank 1 greater than the rank of x. Except for the first two axes of the result and the first axis of x, the shapes of the result and x are equal. There are two quite different cases.

• If y is positive, it must evenly divide #x, and the result has shape ((#x)ß,y),(,y),1ŐŇx.

• If y is negative or zero, the result has shape ((,y)+1+#x),(-,y),1ŐŇx.
Definition
In both cases of this function the result is obtained by arranging the items of x in ways that replace the first axis of x with two new axes. In the case where y is positive it must evenly divide #x, and then the result is simply a reshape of the leading axis of the x into two axes, the first of length (#x)ßy, and the second of length y. See the first example.

Each of the following reports is issued only if there is no parse or value error (see "Common Error Reports") and none of the reports preceding it on this list applies:

• a type error is reported if the left argument is not simple or has an element that is not a restricted whole number;
• a nonce error is reported if the left argument has more than one element;
• a rank error is reported if the right argument is scalar and the left argument is not 1;
• a maxrank error is reported if the right argument is of rank 9;
• a length error is reported if the left argument is positive and does not evenly divide the number of items in the right argument, or if it is negative and more than one greater in absolute value than the number of items in the right argument (for negative y, if |y equals #x the result has one item, and if it equals 1+#x the result has zero items).
Examples
3!'abcABC'
abc
ABC
˘3!0 1 2 3 4 5 6
0 1 2
1 2 3
2 3 4
3 4 5
4 5 6
+/@1Ű˘3!0 1 2 3 4 5 6
3 6 9 12 15
(+/@1Ű˘3!0 1 2 3 4 5 6)ß3 ă Moving average of length 3
1 2 3 4 5

Result űx

Argument and Result
x is any array and its value is also the result.

Definition
The effect of Result is to exit from the current function or immediate execution code and return x as the result. (In immediate execution, this value will not be displayed if what the A+ display mechanism believes was the last function executed is thought by it to be an Assignment - i.e., the display mechanism may not recognize the exit or it may take the Result arrow to be an Assignment arrow.) The niladic use of this symbol, a bare left arrow (ű), is meaningful only outside function definitions, where its effect is to cause resumption of the most recently suspended function execution, with the workspace size increased if necessary; within a function definition it is ignored. Thus, within a function, ű() causes an exit and the return of a Null result, whereas ű alone has no effect at all.

Warning!  Within protected execution, whether do or Execute, at present Result exits from that function only, with a 0 return code and the Result argument as result;  it does not exit from the function containing the protected execution text.

Example
fact n: {if (n=0) ű1; n«fact n-1}
fact 5
120
fact 0
1

Reverse ÷x

Argument and Result
x is any array. The shape of the result equals the shape of x.

Definition
The result is x with the items reversed. (÷x)[i] is x[(˘1+#x)-i].

Examples
÷É5
4 3 2 1 0
÷É2 5
5 6 7 8 9
0 1 2 3 4

Right Űx

Argument and Result
x is any array. The result is the same shape and type as x.

Definition
The result is the value of the argument. This primitive is useful in separating the right operand from the right argument in an expression, and also in getting just the value of a mapped file.

If there is no parse or value error (see "Common Error Reports"),

• a valence error is reported if there is a left argument.
Examples

ŰaűÉ3    ă Continuation beyond Assignment, so the result is displayed.
0 1 2
ă Separate right argument from data operand using Ű :
2 4 8,@0Ű.5 .25 .125
2 0.5        ă Items of the result are the scalar cells
4 0.25       ă of the arguments joined by Catenate.
8 0.125

Rotate y÷x

Arguments and Result
x is any array. y is a simple array of restricted whole numbers whose shape equals 1ŐŇx unless y consists of a single element (and is then of any rank). The shape and, for simple x, the type of the result equal the shape and type of x.

Definition
Suppose x is a matrix and y is a vector with Ňy equal to 1ŐŇx. Then the result is x with each column vector x[;i] rotated by the number of elements indicated in y[i]. If y[i] is positive, then x[;i] is rotated towards the origin, while if y[i] is negative, x[;i] is rotated away from the origin. If y[i] equals 0, there is no rotation.

If x is a vector and y is a scalar (or other one-element array), then the result is x rotated by the amount y, as described above. If x is a matrix and y has one element, then the result is x with each column vector x[;i] rotated by y. The case for x of higher rank is defined by reshaping x into a matrix with all but the first axis combined into one. Formally, the result is:

(Ňx)Ň(,y)÷((1ŮŇx),«/1ŐŇx)Ňx
Each of the following reports is issued only if there is no parse or value error (see "Common Error Reports") and none of the reports preceding it on this list applies:

• a type error is reported if y is nested or does not consist of restricted whole numbers;
• a rank error is reported if y has more than one element and its rank is not 1 less than that of x;
• a length error is reported if y has more than one element and Ňy is unequal to 1ŐŇx.
Example
0 ˘2 1÷É5 3
0 10  5
3 13  8
6  1 11
9  4 14
12  7  2

Selective Assignment targetűa

Arguments and Result
The right argument a is any array. The left argument is the target of the assignment, and takes one of the forms in the table "Targets of Selective Assignment". The compatibility requirements for the two arguments are discussed in the definition. The explicit result is a, except that its type will be that of the selected subarray (see Definition) if they are both numeric but one is integer and the other floating point.

Definition
See also Assignment. Like it, Selective Assignment, in any form, cannot be the operand of an operator.

Each of the various forms of the left argument (see the table "Targets of Selective Assignment"), if executed separately from Selective Assignment, produces a subarray of some target array that appears in the left argument. Executed in Selective Assignment, it selects a subarray of locations in the target array. The effect of Selective Assignment is to replace the values of the target array at the locations specified in the selected subarray by the values in a.

The conformability rule for Selective Assignment is that the shape of the selected subarray must be identical to the shape of the right argument a unless a has only one element.

The type rule is that the selected subarray and a must be of the same general type, with one additional requirement: if the type of the selected subarray is integer and a is floating point, then a must consist entirely of restricted whole numbers, so that it can be coerced to integers before insertion in the selected subarray.

If the same location appears repeatedly in the selected subarray, then in general several distinct values in a will thereby be specified for that one location. The element of a that is actually chosen as the new value for that location is the one with the highest index in ,a. See the examples.

A description of each basic form of Selective Assignment follows.

Performance Note: Assignment In Place

Choose Assignment, (...#x)űy, and the corresponding Bracket Assignments, x[...]űy, are the only assignments guaranteed to be done in place - i.e., without copying x to a new location while revising it. Append Assignment, x[,]űy, is performed in place if there is enough space. All other Selective Assignments, like ordinary Assignment to an existing variable, involve copying the target variable while revising it.

Bracket Indexing Selective Assignment

Bracket Indexing can be used to select subarrays as values. It can also be used, in the same form, on the left side of the Assignment arrow to select subarrays of locations for assignment of new values.

Replace All (x[]űa)

This is a special form of Bracket Indexing Selective Assignment; it would be just a particular case except that it applies to scalars also. It replaces all the elements in the variable named on the left of the assignment arrow. It is the most efficient way to replace all elements of a mapped file; see "Mapped Files".

Append (x[,]űa)

This is a special form of Bracket Indexing Selective Assignment for appending items to an array. x must not be a scalar, else a rank error is reported. The conformability rule is that the shape of the items of x must be identical to the shape of either a or its items, except that a can be a scalar for any x (and, as with any scalar extension, a scalar a can "disappear" - be extended to empty - if the items of x are empty).

Append can cause an itemwise invalidation of an itemwise dependency. See "Recognition of Itemwise Changes".

• A length error is reported if there is a preset callback on an Append Assignment and the callback function changes the shape of the data to be appended, so that it no longer agrees with the indices that were passed to the callback function as an argument.
Targets of Selective Assignment
Target Type Target Form (see below regarding f and see below regarding , (Ravel))
dyadic(y f x)(y#,x) (y f pŘx)(y#,pŘx)
generalf{...;x}#{y;,x} f{...;pŘx}#{y;,pŘx}
index expressionx[a;...;c](,x)[a] (pŘx)[a;...;d](,pŘx)[a]
choose((a;...;c)#x)(a#,x) ((a;...;d)#pŘx)(a#,pŘx)
append x[,]
replace allx[]

Warning! The forms (f,x), (f,pŘx), (y f,x), (y f,pŘx), f{...;,x}, and f{...;,pŘx} are accepted, but unless f is Choose (#) the Ravel (,) is ignored!

In this table, f denotes either a primitive or a defined function, appropriate to the particular form - or f can be omitted. x, the target array, denotes a variable name or %y or c%y, where c and y are any expressions producing simple scalar symbols, but x cannot denote %ˇv or c%ˇv. The variable named by x is the one that is modified.

Primitive Functions in Selective Assignment Expressions

Some A+ primitive functions can be used in expressions on the left of the assignment arrow. They are:
Take, Drop,
Replicate, Expand,
Ravel, Item Ravel, Reshape,
Rotate, Reverse,
Transpose, Transpose Axes.
(By the way, ((j;i)Řa)űb is a valid Selective Assignment, although (iŘjŘa)űb is not.)

For a monadic primitive function f in the above list, the form of the specification is, in the simplest case:

(f x)űa
The definition is as follows: first evaluate
iűf ÉŇx
where x represents a variable name, and then do the Bracket Indexing Selective Assignment:
(,x)[i]űa
This definition is based on the following facts:

• the elements of ÉŇx are exactly all the indices of ,x;
• for each monadic primitive f listed above, ^/(,f ÉŇx)Ĺ,ÉŇx has the value 1. That is, all elements of f ÉŇx are valid indices of ,x.
The definition for a dyadic primitive function is similar. In this case the right argument x of the primitive function, which must represent a variable name, is the target of the assignment and the left argument y is any array for which y f x is valid. Then
(y  f  x)űa
is defined by
iűy f ÉŇx
(,x)[i]űa

Defined Functions in Selective Assignment Expressions

Defined functions can also be used on the left side of the assignment arrow. The definition is the same as the one above for primitive functions, only now it is up to the programmer to see that the function, when applied to arrays whose values are in Én, produces results whose elements are all members of Én.

Brace Assignment ({w;y;...;z;x}űa)

The general form f{w;y;...;z;x}űa has a syntactic special case, where the function name is not present:
{w;y;...;z;x}űa
is permitted and is equivalent to x[]űa. In particular, {x}űa is equivalent to x[]űa.

Separate Symbols Öx

Argument and Result
The argument and result are simple arrays of symbols. The shape of the result is the same as that of the argument except that a last axis of length 2 has been added; i.e., the result shape is (Ňx),2.

Definition
Each element of the argument is separated into two symbols, the first coming from whatever precedes the rightmost dot, and the second from whatever follows it; if there is no dot, a leading one is assumed. Unqualified names and root-context names cannot be distinguished in the result of this function.

Example
Ö`x `.y `c.z `a.b.d
yields
`    `x
`    `y
`c   `z
`a.b `d
If there is no parse or value error (see "Common Error Reports"),

• a maxrank error is reported if the rank of the argument is nine.

Shape Ňx

Argument and Result
The argument is any array. The result is a vector of integers with an element for each axis of the argument.

Definition
The shape of a scalar is É0 because a scalar has no axes. For a nonscalar the ith element of the result is the ith dimension of the argument. That is, if the result is r then r[i]-1 is a valid index of the ith axis of x, but r[i] is not.

Examples
Ň 3 4Ň0
3 4
Ň 10 20 30 40
4
Ň 'The Cat in the Hat'
18
Ň 42
ă This is the display of the empty integer vector.
Ň É5
5

Signal Ůx

Argument and Result
x is a simple symbol or character array.

Definition
The effect during function execution is to signal an error in the current function, display the text of the first symbol of x or the ravel of the character array x as an error message, and cause a suspension at the statement where the current function was called. In protected execution, it returns error code -1. Outside function execution and protected execution, it simply aborts execution of the expression, without any message.

The following report is issued only if there is no parse or value error (see "Common Error Reports"):

• a domain error is reported if the argument is not a simple symbol or character array.
Example
f1 a:1+f2{a}
f2 x:if (x=0) Ů`zero else 2«x
f1 2
5
f1 0
f2: zero
*     \$si
f1 0
.f1: 1+f2{a}
*     a
0
*     ý

Solve y­x

Arguments and Result
x and y are numeric arrays whose ranks are less than or equal to 2, with #y equal to #x. The result has shape (1ŐŇx),1ŐŇy.

Definition
y­x equals (­x)+.«y. If x is a nonsingular matrix with the same number or rows as columns, the result is the solution a to the linear system of equations y equals x+.«a. If x is a matrix with more rows than columns, and if the columns are linearly independent, the result is the least squares solution a to that linear system of equations. That is, a is the array for which +/(y-x+.«a)*2 has the smallest possible value for each element.

The following reports are issued only if there is no parse or value error (see "Common Error Reports"):

• a rank error is reported if the rank of either argument exceeds 2;
• a domain error is reported if (1) an argument is not a simple numeric array, or (2) an argument is a matrix with more columns than rows, or (3) the right argument is singular or very illconditioned.
Example
Given the following linear system of equations:
10 = 3x + 5y -  z
-3 = 7x - 2y + 4z
5 =  x +  y + 2z
the solution vector (x,y,z) can be determined as follows:
10 ˘3 5 ­ 3 3Ň3 5 ˘1 7 ˘2 4 1 1 2
˘.5180722892 2.602409639 1.457831325

Stop ^x

Argument and Result
x is any array, and its value is the explicit result.

Dependency
The value of the system variable `stop, which is set by the Stop command (\$stop) and the Set System Variable function (_ssv).

Definition
The effect of this function depends on the setting of `stop. Either the function has no effect (when `stop is 0), or it causes execution to halt (when `stop is 1), or it causes x to be displayed (when `stop is 2). A Stop halt is the same as an error halt, except that it can occur within protected execution (â or do).

Example
sum{x}:{
zű0;
(iűx) do ^zűz+i+1  ă Call Stop function after each "".
z }
\$stop 0             ă No effect.
sum 3
6
\$stop 1             ă Actual stop each iteration.
sum 3
: stop
*     i,z                ă Check i and z.
0 1
*     ű
: stop
*     zűz+10             ă Give z a little boost.
*     ű
: stop
*     &0                 ă Check the top of the stack.
16
*     ű
16                      ă The doctored result.
\$stop 2             ă Display the value each iteration.
sum 3
1
3
6
6                       ă The result of sum 3.

Take yŮx

Arguments and Result
The argument y is a simple one-element array whose value is a restricted whole number, and x is any array. A scalar x is treated as a one-element vector. The shape of the result equals the shape of the right argument x for all but the first axis, while the first dimension is the absolute value of y.

Definition
There are four cases for Take, depending on whether or not y is nonnegative, and whether or not |y is less than or equal to #x. The result always has |y items. The two cases when |y is less than or equal to #x are the most straightforward: the result consists of the first y items of x if y is nonnegative, and the last -y items if y is negative. See the first two examples.

In the two cases where |y is greater than #x, the difference (|y)-#x represents the number of excess items in the result . These excess items consist entirely of fill elements (see the "Fill Elements" table). Let F be the array of excess items. The shape of F equals the shape of x along all but the first axis, while the length of the first axis is (|y)-#x. The result is the catenation x,F if y is nonnegative, and F,x if y is negative. See the last two examples.

Each of the following reports is issued only if there is no parse or value error (see "Common Error Reports"), and nonce only if there is no type error:

• a type error is reported if the left argument is nested or is not all restricted whole numbers;
• a nonce error is reported if the left argument has more than one element.
Examples
3ŮÉ5 2
0 1
2 3
4 5
˘3ŮÉ5 2
4 5
6 7
8 9
5Ů10 20 30
10 20 30 0 0
˘5Ů10 20 30
0 0 10 20 30
5Ů`a`b`c
`a `b `c ` `

Transpose ôx

Argument and Result
x is any array. The shape of the result is the reverse of the shape of x, i.e., ÷Ňx.

Definition
The result is x with its axes reversed. In particular, if x is a matrix then its rows become the columns of the result, and its columns become the rows. More generally, for any x and any nested vector of simple vectors y for which y#x is valid
y#x űý ô(÷y)#ôx
If y selects a scalar, then the equivalence is simply y#x űý (÷y)#ôx.

Example
ôÉ2 3
0 3
1 4
2 5

Transpose Axes yôx

Arguments and Result
x is any array. y is a simple vector of restricted whole numbers whose length equals the rank of x, i.e., Ňy equals ŇŇx (unless y is a scalar, which is treated as a one-element vector, yielding the uninteresting case 0ôx űý x for vector x). The rank of the result is equal to the number of distinct elements in y, so it is equal to or less than the rank of x.

Definition
The result is x with its axes permuted and coalesced according to y. The elements of y must all be in ÉŇŇr, where r denotes the result, and no element of ÉŇŇr can be missing from y. The elements of y specify where in the result the corresponding axes of x appear. For instance, if x has three axes and y equals 2, then axis 1 of x becomes axis 2 in the result. See the first example. If y contains duplicates, then, for each set of duplicates, the corresponding axes in x are coalesced into one axis in the result, and the length of the resulting axis is the least of the lengths of the coalesced axes. In particular, if x is a matrix then 0 0ôx is the diagonal of x. See the second and third examples.

In terms of indices, if i is a vector of indices which selects an element of x, then there are two possibilities. (1) For some set of coalesced axes, the corresponding elements of i are different. Then the indexed element of x is not in yôx. (2) The element is in yôx and its indices there are i[yÉÉŇŇyôx] (using, for each set of coalesced axes, the index for the first axis in the set, as an arbitrary choice).

Each of the following reports is issued only if there is no parse or value error (see "Common Error Reports") and none of the reports preceding it on this list applies:

• a type error is reported if the left argument is nested or does not consist of restricted whole numbers;
• a rank error is reported if the left argument is not a scalar or vector, or if its length is unequal to the rank of the right argument;
• a domain error is reported if the left argument contains a negative number or does not contain all the restricted whole numbers between zero and its largest element, inclusive, possibly with duplications.
Examples
0 2 1ôÉ2 3 4
0  4  8
1  5  9
2  6 10
3  7 11

12 16 20
13 17 21
14 18 22
15 19 23
0 0ôÉ2 3
0 4
1 0 0ôÉ2 3 4
0 12
5 17
10 22

Argument and Result
The argument is any array; if the argument is a function expression it must be in braces. The result is a symbol scalar.

Definition
The result is the type of the first item of the argument, represented as a symbol. The types are:

character, integer, floating point, null, symbol, function, and box
(`char, `int, `float, `null, `sym, `func, and `box, respectively).

Symbol, function, and box items can be mixed in a single array. See the last three examples in the set that follows. There is also a type included to provide for possible weird cases; its symbol is `unknown.

Examples
`char
`int
`float
`sym
©{+} ă The parser needs the braces as a hint when a function is an argument.
`func
`func    ă Function scalar and function expression are both type `func.
`null
`box
`sym
`box
(<{+}),`a,<1251
`func

Unpack Îx

Argument and Result
x is a simple array composed entirely of symbols. The result r is a simple character array whose shape along all axes except the last is Ňx. I.e., ˘1ŐŇr is Ňx.

Definition
Pack is the left inverse of Unpack. That is, for any array x composed entirely of symbols, ÂÎx equals x. The result has one more axis than x, the last. Each character vector along the last axis of the result consists of the characters - except for the leading backquote - in the display of the corresponding symbol of x, perhaps padded with blanks on the end. The last dimension of the result is the largest number of characters in any of these vectors, before padding.

The following reports are issued only if there is no parse or value error (see "Common Error Reports"):

• a maxrank error is reported if the rank of the result would be greater than nine;
• a type error is reported if the argument is not a simple array of symbols.
Example
Î`a `abc
a
abc

Value %x

Argument and Result
x is a scalar symbol that contains a user global name (see "User Names" and "Symbols and Symbol Constants"). The result is an array or a function.

Definition
If the name in the symbol x is not qualified by a context name, then the current context is assumed. If it is so qualified, the designated context is assumed. For example, `v.a refers to a in the context v, `.a refers to a in the root context, and `a refers to a in the current context. See the example with the function f below.

There are two cases. If the thing named by the symbol x is a global variable, the result is the value of that variable. If the thing is a defined function (not a primitive function, because a primitive function does not have a user name), then the result is that function: if %x occurs bare, the function definition will be displayed; if it occurs with argument(s) the function will be executed, provided general function form is used, with those arguments in braces.

Unlike Execute, Value can be used on the left of Assignment to set the value of a global variable.

The following reports are issued only if there is no parse error (see "Common Error Reports"). A value error report (another of the common error reports) can happen here because either Îx is not a user name or it lacks a global value. A value error will be reported only if there is no type or rank error.

• A type error is reported if the type of x is not symbol.
• A rank error is reported if x is not a scalar.
• If x names a defined function, any further errors will be reported for that function.
Examples
sq x:x*2
fű`sq
xű11 12 13
aű`x
%f
sq x:x*2
(%f){%a}
121 144 169
aűÉ4
%`a
0 1 2 3
(%`a)ű'new'   ă Value can be used on the left of Assignment.
a
new
%`q           ă q has no value.
.q: value
*      ý
f x:{
aűx;        ă Set local a
Őa;         ă Display local a
Ő%`a;       ă Display global a, current context.
Ő%`.a; }    ă Display global a, root context.
aű1 2 3
f 5
5
1 2 3             ă The current context is the root context.
1 2 3
\$cx cc        ă Set a new context.
aű4 5 6       ă Set a in the new context, cc.a
f 5
5                 ă The local a
4 5 6             ă The value in the current context, cc
1 2 3             ă The value in the root context.

Value in Context y%x

Arguments and Result
x and y are scalar symbols such that yÖx is a symbol containing a user global name (see "User Names" and "Symbols and Symbol Constants"). The result is an array or a function.

Definition
Value in Context generates the name it uses in one of two ways:

The root context is represented by ` (the blank or empty symbol: just backquote alone).

There are two cases. If the thing named by y and x is a global variable, the result is the value of that variable. If the thing is a defined function (not a primitive function, because a primitive function does not have a user name), then the result is that function: if y%x occurs bare, the function definition will be displayed; if it occurs with argument(s) the function will be executed, provided general function form is used, with those arguments in braces.

Unlike Execute, Value in Context can be used on the left of assignment to specify the value of a global variable in a context. And unlike Execute in Context, Value in Context in effect constructs a qualified name and then evaluates it. Within a defined function or operator, `cxt%`x always refers to the global variable cxt.x, whereas `cxtâ'x' refers to the local variable x if there is one, and only if there is no such local variable does it refer to cxt.x.

The following reports are issued only if there is no parse error (see "Common Error Reports"). A value error report (another of the common error reports) can happen here because either x and y do not define a user name or the name they produce lacks a global value. A value error will be reported only if there is no type or rank error. An error report for x is preferred to an error report for y.

• A type error report indicates that the type of x or y is not symbol.
• A rank error report indicates that x or y is not a scalar.
• If a defined function is named by y and x, any further errors will be reported for that function.
Examples
my.aűÉ4
cxű`my
vű`a
cx%v                 ă Value of a in the context my
0 1 2 3
`anything%`my.a      ă `anything is ignored.
0 1 2 3
xű30 40
\$cx your
`%`x                 ă Value of x in the context.
30 40
cx%`x                ă The value of cx is my
my.x: value
*     ý
my.aűÉ4
(cx%v)ű'new'
my.a
new 