Nonscalar Primitive Functions


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:

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:

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

     a1; b2;
     f{s;d;i;p;c;v}:v
     (a;b)(b  `a`b _scb <(f;); a3)
 `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 xa 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"):

   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.
     ab                         Okay.
     b2 3                      An invalid label value.
     ab                         Specification fails.
 : invalid
*     

Bins yx

   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 1y. 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#rCondition (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]
#yy[(#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:

   Examples
     1 0 1  0.3 0.3 2 .1 1 5
 2 1 0 2 2 3

     v?50001000      sample set of random numbers
 Put in cells; count how many in each cell, showing distribution of the random numbers:
     +/((1001+10)v).=10
 494 480 477 533 506 472 521 512 524 481
 An equivalent but slightly faster way; shows distribution of the set:
     +/(<(1001+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,kx.

   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:

   Examples
     (2 3 4)[1;2;3]
 23
     'adrv'[2 30 0 2 3 0 2]
aar
var
     (5 5 5)[0;2;3]
 0 1 2
 5 6 7
     (5 5 5)[0;2 50 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 yx

   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 `symx is `null.)
The shape of the result is:
x if x and the result are neither or both symbolic; else
1x 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:

   Examples
     `char97      Return character.
a
     `int3.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:

The result has the same type as:

   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:

   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),1x.

If y is nested, the result is

     x[0y;1y;...;(1+#y)y]
If iy 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[0y;...;(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:

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

   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 yx

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

   Examples
      Convert 2 hours, 5 minutes, and 59 seconds to seconds.
     24 60 602 5 59
 7559
      Present value (price) from interest rate and cash flows.
     cf0 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+.015) @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"),

   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:

   Example
     >(3;103)
 0  1  2
 0 10 20

Drop yx

   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:

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

   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, yx 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, yyx 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:

   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:

   Examples
     100'1 1.23 4.567'
 100 123 456.7
     'a14 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 yx

   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:

   Example
     try.x3
     'x10'        try.x has a value, but x does not.
 .x: value
*      
 : domain          Error gets passed on to Execute.
*      
     0'x10'       Protected execute (`Gf is 1).
 4                  Numeric code for the value error.
     `try'x10'    Execute in Context okay; uses try.x.
 0 0.1 0.2
                    Protected execute using the var that has a value:
     0'try.x10'
<  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:

and, unless there is one of +^ to the immediate left of \ (that is, unless you are thrown into Scan, a monadic operator):

   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 yx

   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 1y. 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:

   Examples
     (4 3'fatbatcathat')(2 3'catpat')
 2 4
     (+;-;;)<{}
 2    Strand makes function expression a function scalar.

Format yx

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

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:

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:


     v1.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.2v
    Rounding    
Actual Internal
Value
1.0551.061.05    1.05499999999999994...    
1.1551.161.161.15500000000000003...
1.2551.261.251.25499999999999989...
1.3551.361.351.35499999999999998...
1.4551.461.461.45500000000000007...
1.5551.561.551.55499999999999994...
1.6551.661.661.65500000000000003...
1.7551.761.751.75499999999999989...
1.8551.861.851.85499999999999998...
1.9551.961.961.95500000000000007...

Notice that using 6.2v 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:

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:

   Examples

     2 10.4 12.22 31 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.121.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:

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

   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:

   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 (/2x),2x and the same type as the argument.

   Definition
The result is ((/2x),2x)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"):

   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:

   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:

   Example
     1 2 3~10 20 30
  1  2  3
 10 20 30

Left yx

   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]  a0 2 4 5 1 3 7 6
 0 1 2 3 4 5 6 7
     ((aa)=a)/a  a'keep only the unique characters'
keponlythuiqcars

Match yx

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

   Example
      2 2 1 2 3 4
 2    1
  1.5 0.5

Member yx

   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 1x. 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:

   Examples
     (123+1e-10 1e-11)123,1950+50
 0 1
     1992 1991 1870 1992 2001123,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 1x.

   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, `char0, 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"):

   Example
     2 3'a  abc'
 `a `abc

Partition yx

   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:

   Examples
     3 2 2 16 3
