A+ Reference: Nonscalar Primitive Functions

# Nonscalar Primitive Functions

Classification of Nonscalar Primitive Functions
Common Error Reports
Function Definitions

Assignment xûa and (x)ûa

Strand Assignment
Value and Value in Context Assignment
Assignment of Objects Bound to Display Classes

In Separate Chapter on Files: Beam àx and yàx
Bins yèx

Table: Bins for Numeric Vectors

Bracket Indexing x[a;b;...;c]
Cast y©x
Catenate y,x
Choose y#x
Count #x
Deal y?x
Decode yÂx
Default Format îx
Depth ½x
Disclose >x
Drop yÕx
Enclose <x
Encode yÎx
Execute âx
Execute in Context or Protected Execute yâx
Expand y\x
Find yÉx
Format yîx
Grade down çx
Grade up èx
Interval Éx
Item Ravel !x
Laminate y~x
Left yÝx
Match y½x
Matrix Inverse x
Member yÅx
Null Ýx
Pack Âx
Partition yÚx
Partition Count Úx
Pick yØx
Print Õx
Rake Åx
Ravel ,x
Raze Øx
Replicate y/x
Reshape yÒx
Restructure y!x
Result ûx
Reverse ÷x
Right Ûx
Rotate y÷x
Selective Assignment targetûa

Bracket Indexing Selective Assignment
Replace All x[]ûa
Append x[,]ûa
Table: Targets of Selective Assignment
Primitive Functions in Selective Assignment Expressions
Defined Functions in Selective Assignment Expressions
Brace Assignment {w;y;...;z;x}ûa
Selective Assignment of Objects Bound to Display Classes

Separate Symbols Öx
Shape Òx
Signal Ùx
Solve yx
Stop ^x
Take yÙx

Table: Fill Elements

In Separate Chapter on Timing Execution: Time time{} and time x
Transpose ôx
Transpose Axes yôx
Type ©x
Unpack Îx
Value %x
Value in Context y%x

> 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 discussion 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.

### Assignment of Objects Bound to Display Classes

> The assignment primitive xûa is affected by display class bindings. If a is bound but x is not, x does not inherit the class of a or any of its attributes. If x is bound then a must be in the domain of the class of x, i.e., it must be possible to bind a to the class of x. This rule applies to Selective Assignment as well.

Additional Error Report

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

> - an invalid error is reported if x is bound to a display class and the value it is to be given is not valid for objects bound to that display class - see s.VERIFY in the "s-Context Parameters (Global Variables)" table regarding the message that is issued.

Example

> The following illustrates successful and rejected assignments for objects bound to display classes:

>          $load s
>          aû"Spec test"
>          `a is `label
>          bû"any character vector"   ã A valid label value.
>          aûb                        ã Okay.
>          bûÉ2 3                     ã An invalid label value.
>          aûb                        ã Specification fails.
>      û: invalid
>     *     ý

## 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.

> Bins for Numeric Vectors
> Value of i#r | Condition (comparisons without tolerance)
> --- | ---
> 0 | (i#x)¤y[0]
> j, where 0<j and j<#y | y[j-1]<i#x and (i#x)¤y[j]
> #y | y[(#y)-1]<i#x

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

Additional Error Reports

> 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.

Additional Error Reports

> 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;<{+})[1]
>     <  5 1 9
>          Ò(É2 3 4)[É0;'';()]
>      0 0 4

## Cast y©x

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.

Additional Error Reports

> 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

>          `char©97     ã Return character.
>     a
>          `int©3.4 4.5 5.6
>      3 5 6
>          `sym©'abcd'
>      `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.

Additional Error Reports

> 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.

Additional Error Reports

