# System Functions

Classification of System Functions
Querying Syntax
Common Error Reports
Definitions of System Functions

The Name Argument
Abort Loading of Script _abortload{}
All Attributes _atts{y;x}
All Dependent Object Names _alldep{x}
Association List to Slotfiller _alsf{x}
Change Directory _cd{x}
Comma Fix Input _cfi{y;x}
Debug _dbg{x}
Dependency Definition _def{x}
Dependent Object Names _dep{x}
Dynamic Load _dyld{x;y}
Execution Profile _profile{x}
Exit _exit{x}
Expunge _ex{x}
Expunge Context _excxt{x}
Fix Input _fi{y;x}
Flatten _flat{x}
Format _fmt{y;x}

Table: Format Phrases
Table: Qualifiers
Table: Decorators

General Search and Replace _gsr{y;x;r;n}
Get Attribute _get{y;x}
Get Callback _gcb{y}
Get Client Data _gcd{y}
Get Format Symbols _gfmtsym{}
Get Preset Callback _gpcb{y}
Get System Variable _gsv{x}
Hash Table Statistics _hashstat{x}
Index of _index_of{y;x}
Is a Slotfiller _issf{x}
Items of a Mapped File _items{y;x}
Load _load{x}
Load and Remove _loadrm{`delete;x}
Locals _locals{x}
Name _name{x}
Name Class _nc{y;x}

Table: Name Classes

Name List _nl{y;x}

Table: Name List Expressions vs. The Kind of Objects in the Result

Name Search _ns{y;x}
Name Search and Replace _nsr{y;x;r}
NaN Find _nanfind{x}
Permissive Indexing _index{i;x;d}
Remove Dependency Definition _undef{name}
Scalar Comma Fix Input _scfi{s}
Scalar Fix Input _sfi{s}
Screen Format _sfmt{f;d}
Set Attribute _set{y;x}
Set Callback _scb{y;x}
Set Client Data _scd{y;x}
Set Preset Callback _spcb{y;x}
Set System Variable _ssv{y;x}
Stack Information _doErrorStack{}
String Search _ss{y;x}
String Search and Replace _ssr{y;x;r}
Valence _valence{x}
Work Area _wa{x}

Table: Arguments and Results for Work Area

# Classification of System Functions

> Although they are listed alphabetically by English name in this chapter, for convenient reference, the A+ system functions can be grouped, among many other ways, in ten categories, dealing with:

> - system variables: Get System Variable, Set System Variable;

> - names and references: Expunge, Expunge Context, Locals, Name, Name Class, Name List, Valence;

> - attributes: All Attributes, Get Attribute, Set Attribute, Get Client Data, Set Client Data;

> - dependencies: All Dependent Object Names, Dependency Definition, Dependent Object Names, Remove Dependency Definition;

> - callbacks: Get Callback, Get Preset Callback, Set Callback, Set Preset Callback;

> - files: Abort Loading of Script, Change Directory, Dynamic Load, Items of a Mapped File, Load a File, Load and Remove a File;

> - format changes: Association List to Slotfiller, Comma Fix Input, Fix Input, Flatten, Format, Scalar Comma Fix Input, Scalar Fix Input, Screen Format, Get Format Symbols, Is a Slotfiller;

> - text functions: General Search and Replace, Index Of, Name Search, Name Search and Replace, String Search, String Search and Replace;

> - indexing: Permissive Indexing;

> - debugging: Debug, NaN Find, Stack Information;

> - A+ operation and space: Execution Profile, Exit, Hash Table Statistics, Work Area.

# Querying Syntax

> To inquire about the syntax of a system function or external function in an A+ session, enter its name alone on a line. For example:

>          _nl
>      _nl{any;any} returns any

> Because some of the system functions take more than two arguments, they are all shown here in general form, for uniformity, and that is how a syntax query is answered. Nevertheless, infix notation can also, of course, be used to invoke the monadic and dyadic system functions.

# 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. Seven reports are common to all system functions:

> - parse;
> - value: an argument has no value;
> - valence: the wrong number of arguments were given;
> - nondata: the argument is a function or some other nondata object;
> - type or domain: an argument is of the wrong type (nested when it should be simple, numeric when it should be a symbol, and so on) or the wrong class (e.g., a symbol, but not from some required set of symbols); the same error is called type by some functions and domain by others;
> - length: a single number is required and the ravel of the argument does not have a length of one;
> - 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 while holding the Control key down.

# Definitions of System Functions

## The Name Argument

> Several system functions take names as arguments. A name argument is one of the following:

> - a symbol holding a valid A+ name, e.g., `var or `ctx.var;

> - a pair of symbols holding a valid A+ context name and a valid name, e.g., `ctx `var.
> These names always refer to global objects. See "Symbols and Symbol Constants".

> The definition of a system function refers to this section if it has an argument that conforms to this definition.

## Abort Loading of Script _abortload{}

Definition

> This system function allows the user to terminate the $loading of a file. Executed in a script, it will terminate that script after the current line is processed. If one script loads a second, and the second script calls _abortload{}, the second script ends immediately, but the first script is not aborted, and continues to be loaded. While the loading of a script is suspended - by an interrupt, error, Stop, or Signal, for example -, entering _abortload{} in the (Emacs or XTerm) session log for execution will terminate its loading, without affecting the suspension.

## All Attributes _atts{y;x}

Argument and Result

> The arguments x and y are described in "The Name Argument". The result is a vector of symbols.

Definition

> Lists all attributes set by _set on y with prefix x. E.g., _atts{`a;`appl} lists all attributes of the form `appl.* set on a. If x is Null, lists all attributes set by _set on y. The attributes are listed in random order. If the variable y does not exist, the result is empty. For a list of attributes set by s (which does not currently use _set), i.e., display attributes, use the settings attribute.

## All Dependent Object Names _alldep{x}

Argument and Result

> The argument x is described in "The Name Argument". The result is a vector of symbols.

Definition

> The result is the transitive closure of _dep{x} (Dependent Object Names): it returns the dependency set of x, to wit, a list containing _dep{x}, _dep¡_dep{x}, etc., with duplicates removed.

> Note that if f is a dependency and `f is contained in the vector _alldep{`f}, then the dependency set _alldep{`f} is cyclic. See "Cyclic Dependencies".

## Association List to Slotfiller _alsf{x}

Argument and Result

> The argument is an association list or a slotfiller. The result is a slotfiller (but see below).

Definition

> This function converts an association list to the equivalent slotfiller. It also accepts slotfillers and returns them unchanged, so that it can be used to obtain a slotfiller from an array that might be either an association list or a slotfiller; no checking is necessary.

> An argument that is an association list whose length is odd is accepted in two cases. If the last element is a symbol, a Null is appended before conversion. If the last element is a Null, it is dropped.

> In one case the result is not actually a slotfiller: if there are duplicates among the symbols that are to be the elements of the first item of the result, the argument is nevertheless accepted and the duplicates are retained.

Example

>          _alsf(`a;1;`b;2;`c;3 4 5)
>     < `a `b `c
>     < < 1
>       < 2
>       < 3 4 5

## Change Directory _cd{x}

Argument and Result

> The argument x is a symbol or character vector. The result is a nested vector with either one or two elements.

Definition

> _cd{x} provides the same function as the $cd command. The argument x specifies the new current directory in Unix format. If the change to the new current directory is successful, the result is 1Ò<`ok; otherwise it is a two-element array of the form (`error;"error message"), for example if there is no such directory. The PWD environment variable is set.

> After a file is loaded, the current directory is the same as it was when the Load function or command was initiated: it is automatically restored if it was changed during execution of the lines of the file.

## Comma Fix Input _cfi{y;x}

Arguments and Result

> y is a simple character array of rank less than or equal to two, and x is a scalar restricted whole number. The result is a two-element nested array of the form (bool;data), where #bool equals #data if y is a matrix and equals 1 otherwise, and bool is an integer array of rank 0Ó¢1+ÒÒy, and data is a numeric array of rank 1ÓÒÒy with ¢1ÙÒdata equal to xÓ0.

Definition

> See "Fix Input" (_fi). The definition of _cfi is the same as Fix Input, except that _cfi permits additional representations (and misrepresentations) of numbers. Specifically, commas and parentheses are permitted in number representations, as well as minus signs, low and the A+ high (¢). In producing the numeric values, commas are ignored no matter where they appear, and high and low minus signs and each set of enclosing parentheses is replaced by a high minus sign. In other words, commas are not treated as "thousands" separators (although they can be playing that role), and all parentheses and - and ¢ are treated as signifiers of negative quantities. For each result number, there can be at most one indication that it is negative: '-¢16', '(-16)', and the like are not accepted. The parentheses that indicate a number is negative must surround the entire number, those that indicate an exponent (in e-notation) is negative just the exponent itself. A left parenthesis may be followed by blanks. Note: blanks between numbers are not required, although their absence is obviously inadvisable; in other words, missing blanks are not used as an indication of possible error any more than missing or extraneous commas are. '1e-3.5-7.6.5' is translated as 1e-3 0.5 ¢7.6 0.5.

> Scalar Comma Fix Input, _scfi, is expected to be used in `in functions, validating user input. _cfi, on the other hand, is designed for larger arrays, such as text files; the assumption is that the data argument is likely to have been machine generated.

Additional Error Reports

> - Nonce error if x is greater than 1000.
> - Rank error if the rank of y exceeds two.

Example

>          _cfi{'(1,200)';1}
>     <  1
>     <  ¢1200.

## Debug _dbg{x}

Argument and Result

> This function takes essentially the same arguments as $dbg and returns essentially the results displayed by it.

Definition

> Provides the functionality of $dbg with different syntax: e.g., _dbg{`cxt;(`only;`)} to trace only the root context. Additionally:

> (1) _dbg{`display;`beam} returns a slotfiller with information about all files currently beamed in. The six fields of the slot filler contain entries for each file:
> `mode - 0, 1, or 2: the file is copy-on-write, read/write, or local write.
> `arg - the righthand argument given to à.
> `fname - the actual file name `arg was turned into.
> `addr - the memory address where the file was mapped.
> `refcnt - reference count: how many A-objects point to the file.
> `bytes - the size of the file in bytes.

> (2) _dbg allows for callbacks at the points where a tracing or tracking message would be displayed. Executing _dbg{`cb;(fn;cd)} sets up the callback function with its client data (static). This function must take five arguments: fn{cd;event;arg1;arg2;arg3}. The events are `func, `xfs, `sfs, `load, `beam, and so on; arg1 is the name of the function, file, or whatever involved; the possible values of arg2 are `enter, `exit, `abort, `in, `out, `unmap, `dep, `func, and how many Infs and how many NaNs; and arg3 is usually null, but for beaming in it is the left argument of à.

> (3) In the event callback for `inv events, the second argument is null for normal invalidation, and equals `cycle if the `inv event is the detection of a cyclic dependency.

## Dependency Definition _def{x}

Argument and Result

> The argument x is described in "The Name Argument". The result is a character vector.

Definition

> The result holds the definition of the dependency named in x. See "Dependencies". If x does not name a dependency, the result is Null.

## Dependent Object Names _dep{x}

Argument and Result

> The argument x is described in "The Name Argument". The result is a vector of symbols.

Definition

> The result contains the names of all dependencies whose definitions explicitly reference the object named in x. See "Dependencies".

## Dynamic Load _dyld{x;y}

Arguments and Result

> The argument x is a character vector and the argument y is a nested vector. The result is a scalar integer.

Definition

> The effect of this system function is to load C functions into A+ so that they can be used like ordinary user functions. (But the fixed number of arguments for a C function being _dylded cannot exceed 8.) The details can be found in "Calling C Subroutines from A+". System error messages are also displayed. If this function is not available, the Dynamic Environment system variable, `dyme, has the value -1. It is safe to _dyld an object already _dylded.

> Warning! A cover function that takes care of the requirements of different architectures should be used rather than a direct invocation of _dyld, except when "hacking".

> Warning! If the A+ name used in _dyld (in its right argument) begins with an underscore, then the function will be installed in the root context, no matter what the current context, and it will be listed by $sfs but not by $xfs.

## Execution Profile _profile{x}

Argument and Result

> A meaningful argument is a scalar symbol, one of `on `off `report `reset. If the argument does not cause an error - i.e., if it is a one-element array - then the explicit result is the scalar integer 0.

Definition

> This facility is enabled by executing _profile `on and disabled by _profile `off. When not enabled, it adds absolutely no overhead to primitive function calls.

> When it is enabled, executing _profile `report causes a report to be displayed that gives the number of primitive function executions by function, data type, and array size range (number of elements) since the last time _profile `on or _profile `reset was executed.

## Exit _exit{x}

Argument and Result

> The argument x is a scalar integer. There is no result.

Definition

> The expression _exit{x} provides a similar function to the system command $off. The argument x is the value returned when the A+ process terminates. Proper values for x are 0 through 255, although any integer is accepted; by convention, the value 0 means success. Since execution of this system function causes the A+ process to exit, it has no meaningful result. See "Invoking A+".

## Expunge _ex{x}

Argument and Result

> The argument x is described in "The Name Argument". The result is an integer scalar.

Definition

> _ex provides the same function as $ex. The object named in x is removed and its associated memory is freed. The result is 0 if the removal is successful, and 1 otherwise. In particular, the result is 1 if the object does not exist. It is also 1 if x is an object bound to a display class (see "is" and "free"); i.e., a bound object cannot be expunged.

## Expunge Context _excxt{x}

Argument and Result

> The argument x is described in "The Name Argument". The result is an integer scalar.

Definition

> The context named in x must be empty. If it is, _excxt{x} removes it from the active workspace and returns 0. If the context is not empty, _excxt returns 1. The Name List system function with arguments x and `globs can be used to list all objects that would prevent the expunging of a context. See the "Name List" (_nl{y;x}) function. See also "Expunge Context" ($excxt).

> The root context cannot be expunged; an attempt to expunge it yields a result of 1. For a nonexistent context, the result is 1.

## Fix Input _fi{y;x}

Arguments and Result

> y is a simple character array of rank less than or equal to two, and x is a scalar restricted whole number. The result is a two-element nested array of the form (bool;data), where #bool equals #data if y is a matrix and equals 1 otherwise, and bool is an integer array of rank 0Ó¢1+ÒÒy, and data is a numeric array of rank 1ÓÒÒy with ¢1ÙÒdata equal to xÓ0.

Definition

> This function creates a numeric array with xÓ0 elements derived from each row of y (or from y itself, if it is a scalar or vector). If a valid vector is created for the row i#y, it becomes i#data, and i#bool is assigned 1. If i#y does not contain the representations of exactly xÓ0 numbers, then i#bool is assigned 0, and i#data is created by using the first xÓ0 valid nonblank sequences in i#y, and using zeros as fillers if there are not enough valid nonblank sequences. (The term nonblank suggests how you should use the function, with blanks as separators, but see the note with which this definition ends.) If there is a nonblank sequence in i#y that does not represent a number, then i#data contains zeros from the point of invalidity on.

> Each row of the argument y for which a valid numeric vector can be created must consist of x common representations of numbers. A common representation is one of the three general forms produced by the Default Format monadic primitive function î, namely integer, fixed-point, and exponential, except that low and high minuses are accepted indifferently: a low minus is accepted at the beginning of any number and in exponential form a high minus is accepted in the exponent. The expression

>          bool/É#y

> yields the row indices of y for which a valid numeric vector was created. Note: blanks between numbers are not required. 1e-3.5 7.6.5-2 is translated as 1e-3 0.5 7.6 0.5 ¢2.

Additional Error Reports

> - Nonce error if x is greater than 1000.
> - Rank error if the rank of y exceeds two.

Examples

>          Õaû3 5Ò'1.34 2 3  2x50 '
>     1.34
>     2 3
>     2x50
>          a _fi 1
>     < 1 0 0
>     <  1.34
>        2
>        2
>          a _fi 2
>     < 0 1 0
>     <  1.34 0
>        2    3
>        2    0

## Flatten _flat{x}

Argument and Result

> The argument x is any array whose simple components are of one type, except that symbols and functions may be mixed and nulls are essentially ignored. The result is a simple vector whose length is the total number of elements in all the simple components of x and whose type is that of the first nonempty simple component of x, if x is not empty.

Definition

> The simple components of x are all those simple objects obtainable by repeated selection and disclosure. If they are all empty, the result is an empty vector whose type is that of the nonnull ones; if they are all null, the result is the Null. If x is simple, the result is the ravel of x. Otherwise, the result is the catenation of the ravels of all the simple components of x.

Additional Error Report

> - A domain error is reported if two simple components of x (including empty arrays whose types are not null) are of different types, except that symbol and function may both be present.

Examples

>         _flat (É3 5;23 34 42;0;É0;;<<(<¢1 ¢2),<1 2Ò7 8)
>     0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 23 34 42 0 ¢1 ¢2 7 8
>         _flat `a,<2 2Ò`b`c`d`e
>      `a `b `c `d `e
>         (`a,<{+})½_flat(`a;+)
>     1

## Format _fmt{y;x}

Arguments and Result

> y is a character vector or scalar, and x is a simple character or numeric array or a nested array. The result is a simple character array of rank less than or equal to 2.

Definition

> The function _fmt transforms character and numeric data in x into a character table according to specification y, which consist of a series of format phrases - see the "Format Phrases" table - separated by commas. For example, the string 'i6,f8.2,f6.1' contains three phrases. Each phrase governs the appearance of a column in the result. The number of phrases need not match the number of items in x, the phrases being repeated cyclically as needed; furthermore, tab and constant specifications are in separate phrases.

> Each phrase has a type, indicated by a letter, such as the letters i and f in the above example. A tab or constant field in y does not correspond to anything in x. A tab field merely contributes to the positioning of the next part of the output, and a constant field is reproduced in the output exactly as shown.

> Within each format phrase, to the left of the letter that identifies its type, qualifiers or decorators may be inserted. A qualifier provides additional rules, such as "insert commas between triplets of digits" or "leave this field blank for zero". See the "Qualifiers" table. A decorator is a code letter immediately followed by a piece of text enclosed in angle brackets or whatnot; the text is to be attached to the representation of a number, usually to indicate its sign. See the "Decorators" table.

> When rounding is required, IEEE rules are used: see "Format". When a number cannot be formatted in the specified manner, its field is filled with asterisks. A field whose format is valid but for a different type from the data is filled with question marks. In particular, symbols in x do not cause an error message, but the field in which a symbol is to be formatted is filled with question marks.

> Normally, x is a matrix, and the application of the formatting phrases is straightforward. It can be of other ranks and of any depth, however. In that case, the columns to be formatted are obtained, conceptually, by the following process. When a nested array is encountered, it is ravelled, and its elements are successively disclosed and treated in the manner being described. When a simple array is encountered, it is transformed into a matrix if it is not already one: a scalar becomes a 1 by 1 matrix, an n-element vector becomes an n by 1 matrix, and any other array a is reshaped as ((«/¢1ÕÒa),¢1ÙÒa)Òa. This produces a series of matrices, and thus a series of columns, to which the formatting phrases are applied as stated above. Each formatted column can be viewed as a character matrix; the result has the same number of rows as the one with the most rows. Conceptually, blank rows are appended as necessary to each of these matrices to make them the same length as the result, and they are catenated side by side (,@0) to form the result.

> In the "Format Phrases" table, j is an optional repetition factor; q represents an optional qualifier and decorators; w is field width; d denotes significant digits or decimal digits; p is displacement; a, e, f, i, t, and x are literals giving phrase types.

> Format Phrases
> Phrase | Application | Description
> --- | --- | ---
> j a w | Character | Display each character in a field w positions wide. A w greater than 1 produces blanks between adjacent characters.
> jq e w.d | Exponential | Display each number in a field w positions wide, with d significant digits. Align E's and decimal points in fields that are not left justified.
> jq f w.d | Fixed point | Display in a field w positions wide, with d decimal digits, including trailing zeros. Leading zeros are shown as blanks unless the z qualifier is used.
> jq i w | Integer | Display in a field w positions wide. Leading zeros are shown as blanks unless the z qualifier is used.
> jq g<txt> | Picture Format, rounding arguments to integers | In txt, 9 and z are "special characters"; the rest are "ordinary." Round each number to an integer, after scaling if k is present. If s is present, modify txt as required. Then format each number with as many digits as there are special characters in txt, so each digit corresponds to a special character. Display a digit corresponding to a 9 unconditionally. If a digit corresponding to a z is in a sequence of leading or trailing zeros, display a blank; otherwise, display the digit. Display ordinary characters as is, with one exception, intended to exclude superfluous thousands separators but include decimal points: any ordinary character surrounded by special characters is displayed as blank if in the display a blank is next to it, unless it is the last ordinary character and is followed by at most two characters. The only valid decorators and qualifiers are m and p (but only the first character of the text of each), s, and k.
> j t p | Absolute tab | Start the next field at position p+1. If p is too small, the next field may overwrite earlier ones.
> j x p | Relative tab | Start the next field at a position displaced p positions from the end of the preceding field. If p is negative, the next field may overwrite earlier ones.
> <text> | Constant: for all | Insert text in every row of the result.

> Qualifiers
> Qualifier | Summary | Description
> --- | --- | ---
> b | blanks | Make the entire field blank when the value is zero.
> c | commas | Insert commas between successive triplets of digits in integer and (before the decimal point) fixed-point fields.
> k e | scale | Scale the result by displaying a value that is 10e times the value.
> l | justify | Left justify. The default is right justification.
> z | zeros | Display leading zeroes in integer and fixed-point fields.

> In the "Decorators" table, text may also be delimited by ¤¦, ÚØ, ¡¡, //, ÌÌ, ìì.

> Decorators
> Decorator | Summary | Description
> --- | --- | ---
> m<text> | Negative-Left | Insert text to the left of a negative value, not APL high minus. text can be empty. m and n can be used together.
> n<text> | Negative-Right | Insert text to the right of a negative value rather than use APL high minus. text can be empty. m and n can be used together.
> o<text> | Zero replacement | When the data as formatted is zero, replace the result by text. Valid for the e, f, and i phrase types.
> p<text> | Positive-Left | Insert text to the left of a positive value. p and q can be used together.
> q<text> | Positive-Right | Insert text to the right of a positive value. p and q can be used together.
> r<text> | Background | Fill the field cyclically with text where normally blanks would appear, including blanks from a b qualifier. For e, f, and i phrase types.
> s<text> | Symbol Substitution | For each pair of characters in text, the second indicates a character to replace the first. In e, f, and i phrase types, punctuation, sign, and error characters in the result can be replaced; in a g phrase type, any characters in the picture text and error characters in the result can be replaced; no other replacements can be made. For example, s<,..,> in an f phrase type produces periods where commas usually appear and commas where periods usually appear.

Examples

>          'e9.4' _fmt 200 .987
>      2.000E 2               ã Internal blank used to align decimal points and E's.
>      9.870E¢1

>          nû123456789 0 ¢123456789 123456
>          'bcm<->k-2f13.2' _fmt n
>      1,234,567.89

>     -1,234,567.89
>          1,234.56

>          'm<(> n<)> q< > b c k-2 f16.2' _fmt n
>        1,234,567.89                ã Blanks are okay in the left argument.

>       (1,234,567.89)
>            1,234.56

>          'i 6' _fmt `wrong `type
>     ??????
>     ??????

>          'g<99:99:99>' _fmt 100Â3Ù3Õsys.ts{}
>     07:19:30

>          'g<zz9>' _fmt .49 .51 99.47
>       0
>       1
>      99

>          rfndû 1.23 10.00 12345.67 332 1234.56
>          'k2 g<Your refund is: $z,zz9.99>' _fmt rfnd
>     Your refund is: $    1.23 ã k2 applied to 1.23 is 123, and the
>     Your refund is: $   10.00 ã decimal point in 1.23 is from g.
>     ************************* ã 12,345.67 is too long; if we had s<*?>
>     Your refund is: $  332.00 ã in the left arg, *...* would be ?...?.
>     Your refund is: $1,234.56 ã The comma is needed here, and it appears.

>          'k2 g<Your refund is: $z,zz9.zz>' _fmt 1.23 10.00
>     Your refund is: $    1.23
>     Your refund is: $   10.   ã The decimal point is the last ordinary
>                               ã character and it has only two characters
>                               ã after it,so it's shown even when the
>                               ã trailing zeros are dropped.

>          's<9#z$>g<$$$# units of product z9>' _fmt 73
>       73 units of product z9  ã s allows 9 and z to be included literally
>                               ã in the output.

## General Search and Replace _gsr{y;x;r;n}

Arguments and Result

> y, x, r, and n are all simple character arrays, normally vectors, except that r and n can also be null. The result is either a simple character array or an integer vector or matrix.

Definition

> If x, r, or n is not a vector, its ravel is used. There are eight cases, as determined by n and r:
> - If r is Null, then:
>   - If n is Null, then the function is the same as String Search (_ss).
>   - If n is not Null, then the function is the same as Name Search (_ns), except that n affects the definition of "namelike" as follows:
>     - if n is the empty character vector (''), then the definition is exactly the same as for _ns;
>     - if n is nonempty and 0#n is not 'þ', then n replaces '._', and '`¢' are not considered;
>     - if n is 'þ',c, then c replaces the alphabetic characters, digits, and '._', and '`¢' are not considered.

> - if r is not Null (but possibly ''), then:
>   - If n is Null, then the function is the same as String Search and Replace (_ssr).
>   - If n is not Null, then the function is the same as Name Search and Replace (_nsr), except that n affects the definition of "namelike" as follows:
>     - if n is the empty character vector (''), then the definition is exactly the same as for _nsr;
>     - if n is nonempty and 0#n is not 'þ', then n replaces '._', and '`¢' are not considered;
>     - if n is 'þ',c, then c replaces the alphabetic characters, digits, and '._', and '`¢' are not considered.

Examples

> Name delimiters are okay within target and replacement:

>          _gsr{'ÌIOû1';'ÌIO';'ÈIO';'ÌÈü'}
>     ÈIOû1

>          _gsr{'ÌÌIOû1,ÌIOû2,BÌIOû3';'ÌIO';'ÈIO';'ÌÈü'}
>     ÌÌIOû1,ÈIOû2,BÌIOû3

>          _gsr{'ÌÌIOû1,ÌIOû2,BÌIOû3';'ÌIO';'ÈIO';'þÌÈü'}
>     ÌÌIOû1,ÈIOû2,BÈIOû3

>          _gsr{'Mississippi is';'is';'IS';''}
>     Mississippi IS

>          _gsr{'Mississippi is';'is';'IS';}
>     MISsISsippi IS

## Get Attribute _get{y;x}

Argument and Result

> The arguments x and y are described in "The Name Argument". The result is an array.

Definition

> If _set{y;(x;z)} (Set Attribute) has been executed previously, then the result of this function is z, the value for attribute x on variable y. Otherwise, the result is Null, including the case when y does not exist.

## Get Callback _gcb{y}

Argument and Result

> The argument y is described in "The Name Argument". The result is a two-element nested array.

Definition

> If _scb{y;x} (Set Callback) has been executed previously, then the value of _gcb{y} is the value of x in the last such setting: function scalar, static data. Although the name displayed for the callback function may now have a new reference, î0Ø_gcb{y} gives the definition of the callback function. Otherwise the value is Null.

## Get Client Data _gcd{y}

Argument and Result

> The argument y is described in "The Name Argument". The result is an array.

Definition

> This function is like _get (Get Attribute), but for an implicit, unnamed attribute. It gets the value that was set by the last execution of _scd{y} (Set Client Data); if none was set, it returns the Null. It has been superseded by Get Attribute and is retained only for compatibility.

## Get Format Symbols _gfmtsym{}

Result

> The result is a vector of symbols.

Definition

> This function lists the symbols acceptable as values for the out attribute. See the "out Attribute Format Samples" table.

## Get Preset Callback _gpcb{y}

Argument and Result

> The argument y is described in "The Name Argument". The result is a two-element nested array.

Definition

> If _spcb{y;x} (Set Preset Callback) has been executed previously, then the value of _gpcb{y} is the value of x in the last such setting: function scalar, static data. Although the name displayed for the preset callback function may now have a new reference, you can obtain the definition of the preset callback function by entering î0Ø_gpcb{y}.

> Otherwise the value is Null.

## Get System Variable _gsv{x}

Argument

> The argument x is a symbol scalar or a quoted string naming a system variable whose value the user is allowed to access. The result is the value of that system variable.

Definition

> The value is the current value of the system variable named in x. A domain error is reported if x does not name a system variable or access to the system variable named in x is forbidden, as it is for `rl. See "System Variables" for descriptions of the system variables and their values and interdictions.

Additional Error Report

> - A domain error is reported if x does not name a system variable whose value is accessible.

## Hash Table Statistics _hashstat{x}

Argument and Result

> The argument is Null or a symbol naming a context. The result is an integer vector.

Definition

> The result gives the number of entries in each bucket of a hash table. If the argument is Null, the statistics are for the symbol table and the result length is 1024. If the argument names a context, the statistics are for the hash table for that context and the result length is 512. The function +/ applied to the result indicates the number of names that have ever been defined, while Ó/ gives a rough indication of collisions and hence possibly reduced execution speed (although for this purpose the whole vector should be examined for clumping).

## Index of _index_of{y;x}

Arguments and Result

> y and x must be nested vectors of the same length. For each of them, its elements must all be nested vectors of the same length, or all be enclosed scalars. For y, a scalar is treated as a one-element vector. The result is a simple integer vector or scalar whose shape is the same as an element of x.

Definition

> Call y's contained vectors y1...yn and x's contained vectors x1...xn. The result r is an integer vector of length Òx1; r[i] is the least j for which xk[i] is equal to yk[j] for all k; if there is no such j, then r[i] is Òy1. This function is a high performance version of the expression (ô>y É¡y)Éô>y É¡x.

> Regarding the arguments as matrices whose columns are the contained vectors, so that the matrices have the same number of columns, _index_of yields a vector that gives, for each row of the right argument, the index of the first row of the left argument that it matches; for any row of the right argument that does not have a matching row in the left argument, the corresponding element of the result is the number of rows in the left argument, i.e., the common length of its contained vectors.

Example

> Consider a tiny table with three fields: styles, colors, and prices. The style and color fields can be used as key fields with _index_of to find row indices of the table, and these can be used with Pick to give prices:

       Inventoryû(("Oxford";"Oxford";"Loafer";"Loafer");
    *             ("Brown"; "Tan";   "Black"; "Brown" );
    *             (128.98;  175.98;  112.50;  112.50))
       (Inventory[0 1]_index_of(<"Oxford";<"Tan"))Ø2ØInventory
     175.98

Additional Error Reports

> - A length error is reported if the arguments are not the same length.
> - A domain error is reported if the contained vectors of an argument are not of the same length.

## Is a Slotfiller _issf{x}

Argument and Result

> x is any array. The result is a scalar boolean integer.

Definition

> If x is a slotfiller, the result is 1. Otherwise the result is 0, e.g., if there are repetitions among the items of 0Øx.

## Items of a Mapped File _items{y;x}

Arguments and Result

> The argument y is a one-element numeric array whose element is a restricted whole number, while the argument x is a symbol or character scalar or character vector. The result is a scalar integer.

Definition

> The argument x holds the name of a mapped file (see "Mapped Files"). A mapped file can be processed within A+ as if it were an ordinary array. In particular, it makes sense to speak of the items of a mapped file. If y is -1, the result is the number of currently allocated items. If y is nonnegative and less than the current number of items, then the effect is to truncate the file. Otherwise, if y is nonnegative the effect of this function is to allocate space (if necessary) on the end of the file so that the file can hold y items. See "Work Area" (_wa) regarding units of storage allocation. The result is the current number of items before the new allocation. See "Examples", and note that the "Operation would block" message and the delay caused by trying to avoid that message can occur for _items.

> When a file is written out as a mapped file, the file is made only large enough to hold the actual data.

> After a file length is changed by _items, any variables that were associated with it (by Map or Map In) must be remapped (by a new application of Map or Map In), because _items has rewritten the file.

## Load _load{x}

Argument and Result

> The argument x is a symbol scalar or a character vector. The result is a two-element nested array.

Definition

> The expression _load{x} provides the same function as $load x (Load command). The argument x names the A+ script file to be loaded. The result is (`ok;file) if the file is found and can be read, where file is a character vector giving the fully qualified name of the file that is loaded, i.e., path/filename. After a file is loaded, the current context and the current directory are the same as they were when the Load function was invoked: each is automatically restored if it was changed during execution of the lines of the file.

> If the file is not found the result has the form (`error;"error message"). Note that a result (`ok;file) does not mean that the file was loaded without error, just that it was found and can be read.

Example

>          _load 's'
>     < `ok
>     < /usr/local/lib/s.+

## Load and Remove _loadrm{`delete;x}

Argument and Result

> The right argument x is a symbol scalar or a character vector. The result is a two-element nested array.

Definition

> _loadrm{`delete;x} provides the same function as $loadrm x (Load and Remove command). The argument x holds the name of the file to be loaded. The file is loaded and then deleted (this is a special function for the Emacs environment). The result is the same as that of _load. The left argument must be `delete or 'delete' or an error message is issued.

## Locals _locals{x}

Argument and Result

> x is a symbol, function expression, or function scalar representing a defined or external function; it cannot be a primitive or derived function. The result is a three-element nested array.

Definition

> The first element of the result is the name of the function, as a symbol. If x represents a defined function, the second element is a vector of the names of the arguments to the function and the third element lists its local variables. If x represents an external function, the second element is an integer vector of its argument types (see table in "Calling C Subroutines from A+"), and the third element is null.

## Name _name{x}

Argument and Result

> The argument x is a function scalar. The result is a scalar symbol.

Definition

> x is of the form <{fn}, where fn is a defined, primitive, or system function. For a defined function, the only case that really makes sense, the result holds the fully qualified name of fn, i.e., the name of the current context, which will be empty for the root context, followed by a dot as separator, followed by fn. If fn is a system or primitive function, the result is just fn preceded by a backquote.

> The expression _name<{&}, either inside the definition of a function fn or entered when a defined function fn is suspended, will produce the fully qualified name of fn.

> If in context cx you enter, literally, _name<{f}, you will get either the uninteresting result `cx.f or a value error: the only unqualified name you can use in the argument is one defined in the current context. A more useful case is when you have an expression that yields a function that may or may not be in the current context, an expression that uses _gcb or of or the like.

Additional Error Report

> - A nonce error report is issued if x is a symbol.

Example

>          $cx sys
>          _name <{import}
>      `sys.import

## Name Class _nc{y;x}

Arguments and Result

> Both arguments and the result are symbol scalars; y can also be Null.

Definition

> If the symbol x holds an unqualified user name, i.e., a name without an explicit reference to its context, and if the symbol y holds a context name, the result is the symbol form of the name class of the user name x, in the context y (see the "Name Classes" table). If x holds a fully qualified name of the form cxt.nm, the result refers to nm in the context cxt, and the value of y is ignored.

> The root context is denoted by the empty symbol (`). The current context is denoted by Null: if _nc is referenced in the form _nc{;x}, the current context is assumed.

> Name Classes
> Name Class | Description
> --- | ---
> `vars | User variables
> `fns | Defined functions
> `xfs | External functions
> `globs | Global objects
> `deps | Dependencies
> `ops | Defined operators
> `null | Not in use, not a valid name, or not one of the above

## Name List _nl{y;x}

Arguments and Result

> Both y and x are symbols, except that x can be Ï and y can be Null. The result is a vector of symbols.

Definition

> The result is a vector of symbols holding the names of objects of class x (see the "Name Classes" table) in the context identified by y. The empty symbol (`) denotes the root context, and Null denotes the current context. Dependencies are listed only when they have saved values, which need not be valid. See the table "Name List Expressions vs. The Kind of Objects in the Result" for examples of these and other uses of Name List. For the arguments `apl `ascii, and `uni, the order of the symbols is consistent between them (the symbols in the same positions representing the same primitive) within the same version of A+, but the order may change from version to version, and new functions may cause insertion of symbols; any such changes will not be considered upwardly incompatible.

> Name List Expressions vs. The Kind of Objects in the Result
> Expression (see Note below) | Kind of Object Named in the Result
> --- | ---
> _nl{`ctx;`vars} | Variables in the context `ctx
> _nl{`ctx;`fns} | Functions in the context `ctx
> _nl{`ctx;`deps} | Dependencies in the context `ctx
> _nl{`ctx;`ops} | Operators in the context `ctx
> _nl{`ctx;`globs} | Global objects in the context `ctx
> _nl{`ctx;`xfs} | External functions in the context `ctx
> _nl{`;`cxs} | Contexts
> _nl{`;`svs} | System variables
> _nl{`;`sfs} | System functions
> _nl{`;`cmds} | System commands
> _nl{`;`apl} | All keywords and primitive symbols in APL mode
> _nl{`;`ascii} | All keywords and primitive symbols in ASCII mode
> _nl{`;`uni} | All keywords and primitive symbols in UNI mode
> _nl{`;`circle} or _nl{;Ï} | List of symbolic left arguments for Circle function. (Although ` _nl `circle works fine, the parser is confused by ` _nl Ï. Left arg can be null, with correct result in any current context.)
> _nl{`;`errors} | Names (as symbols) of errors defined in A+
> _nl{`;`nl} | Valid right arguments to _nl
> _nl{`;`wa} | Valid symbol arguments to _wa

> Note:

> - Where the left argument is shown as `ctx, it can also be Null (absent), indicating the current context.
> - Where the left argument is shown as ` (the root context), it can also be Null (absent), indicating the current context.

## Name Search _ns{y;x}

Arguments and Result

> Both y and x are character arrays, normally vectors. The result is an integer vector or matrix.

Definition

> If x is not a vector, its ravel is used. If y is a vector, the result is a vector of indices of nonoverlapping namelike occurrences of the vector x in y. Each index marks the beginning of an occurrence in y. An empty result signifies that there are no occurrences. A namelike occurrence is one that satisfies the following restrictions:

> - not part of a comment;
> - not in quotes;
> - not immediately preceded by a backquote or a high minus (`¢) or preceded or followed by an alphabetic character (in upper or lower case), a digit, or a dot or an underscore (._).
> If y is a matrix or higher-rank array, then an occurrence is required to be entirely on one line; occurrences spanning rows are not accepted. (An unbalanced quotation mark, perhaps intended as an apostrophe, will block name recognition in later lines, however.) The result is an r by n matrix, where r is the rank of y and n is the number of occurrences found. A column of the result gives the indices of the corresponding occurrence, with the highest-order index at the top and the column index at the bottom. Thus 0# applied to the result gives a list of the items in which occurrences were found.

Examples

>           _ns{'This is ''is''';'is'}
>      5
>          4 3Ò'abc abc  abc'
>     abc
>      ab
>     c
>     abc
>          _ns{4 3Ò'abc abc  abc';'abc'}
>      0 3
>      0 0

## Name Search and Replace _nsr{y;x;r}

Arguments and Result

> y, x, r, and the result are all character arrays, normally vectors.

Definition

> If x or r is not a vector, its ravel is used. Occurrences of x are sought in exactly the same way as they are in Name Search, _ns{y;x}, but in two different objects, depending upon y, x, and r:
> - If y is a vector or the ravels of x and r are the same length, then the result is y with r in place of every occurrence of x found in y itself.

> - Otherwise, the result is the ravel of y with r in place of every occurrence of x found in the ravel of y; if no occurrences were found, the result is simply the ravel of y.
> See also the examples in "String Search and Replace".

Example

>          _nsr{'This is ''is''';'is';'are'}
>     This are 'is'

## NaN Find _nanfind{x}

Argument and Result

> The argument is any array. The result is an integer vector.

Definition

> If the type of x is floating point (so x is simple), then the result is a vector consisting of the indices of those elements of the ravel of x that are NaN's. Otherwise the result is É0.

> NaN's are used in some systems to represent indeterminate numbers. They are like Infs, but more general. This function can be used to locate NaN's occurring in loaded files or resulting from dynamically loaded code. The nan subcommand of the $dbg command can be used to screen files being beamed in for NaN's. (NaN's are not generated by A+ primitive functions.)

## Permissive Indexing _index{i;x;d}

Arguments and Result

> i is a simple array of restricted whole numbers, x is any array, and d conforms to the items of x, i.e., its general type is the same as theirs, and either it is a scalar or its shape is the same as theirs.

Definition

> This function is like i#x, with three exceptions: (1) Only a simple i is allowed, so only items of x are chosen. (2) If i is Null, the result is no items of x, not all items of x. (3) If an element of i is out of range, no index error is reported; instead, d is placed in the corresponding position in the result, replicated if necessary so that it matches the items of x.

Examples

>          _index{2 19 14 1;
>             ('Mar 06';'Jul 18';'May 15';'Nov 26');<'n.a.'}
>     < May 15
>     < n.a.
>     < n.a.
>     < Jul 18

>          _index{10 11;É11 4;¢1}
>      40 41 42 43
>      ¢1 ¢1 ¢1 ¢1

## Remove Dependency Definition _undef{name}

Argument and Result

> The argument name is described in "The Name Argument". The result is a boolean integer.

Definition

> The function removes the dependency definition for name, if any, and leaves everything else, such as value and callback function, unchanged. After this function is executed, name is an ordinary, not a dependent, variable. It may not have a value, since Remove Dependency Definition does not cause an evaluation. You may sometimes want to force an evaluation before invoking this function. The result is 0 if a definition was removed, and 1 otherwise - name does not name a dependency. Cf. "Remove Dependency Definition" ($undef).

## Scalar Comma Fix Input _scfi{s}

Argument and Result

> The argument s is a character array, normally a vector, and the result is a numeric scalar.

Definition

> This function is like Comma Fix Input (_cfi), except that: it handles only a single number (so there must be no internal blanks); it has a simple scalar result; it has no boolean part to its result, an invalidity being reported as an error instead; and it treats commas properly, requiring that they be internal to the integer portion of the number, properly placed every three digits leftward from the decimal point (or right end, if there is no decimal point), and that there be either no commas or the full set. I.e., if s is a valid argument for _scfi, _scfi{s} is exactly equivalent to ''Ò1Ø_cfi{s;1}.

Additional Error Report

> - A domain error is reported if the first item of _cfi{s;1} would be zero.

## Scalar Fix Input _sfi{s}

Argument and Result

> The argument s is a character array, normally a vector, and the result is a numeric scalar.

Definition

> This function is like Fix Input (_fi), except that it handles only a single number, has a scalar result, and has no boolean part to its result, an invalidity being reported as an error instead. I.e., if s is a valid argument, _sfi{s} is exactly equivalent to ''Ò1Ø_fi{s;1}.

Additional Error Report

> - A domain error is reported if the first item of _fi{s;1} would be zero.

## Screen Format _sfmt{f;d}

Arguments and Result

> The left argument is a format specification, either one shown in the "out Attribute Format Samples" table, or one acceptable as a left argument for _fmt (Format), or î (Format). The right argument is a simple numeric scalar. The result is a character vector.

Definition

> If the left argument is a symbol, then it and the result are as described in the "out Attribute Format Samples" table. If the left argument is character, then it and the result are as described for _fmt (Format). Otherwise, the left argument is numeric and the result is as described for î (Format).

> Formats containing y2 are restricted to the years 1950 through 2049, errors in dates return 0's except that an erroneous `y2 is set to "**", and the length of the result returned for a bad date is the same as for a good date.

> Warning! If the right argument is numeric but nonscalar, only the first element is used.

## Set Attribute _set{y;x}

Argument and Result

> The argument x is a nested vector (w;z), where z is any array. Both w and the argument y are described in "The Name Argument". The result is a scalar integer.

Definition

> Sets the value for attribute w on global variable y to the value z. If z is Null the attribute is removed. The result is 1 if the value was not previously set or the attribute was removed or y does not exist, and 0 otherwise. The attribute w, which is commonly a name, can be whatever you want; it simply allows you to associate data with y in an easily retrievable way.

## Set Callback _scb{y;x}

Arguments and Result

> The argument y is described in "The Name Argument". The argument x is a two-element nested array. The result is Null.

Definition

> The argument x is a pair of the form (f;s), where s is any array and f is a function expression. Thus the first element of x is a function scalar and not the name of a function, so this assignment is unaffected by any later changes to the meaning of the name of the function f. Executing _scb{y;x} causes the "callback" function f to be called each time the value of the global variable (or, indeed, function) named in y is modified through certain assignments, after the modification has been made. The array s is known as the static data, and is passed as a parameter to f on every call that results from an assignment to the global variable named in y.

> If s is omitted the static data is Null. If f is omitted then any callback previously established for the global variable named in y is removed.

> The general form of the syntax of f is
> f{s;d;i;p;c;v} where

> > s is the static data
> > d is the new value
> > i is an index, nested if for y and simple if for ,y
> > p is a path
> > c is a symbol naming the context in which y is defined, and
> > v is `y

> such that

> (i#pØc%v)ûd ã if i is nested
> (i#,pØc%v)ûd ã if i is simple
> or
> (pØc%v)[,]ûd ã if i is out of range for c%v before this assignment

> describes the change that caused f to be called.

> A callback function can have any number of arguments from to zero to six, but the meaning of the arguments is always as above, reading from the left. For example, if it has three arguments then the first is static data, the second is new data, and the third is an index. Any explicit result of a callback function is ignored by A+.

> Dependencies are global variables, and callbacks can be set on them. However, such a callback function is called only when the dependent variable is explicitly specified using ordinary or selective assignment, and in the latter case only as described above. A callback does not occur when a dependency is marked for evaluation, or when an evaluation occurs (although a preset callback is called in this latter case). Furthermore, during a callback on a dependency, the dependency's value is not marked invalid by any change the function makes in a variable on which it depends. (Cf. "Set Preset Callback".)

> Only one callback can be set on a global variable. For example, if _scb{`a;(fn;)} is executed, and then _scb{`a;(gn;)}, the first callback function fn is removed when the second one gn is established. Since it is the callback function itself, and not a name, that is given to _scb, if you redefine the function and want the new definition to apply to the callback, you must call _scb again to set it.

> For examples and more detail, see "Callback Functions".

## Set Client Data _scd{y;x}

Arguments and Result

> The argument x is any array. The argument y is described in "The Name Argument". The result is an array.

Definition

> This function is like _set (Set Attribute), except that there is no explicit, named attribute and the result is the previous client data, i.e., what the result of _gcd{y}, Get Client Data, would be if it were executed immediately before _scd{y}. This function has been superseded by Set Attribute and is retained only for compatibility.

## Set Preset Callback _spcb{y;x}

Arguments and Result

> The argument y is described in "The Name Argument". The argument x is a two-element nested array, as described for Set Callback. The result is Null.

Definition

> The differences between callback functions established by _spcb and _scb are:
> - preset callback functions on dependencies are called when either a dependent variable is assigned a value or a dependency is evaluated (after the evaluation of the dependency definition is completed), whereas callback functions are called only when the dependent variable is assigned a value;

> - _spcb{y;x} causes the callback function specified in x to be called just before the value of the global variable (or, indeed, function) named in y is changed, but _scb is called just after;

> - preset callback functions are used to validate new values for global variables and they therefore return meaningful results (namely, the validated data), whereas callback functions do not;

> - for the Append form of Selective Assignment, the indices i are not valid for _spcb, since the appending has not yet been done, but they are valid for _scb.
> Since preset callbacks are used for validating new values of global variables, the following rules should be followed in their definitions:

> - if a new value is valid, set the result of the preset callback function to that value;
> - if a new value is invalid, signal an error (see "Signal"); the value of the global variable will remain unchanged.
> For examples and more detail, see "Callback Functions".

## Set System Variable _ssv{y;x}

Arguments and Result

> The argument y is a symbol scalar or a quoted string. The result is always Null.

Definition

> This function sets the value of the system variable named in y to the value of the right argument x. A domain error is reported or a correction made (e.g., 100Íx for `pp) if the right argument is not a valid value of the system variable named in y or if that system variable is not allowed to be set. See "System Variables" for descriptions of the various system variables and their values and interdictions.

Additional Error Report

> - A domain error is reported if y does not name a system variable that can be set or x is an impermissible setting for y. Although $Df 2 is a no-op, _ssv{`Df;2} is a domain error.

## Stack Information _doErrorStack{}

Returns the stack information for the last error that occurred under a Protected Execute while `doErrorStack was enabled (1).

This facility should enable developers to mail error information without having to exit the application.

## String Search _ss{y;x}

Arguments and Result

> Both y and x are character arrays, normally vectors. The result is an integer vector or matrix.

Definition

> If x is not a vector, its ravel is used. If y is a vector, the result is a vector of indices of nonoverlapping occurrences of x in y. Each index marks the beginning of an occurrence.

> If y is a matrix or higher-rank array, then an occurrence is required to be entirely on one line; occurrences spanning rows are not accepted. The result is an r by n matrix, where r is the rank of y and n is the number of occurrences found. A column of the result gives the indices of the corresponding occurrence, with the highest-order index at the top and the column index at the bottom. Applying 0# to the result gives the indices of the items in which occurrences were found. See also the examples for Name Search.

Examples

>          _ss{'Mississippi';'is'}
>      1 4
>          _ss{'Mississippi';'issi'}
>      1     ã The instances must be nonoverlapping.

## String Search and Replace _ssr{y;x;r}

Arguments and Result

> y, x, r and the result are all character arrays, normally vectors.

Definition

> If x or r is not a vector, its ravel is used. Occurrences of x are sought in exactly the same way as they are in String Search, _ss{y;x}, but in two different objects, depending upon y, x, and r:
> - If y is a vector or the ravels of x and r are the same length, then the result is y with r in place of every occurrence of x found in y itself.

> - Otherwise, the result is the ravel of y with r in place of every occurrence of x found in the ravel of y; if no occurrences were found, the result is simply the ravel of y.

Examples

>          _ssr{'Mississippi';'is';'IS'}
>     MISsISsippi
>          3 6Ò'abc abc defgh abcd'
>     abc ab
>     c defg
>     h abcd
>          _ssr{3 6Ò'abc abc defgh abcd';'abc';'xyz'}
>     xyz ab
>     c defg
>     h xyzd
>          _ssr{3 6Ò'abc abc defgh abcd';'abc';'wxyz'}
>     wxyz wxyz defgh wxyzd

## Valence _valence{x}

Argument and Result

> The argument x is either the name of a defined or external function, as described in "The Name Argument", or a function expression or scalar holding a defined, external, or system function. The result is an integer scalar.

Definition

> The result is the number of arguments taken by the function specified in the argument x.

Additional Error Reports

> - A nonce error is reported if x is a function scalar that is a primitive function;
> - a domain error is reported if x is a symbol naming a system function, but not if x is a function scalar that is a system function.

## Work Area _wa{x}

Argument and Result

> The argument x is a symbol or integer scalar.

Definition

> The expression _wa n, for n greater than or equal to 1, increases the workspace size by approximately n megabytes; see the first table entry regarding IBM machines. Other values of the argument x will produce information about the amount of available storage in the workspace, as well as the amount and distribution of storage in use, and in one case cause the areas of unused storage to be coalesced. See the "_wa Arguments and Results" table.

> Memory allocation for A+ objects is based on an increasing set of integers called fragment sizes. The storage area for a particular object will be a fragment of sufficiently large fragment size to hold the object, but perhaps with extra, unused room. (It always uses a fragment of smallest possible size. Fragments can be split off larger ones as needed.) As noted in "_wa Arguments and Results", _wa can be employed to find out how many fragments of each size are currently in use.

> _wa Arguments and Results
> Argument | Effect and Result
> --- | ---
> n, for n¦1 | The effect is to increase the workspace size, `size, by n megabytes (a megabyte is 220 bytes). The effect of giving a noninteger argument is undefined. The result is 0 if successful. On IBM machines, the workspace size cannot be increased when a mapped file exists for an A+ process, because A+ requires that the entire workspace be contiguous and AIX requires that all space be taken from one end of the address space; thus, the mapped file blocks enlargement of the workspace.
> `fragsizes | The result is a vector of integers of fragment sizes, in words. This vector is fixed for every A+ session, but may vary with the release number and the machine on which you are running.
> `fragcounts or 0 | The result is a vector of integers giving the number of free, or available, storage fragments of each fragment size. (Note that these numbers are computed after the argument to _wa is allocated.)
> `coalesce or ¢1 | The effect is to combine contiguous free fragments into larger fragments. The result is a vector of the new fragment counts. If there is no writable /var/atmp (see the -m invocation flag, below) nothing is done and the result is all zeros.
> `size | The result is the workspace size, i.e., its current maximum permitted size, in bytes. It can be increased by _wa n, or by a naked left arrow (û, indicating resumption) with a pending wsfull error.
> `avail | The result is the amount of available storage in the workspace. (Note that the amount is computed after the argument to _wa is allocated.) It is the difference between the workspace size, `size, and the space actually being used, and is almost equal to the result of the command $wa. Usually, some of `avail is in `atmp and some is not.
> `atmp | The result is the current total size of the files used to hold the workspace. It includes both space that is in use and space that is available. See `avail. $df /var/atmp tells more about available atmp.
> `info | The result is a combination of the above information in the following arrangement: (`size `atmp `avail; `fragcounts; `fragsizes).

> A+ data objects (including function arrays but not functions) are stored as 56-byte headers and bodies of varying size. If the number of elements of an object is n, then its body will take, in bytes, depending on its type:
> `char n+1
> `int 4«nÓ1
> `float 8«nÓ1
> `sym 4«nÓ1
> `box 4«nÓ1 plus the storage for each of its elements
> `func 4«nÓ1
> `null usually no space, but sometimes the same formula as `box.

> A+ looks for its atmp space in /var/atmp/*. If several A+ processes are running on the same machine, they will compete for the same atmp space. The atmp space is used as both workspace area and mapped file area, so if large mapped files are used it may even be necessary to reduce the workspace size to get an application to work. Usually, it is best to keep the workspace about twice as large as the amount of memory you expect to use; 256Meg is the recommended safe limit, beyond which you may run out of address space.

> Modifying Memory Mapping Characteristics

> The memory mapping characteristics of atmp can be modified by means of the invocation flag -m with the value ws_atmp_shared, ws_atmp_noreserve, ws_atmp_private, ws_atmp_heap, or ws_malloc. The same settings can be given to APLUS_ATMP_MODEL, an environment variable, with the same effect.

> ws_atmp_shared, ws_atmp_noreserve, and ws_atmp_private control the flags used for mmap and atmp (see the man page for mmap); ws_atmp_noreserve is implemented as MAP_AUTORESRV on sgi. ws_atmp_heap will put atmp in memory. ws_malloc will just use malloc and free as needed. If there is no /var/atmp then the default will be ws_malloc. When /var/atmp does exist, the default is ws_atmp_shared except on UltraSparc and all Solaris machines, which have a default of ws_atmp_noreserve. Alternatively and temporarily, the memory mapping characteristics of atmp can be modified by setting the environment variable APLUS_ATMP. This variable is intended for use by system administrators to configure new architectures. The possible settings for APLUS_ATMP are: MAP_PRIVATE, MAP_NORESERVE, and FROM_HEAP.

> The Heap

> There is another area of storage in A+, aside from atmp space, namely, the heap. The heap is used for A+ internal memory needs, either temporary or permanent, such as in creating contexts or global names, parsing nested arrays, and buffering outgoing messages in adap. Subsequent uses of a symbol or name within a process do not use more memory, because expunging a name does not free the heap space used for it.

> A long-running A+ process can eventually use up its heap, although the heap is pretty large and A+'s demands on it are fairly small. A brealloc() error can then occur. The obvious way of controlling this potential problem is to not use a tremendous number of names. The heap size can be changed at A+ invocation by using the -h flag; caution: do not use this flag unless it is specifically needed to solve a memory-related problem. The size can be measured using pmon, remotely, from an XTerm, but not from within an A+ process, since pmon is interactive, so $pmon cannot be used.

> Another way to monitor heap space use is to run in an XTerm, while A+ is running,
> while [ true ]; do pstat -s; sleep 1; done

> Handling of Symbols

> Memory allocation and hashing algorithms are intended to provide high performance even for applications using 10,000 or more symbols. Symbols are kept in the atmp area rather than in the heap, preventing the bus errors that could occur when an application used hundreds of thousands of symbols, exhausting the heap. Such an application may need a relatively large _wa allocation.

> The address space for an A+ process is fixed at two gigabytes. Four things use address space:

> - the actual code of the A+ process, and dynamically loaded routines;
> - dynamic memory (heap space);
> - atmp space;
> - mapped files.

> See also "Memory Allocation - What to Do and What Not to Do" and "Memory Allocation in A+ - a Closer Look" in "Calling C Subroutines from A+".