<  0 1 2
   3 4 5
   6 7 8
<   9 10 11
   12 13 14
<  15 16 17
<
     35
<  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:

   Examples
     1 0 0 0 1 0
 4 2
     1 0 0 0 1 1 0 1
 4 1 2 1

Pick yx

   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 0x, then yx is defined and equals >1x.

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:

     yx  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
  11 2 3 2
  02 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 yx (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 yx 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 (ija)b is not.

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

   Examples
     1('ab';(2 2'cdef';10 20))
< cd
  ef
<  10 20
     01('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:

   Examples
     ('ab';'cde';'f')
 abcdef
     (2 3;102 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:

and, unless one of +^ is to the immediate left of /, throwing you into Reduce, a monadic operator:

   Examples
     3 0 1/3 2'abcdef'
ab
ab
ab
ef
     (a0)/a4 1 3 0 8 5      Compress.
 4 3 0 8
     2 0 3 0/'a'
aaaaa

Reshape yx

   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:

   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.

   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:

   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; nfact 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"),

   Examples

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

   Arguments and Result
x is any array. y is a simple array of restricted whole numbers whose shape equals 1x 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 1x. 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)((1x),/1x)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:

   Example
     0 2 15 3
  0 10  5
  3 13  8
  6  1 11
  9  4 14
 12  7  2

Selective Assignment targeta

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

Targets of Selective Assignment
Target Type Target Form (see below regarding f and see below regarding , (Ravel))
monadic(f x)(,x) (f px)(,px)
dyadic(y f x)(y#,x) (y f px)(y#,px)
generalf{...;x}#{y;,x} f{...;px}#{y;,px}
index expressionx[a;...;c](,x)[a] (px)[a;...;d](,px)[a]
choose((a;...;c)#x)(a#,x) ((a;...;d)#px)(a#,px)
append x[,]
replace allx[]

Warning! The forms (f,x), (f,px), (y f,x), (y f,px), f{...;,x}, and f{...;,px} 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 (ija)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
      if 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 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
     iy 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:

   Examples
     v10
     v[2 2 2]5 9 1   Repeated indices
     v
 0 1 1 3 4 5 6 7 8 9

     m4 4
     0 0m             Diagonal
 0 5 10 15


     (0 0m)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
     a3 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 0x    Pick-Choose selection
 4                  Present value of selected component


     ((1;1)#2 0x)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
     v10          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"),

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 40
 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"):

   Example
     f1 a:1+f2{a}
     f2 x:if (x=0) `zero else 2x
     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 (1x),1y.

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

   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 33 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}:{
      z0;
      (ix) do ^zz+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
*     zz+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 yx

   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 argumentFill element
numeric0
characterblank
symbolthe empty symbol
nestedenclosed 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:

   Examples
     35 2
 0 1
 2 3
 4 5
     35 2
 4 5
 6 7
 8 9
     510 20 30
 10 20 30 0 0
     510 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 yx

   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 0x 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 0x 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 yx. (2) The element is in yx and its indices there are i[yyx] (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:

   Examples
     0 2 12 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 02 3
 0 4
     1 0 02 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., 1r 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"):

   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.

   Examples
     sq x:x*2
     f`sq
     x11 12 13
     a`x
     %f
sq x:x*2
     (%f){%a}
 121 144 169
     a4
     %`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:{
       ax;         Set local a
       a;          Display local a
       %`a;        Display global a, current context.
       %`.a; }     Display global a, root context.
     a1 2 3
     f 5
 5
 1 2 3              The current context is the root context.
 1 2 3
     $cx cc         Set a new context.
     a4 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 yx is a symbol containing a user global name (see "User Names" and "Symbols and Symbol Constants"). The result is an array or a function.

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

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

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

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

   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.

   Examples
     my.a4
     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
     x30 40
     $cx your
     `%`x                  Value of x in the context.
 30 40
     cx%`x                 The value of cx is my
 my.x: value
*     
     my.a4
     (cx%v)'new'
     my.a
new


doc@aplusdev.org© Copyright 1995–2008 Morgan Stanley Dean Witter & Co. All rights reserved.