> 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.
>     adg
>          (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)[0] (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.

Additional Error Reports

> 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[0],y[1], ... , 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.

Additional Error Reports

> 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 the string *derived*. (Note that Default Format shows that expressions such as +.« are not derived functions strictly speaking.)

Additional Error Reports

> 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.

Additional Error Reports

> 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.

Additional Error Reports

> 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[0],y[1], ... ,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.

Additional Error Reports

> 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.

Additional Error Reports

> 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".

> Execute in Context is useful when one wants to create multiple instances of a dependency or dependencies, distinguished by contexts. You can create a dependency by, for instance,

>          `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.

> Messages that are not strictly A+ error messages will still appear in the log, e.g.
> filename: No such file or directory
> not an `a object
> and many Adap messages.

> The treatment of input errors while stopped in protected execution is described under monadic do.

> Warning! Within a Protected Execute - as in a protected do - Result exits from Protected Execute only, with a 0 return code and the Result argument as result; it does not exit from the function containing the Protected Execute.

Additional Error Reports

> 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.

Additional Error Reports

> 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.

Additional Error Reports

> 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.055 | 1.06 | 1.05 | 1.05499999999999994...
> 1.155 | 1.16 | 1.16 | 1.15500000000000003...
> 1.255 | 1.26 | 1.25 | 1.25499999999999989...
> 1.355 | 1.36 | 1.35 | 1.35499999999999998...
> 1.455 | 1.46 | 1.46 | 1.45500000000000007...
> 1.555 | 1.56 | 1.55 | 1.55499999999999994...
> 1.655 | 1.66 | 1.66 | 1.65500000000000003...
> 1.755 | 1.76 | 1.75 | 1.75499999999999989...
> 1.855 | 1.86 | 1.85 | 1.85499999999999998...
> 1.955 | 1.96 | 1.96 | 1.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.

Additional Error Reports

> 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.

## Grade down çx

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, which are shown in "Graphic Characters for Atomic Vector". 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.

Additional Error Reports

> 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

## Grade up èx

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, which are shown in "Graphic Characters for Atomic Vector". 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.

Additional Error Report

> 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").

Additional Error Reports

> 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.

Additional Error Report

> 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[0] equals y and item r[1] equals x. If x is nonscalar and y is a scalar then item r[0] equals (Òx)Òy and item r[1] equals x. If x is scalar and y is a nonscalar then item r[0] equals y and item r[1] 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.

Additional Error Reports

> 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.

Additional Error Reports

> 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 ill-conditioned.

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.

Additional Error Reports

> 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.

Additional Error Report

> 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)[0] items of x, the second element is Enclose of the next (,y)[1] 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.

Additional Error Reports

> 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.

Additional Error Reports

> 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.)

> Scalar right argument

> 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[1]Øy[0]Ø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[1]Øy[0]Ø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.

Additional Error Reports

> 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.

Additional Error Reports

> 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.

Additional Error Reports

> 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.

Additional Error Reports

> 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.

> In the case where y is negative or zero, the elements of x are used repeatedly. The result r can be thought of in terms of clipping sections of the first axis of x using a window of length -y. That is, if wûÉ-,y then 0#r is w#x, 1#r is (w+1)#x, and in general i#r is (w+i)#x. See the second example. This form of the function is useful for producing moving averages.

Additional Error Reports

> 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, 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.

Additional Error Report

> 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

Additional Error Reports

> 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).

> Execution of x[,]ûa can be more efficient than xûx,a because if there is enough unused space following x in the storage area allocated to x, the result is formed simply by copying a into that space. Because storage is allocated roughly in powers of two, an array has between exactly and twice the space it needs. In particular, this form of assignment is the only efficient way to extend a mapped file; see "Mapped Files".

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

> Additional Error Report for Append

