Nonscalar Primitive Functions

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.

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

Strand Assignment

Value and Value in Context Assignment

Bins yèx

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

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.

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.

Cast y©x

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.

Catenate y,x

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.

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.

Choose y#x

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.

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.

Count #x

The argument is any array. The result is a scalar integer.

Deal y?x

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.

Decode yÂx

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.

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.

     ã 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

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.

     _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

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

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.

     ½'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

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.

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.

Drop yÕx

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.

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.

Enclose <x

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.

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.

     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

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

Execute âx

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.

Execute in Context or Protected Execute yâx

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.

Expand y\x

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

Find yÉx

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.

Comparison tolerance, if an argument is in floating point.

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.

Format yîx

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.

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.

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.

Grade down çx

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.

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

Grade up èx

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.

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

Interval Éx

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.

Item Ravel !x

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.

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.

Laminate y~x

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.

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.

Left yÝx

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

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.

     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

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

Comparison tolerance, if an argument is in floating point.

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.

     '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

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.

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.

Member yÅx

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.

Comparison tolerance, if an argument is in floating point.

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.

Null Ýx

x is any array.

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

     Ý'junk'
     ()½Ý9 10
 1

Pack Âx

x is a simple character array. The result is an array of symbols with shape ¢1ÕÒx.

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.

Partition yÚx

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.

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.

Partition Count Úx

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

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.

Pick yØx

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.

Print Õx

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

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

     2+Õ3
 3
 5

Rake Åx

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

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.

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

The argument x is any array. The result is a vector of shape «/Òx.

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.

     a
 101   2
   3 ¢45
  34  21.5
     ,a
 101 2 3 ¢45 34 21.5

Raze Øx

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.

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.

Replicate y/x

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.

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.

Reshape yÒx

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

Restructure y!x

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.

Result ûx

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

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

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

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

Reverse ÷x

x is any array. The shape of the result equals the shape of x.

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

     փ5
 4 3 2 1 0
     փ2 5
 5 6 7 8 9
 0 1 2 3 4

Right Ûx

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

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.

Rotate y÷x

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.

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

Selective Assignment targetûa

Bracket Indexing Selective Assignment

Replace All (x[]ûa)

Append (x[,]ûa)

Primitive Functions in Selective Assignment Expressions

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

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

     (f x)ûa

The definition is as follows: first evaluate

      iûf ÉÒx

where x represents a variable name, and then do the Bracket Indexing Selective Assignment:

     (,x)[i]ûa

This definition is based on the following facts:

• the elements of ÉÒx are exactly all the indices of ,x;
• for each monadic primitive f listed above, ^/(,f ÉÒx)Å,ÉÒx has the value 1. That is, all elements of f ÉÒx are valid indices of ,x.

The definition for a dyadic primitive function is similar. In this case the right argument x of the primitive function, which must represent a variable name, is the target of the assignment and the left argument y is any array for which y f x is valid. Then

     (y  f  x)ûa

is defined by

     iûy f ÉÒx
     (,x)[i]ûa

Defined Functions in Selective Assignment Expressions

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

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

The general form f{w;y;...;z;x}ûa has a syntactic special case, where the function name is not present:

{w;y;...;z;x}ûa

is permitted and is equivalent to x[]ûa. In particular, {x}ûa is equivalent to x[]ûa.

Separate Symbols Öx

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.

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.

     Ö`x `.y `c.z `a.b.d

yields

 `    `x
 `    `y
 `c   `z
 `a.b `d

Shape Òx

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

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.

     Ò 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

x is a simple symbol or character array.

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.

Solve y­x

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.

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

Stop ^x

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

Take yÙx

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.

Transpose ôx

x is any array. The shape of the result is the reverse of the shape of x, i.e., ÷Òx.

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.

     ôÉ2 3
 0 3
 1 4
 2 5

Transpose Axes yôx

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.

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

Type ©x

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

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.

     ©'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

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.

Value %x

Value in Context y%x