> > - 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))
--- | ---
monadic | (f x) | (,x) | (f pØx) | (,pØx)
dyadic | (y f x) | (y#,x) | (y f pØx) | (y#,pØx)
general | f{...;x} | #{y;,x} | f{...;pØx} | #{y;,pØx}
index expression | x[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 all | x[]

> 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.

### Selective Assignment of Objects Bound to Display Classes

> See "Assignment of Objects Bound to Display Classes".

Additional Error Reports

> 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:

> - an error is reported if one of the functions selecting the subarray encounters an error; this includes any defined function, so the report may come from a primitive function within a defined function;
> - a type error is reported if the general type of the target differs from the general type of a or if the target is integer but a is floating point and not composed entirely of restricted whole numbers;
> - a rank error is reported if the rank of the selected subarray differs from the rank of a and a is not a one-element array;
> - a length error is reported if corresponding dimensions of a and the selected subarray differ and a is not a one-element array;
> - a maxitems error is reported if an attempt is made to append an item to a mapped file beyond its maximum size as specified by _items (see "Items of a Mapped File");
> - an invalid error is reported if the target array is bound to a display class and the value it is to be given is not a valid value for (the selected part of) objects bound to that display class;
> - an index error is reported if an index not in ÉÒx is generated; the error may not be detected before partial replacement of values has occurred - see the examples.

Examples

>          vûÉ10
>          v[2 2 2]û5 9 ¢1  ã Repeated indices
>          v
>      0 1 ¢1 3 4 5 6 7 8 9

>          mûÉ4 4
>          0 0ôm            ã Diagonal
>      0 5 10 15

>          (0 0ôm)û1 2 3 4  ã Primitive function selection: diagonal.
>          m
>       1  1  2  3
>       4  2  6  7
>       8  9  3 11
>      12 13 14  4

>               ã Display argument, then return last element (to show how
>               ã defined functions are called during Selective Assignment):
>          last x: ¢1Ù,Õx
>          aû3 2Ò'abcdef'
>          last a
>     ab
>     cd
>     ef
>     f

>          (last a)û'F'  ã User-defined function selection.
>      0 1               ã  Argument it was given: ÉÒa, i.e., É3 2
>      2 3
>      4 5               ã It returns 5.

>          a
>     ab
>     cd
>     eF                 ã The new value 'F' was placed at (,a)[5].

>          xû(10;20;(É2 3;'abc'))
>          (1;1)#2 0Øx   ã Pick-Choose selection
>      4                 ã Present value of selected component

>          ((1;1)#2 0Øx)û99   ã Pick-Choose selection for
>          x                  ã Selective Assignment, new value 99
>      <  10
>      <  20
>      < <  0  1  2
>           3 99  5      ã New value is at the selected location.
>        < abc

>          f x:x+5       ã User function to manipulate indices
>          vûÉ10         ã Variable for Selective Assignment
>          (f v)û100+É10 ã Make erroneous Selective Assignment:
>      û: index          ã error detected.
>     *       ý
>           v            ã In time?
>      0 1 2 3 4 100 101 102 103 104
>     ã Not quite. Indices up to first incorrect one were used.

## 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

Additional Error Report

> 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.

Additional Error Report

> 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 yx

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

> yx 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.

Additional Error Reports

> 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 ill-conditioned.

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).

> See "Example of a Defined Function" and, immediately following it, "Errors and Stops" in the appendix.

Example

>          sum{x}:{
>           zû0;
>           (iûx) do ^zûz+i+1  ã Call Stop function after each "zû".
>           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.

> Fill Elements
> General type of right argument | Fill element
> --- | ---
> numeric | 0
> character | blank
> symbol | the empty symbol
> nested | enclosed Null

Additional Error Reports

> 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[1] 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).

Additional Error Reports

> 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

## Type ©x

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

>          ©'a'
>      `char
>          ©42
>      `int
>          ©4.2
>      `float
>          ©`a
>      `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
>          ©<'a'
>      `box
>          ©`a,(<1251),<{+}
>      `sym
>          ©(<1251),(<{+}),`a
>      `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.

Additional Error Reports

> 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.

Additional Error Reports

> 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:

> - if the name represented by the symbol x does not specify a context, then y%x qualifies it by the context named by the symbol y. For example, `ctx%`a uses the name ctx.a;
> - otherwise, the name represented by x specifies a context, as in `ctx.a, and y%x uses that name, and ignores the value of the symbol y. For example, `any%`ctx.a uses ctx.a.
> 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.

Additional Error Reports

> 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