**Synopsis**-
Tests if all elements of an array are non-zero

**Usage**-
`Char_Type all (Array_Type a [,Int_Type dim])`

**Description**-
The

`all`

function examines the elements of a numeric array and returns 1 if all elements are non-zero, otherwise it returns 0. If a second argument is given, then it specifies the dimension of the array over which the function is to be applied. In this case, the result will be an array with the same shape as the input array minus the specified dimension. **Example**-
Consider the 2-d array

generated by1 2 3 4 5 6 7 8 9 10

Thena = _reshape ([1:10], [2, 5]);

`all(a)`

will return 1, and`all(a>3, 0)`

will return a 1-d array

Similarly,[0, 0, 0, 1, 1]

`all(a>3, 1)`

will return the 1-d array[0,1]

**See Also**

**Synopsis**-
Test if any element of an array is non-zero

**Usage**-
`Char_Type any (Array_Type a [,Int_Type dim])`

**Description**-
The

`any`

function examines the elements of a numeric array and returns 1 if any element is both non-zero and not a NaN, otherwise it returns 0. If a second argument is given, then it specifies the dimension of the array to be tested. **Example**-
Consider the 2-d array

generated by1 2 3 4 5 6 7 8 9 10

Thena = _reshape ([1:10], [2, 5]);

`any(a==3)`

will return 1, and`any(a==3, 0)`

will return a 1-d array with elements:0 0 1 0 0

**See Also**

**Synopsis**-
Returns information about an array

**Usage**-
`(Array_Type, Integer_Type, DataType_Type) array_info (Array_Type a)`

**Description**-
The

`array_info`

function returns information about the array`a`

. It returns three values: an 1-d integer array specifying the size of each dimension of`a`

, the number of dimensions of`a`

, and the data type of`a`

. **Example**-
The

`array_info`

function may be used to find the number of rows of an array:define num_rows (a) { variable dims, num_dims, data_type; (dims, num_dims, data_type) = array_info (a); return dims [0]; }

**See Also**

**Synopsis**-
Apply a function to each element of an array

**Usage**-
`Array_Type array_map (type, func, args...)`

**Usage**-
`(Array_Type, ...) array_map (type, ..., func, args...)`

DataType_Type type, ...; Ref_Type func;

**Description**-
The

`array_map`

function may be used to apply a function to each element of an array and returns the resulting values as an array of the specified type. The`type`

parameter indicates what kind of array should be returned and generally corresponds to the return type of the function. If the function returns multiple values, then the type of each return value must be given. The first array-valued argument is used to determine the dimensions of the resulting array(s). If any subsequent arguments correspond to an array of the same size, then those array elements will be passed in parallel with the elements of the first array argument.To use

`array_map`

with functions that return no value, either omit the`type`

argument, or explicitly indicate that it returns no value using the`Void_Type`

type. **Example**-
The first example illustrates how to apply the

`strlen`

function to an array of strings.

This is equivalent to:S = ["", "Train", "Subway", "Car"]; L = array_map (Integer_Type, &strlen, S);

S = ["", "Train", "Subway", "Car"]; L = Integer_Type [length (S)]; for (i = 0; i < length (S); i++) L[i] = strlen (S[i]);

Now consider an example involving the

`strcat`

function:files = ["slang", "slstring", "slarray"]; exts = ".c"; cfiles = array_map (String_Type, &strcat, files, exts); % ==> cfiles = ["slang.c", "slstring.c", "slarray.c"]; exts = [".a",".b",".c"]; xfiles = array_map (String_Type, &strcat, files, exts); % ==> xfiles = ["slang.a", "slstring.b", "slarray.c"];

Here is an example of its application to a function that returns 3 values. Suppose

`A`

is an array of arrays whose types and sizes are arbitrary, and we wish to find the indices of`A`

that contain arrays of type`String_Type`

. For this purpose, the`array_info`

function will be used:(dims, ndims, types) = array_map (Array_Type, Int_Type, DataType_Type, &array_info, A); i = where (types == String_Type);

The

`message`

function prints a string and returns no value. This example shows how it may be used to print an array of strings:a = ["Line 1", "Line 2", "Line 3"]; array_map (&message, a); % Form 1 array_map (Void_Type, &message, a); % Form 2

**Notes**-
Many mathematical functions already work transparently on arrays. For example, the following two statements produce identical results:

B = sin (A); B = array_map (Double_Type, &sin, A);

**Notes**-
A number of the string functions have been vectorized, including the

`strlen`

function. This means that there is no need to use the`array_map`

function with the`strlen`

function. **See Also**

**Synopsis**-
Reverse the elements of an array

**Usage**-
`array_reverse (Array_Type a [,Int_Type i0, Int_Type i1] [,Int_Type dim])`

**Description**-
In its simplest form, the

`array_reverse`

function reverses the elements of an array. If passed 2 or 4 arguments,`array_reverse`

reverses the elements of the specified dimension of a multi-dimensional array. If passed 3 or 4 arguments, the parameters`i0`

and`i1`

specify a range of elements to reverse. **Example**-
If

`a`

is a one dimensional array, then

are equivalent to one another. However, the form usingarray_reverse (a, i, j); a[[i:j]] = a[[j:i:-1]];

`array_reverse`

is about 10 times faster than the version that uses explicit array indexing. **See Also**

**Synopsis**-
Get the shape or dimensions of an array

**Usage**-
`dims = array_shape (Array_Type a)`

**Description**-
This function returns an array representing the dimensionality or shape of a specified array. The

`array_info`

function also returns this information but for many purposes the`array_shape`

function is more convenient. **See Also**

**Synopsis**-
Sort an array or opaque object

**Usage**-
`Array_Type array_sort (obj [, &func [, n]])`

**Description**-
The

`array_sort`

function may be used to sort an object and returns an integer index array that represents the result of the sort as a permutation.If a single parameter is passed, that parameter must be an array, which will be sorted into ascending order using a built-in type-specific comparison function.

If two parameters are passed (

`obj`

and`func`

), then the first parameter must be the array to be sorted, and the second is a reference to the comparison function. In this case, the comparison function represented by`func`

must take two arguments representing two array elements to be compared, and must return an integer that represents the result of the comparison. The return value must be less than zero if the first parameter is less than the second, zero if they are equal, and a value greater than zero if the first is greater than the second.If three parameters are passed, then the first argument will be regarded as an opaque object by the sorting algorithm. For this reason, the number of elements represented by the object must also be passed to

`array_sort`

function as the third function argument. The second function argument must be a reference to comparison function. In this case, the comparison function will be passed three values: the opaque object, the (0-based) index of the first element to be compared, and the (0-based) index of the second element. The return value must be less than zero if the value of the element at the first index considered to be less than the value of the element at the second index, zero if the values are equal, and a value greater than zero if the first value is greater than the second.`array_sort`

sorts the array`a`

into ascending order and returns an integer array that represents the result of the sort. If the optional second parameter`f`

is present, the function specified by`f`

will be used to compare elements of`a`

; otherwise, a built-in sorting function will be used.The integer array returned by this function is simply an index array that indicates the order of the sorted object. The input object

`obj`

is not changed. **Qualifiers**-
By default, elements are sorted in ascending order. The

`dir`

qualifier may be used to specify the sort direction. Specifically if`dir>=0`

, the sort will be an ascending one, otherwise it will be descending.The

`method`

qualifier may be used to select between the available sorting algorithms. There are currently two algorithms supported: merge-sort and quick-sort. Using`method="msort"`

will cause the merge-sort algorithm to be used. The quick-sort algorithm may be selected using`method="qsort"`

. **Example**-
An array of strings may be sorted using the

`strcmp`

function since it fits the specification for the sorting function described above:

Alternatively, one may useA = ["gamma", "alpha", "beta"]; I = array_sort (A, &strcmp);

to use the built-in comparison function.variable I = array_sort (A);

After the

`array_sort`

has executed, the variable`I`

will have the values`[2, 0, 1]`

. This array can be used to re-shuffle the elements of`A`

into the sorted order via the array index expression`A = A[I]`

. This operation may also be written:A = A[array_sort(A)];

**Example**-
A homogeneous list may be sorted by using the opaque form of the

`array_sort`

function:

Alternatively one may first convert it to an array and use the built-in comparison function:private define cmp_function (s, i, j) { if (s[i] > s[j]) return 1; if (s[i] < s[j]) return -1; return 0; } list = {}; % fill list .... % now sort it i = array_sort (list, &cmp_function, length(list)); % Create a new sorted list list = list[i];

to get the effect of an "in-place" sort.a = list_to_array (list); i = array_sort(a); % Rearrange the elements list[*] = a[i];

**Notes**-
The default sorting algorithm is merge-sort. It has an N*log(N) worst-case runtime compared to quick-sort's worst-case N^2 runtime. The primary advantage of quick-sort is that it uses O(1) additional memory, whereas merge-sort requires O(N) additional memory.

A stable sorting algorithm is one that preserves the order of equal elements. Merge-sort is an inherently stable algorithm, whereas quick-sort is not. Nevertheless, the slang library ensures the stability of the results because it uses the indices themeselves as tie-breakers. As a result, the following two statments may not produce the same results:

i = array_sort (a; dir=-1); i = array_reverse (array_sort (a; dir=1));

**See Also**-
set_default_sort_method, get_default_sort_method, strcmp, list_to_array

**Synopsis**-
Swap elements of an array

**Usage**-
`array_swap (Array_Type a, Int_Type i, Int_Type j)`

**Description**-
The

`array_swap`

function swaps the specified elements of an array. It is equivalent to

except that it executes several times faster than the above construct.(a[i], a[j]) = (a[j], a[i]);

**See Also**

**Synopsis**-
Compute the cumulative sum of an array

**Usage**-
`result = cumsum (Array_Type a [, Int_Type dim])`

**Description**-
The

`cumsum`

function performs a cumulative sum over the elements of a numeric array and returns the result. If a second argument is given, then it specifies the dimension of the array to be summed over. For example, the cumulative sum of`[1,2,3,4]`

, is the array`[1,1+2,1+2+3,1+2+3+4]`

, i.e.,`[1,3,6,10]`

. **See Also**

**Synopsis**-
Get the default sorting method

**Usage**-
`String_Type get_default_sort_method ()`

**Description**-
This function may be used to get the default sorting method used by

`array_sort`

. It will return one of the following strings:"msort" Merge-Sort "qsort" Quick-Sort

**See Also**

**Synopsis**-
Initialize an array of characters

**Usage**-
`init_char_array (Array_Type a, String_Type s)`

**Description**-
The

`init_char_array`

function may be used to initialize a Char_Type array`a`

by setting the elements of the array`a`

to the corresponding bytes of the string`s`

. **Example**-
The statements

creates an character array and initializes its elements to the bytes in the stringvariable a = Char_Type [10]; init_char_array (a, "HelloWorld");

`"HelloWorld"`

. **Notes**-
The character array must be large enough to hold all the characters of the initialization string. This function uses byte-semantics.

**See Also**

**Synopsis**-
Check an array for NULL elements

**Usage**-
`Char_Type[] = _isnull (a[])`

**Description**-
This function may be used to test for the presence of NULL elements of an array. Specifically, it returns a

`Char_Type`

array of with the same number of elements and dimensionality of the input array. If an element of the input array is`NULL`

, then the corresponding element of the output array will be set to`1`

, otherwise it will be set to`0`

. **Example**-
Set all

`NULL`

elements of a string array`A`

to the empty string`""`

:A[where(_isnull(A))] = "";

**Notes**-
It is important to understand the difference between

`A==NULL`

and`_isnull(A)`

. The latter tests all elements of`A`

against`NULL`

, whereas the former only tests`A`

itself. **See Also**

**Synopsis**-
Get the length of an object

**Usage**-
`Integer_Type length (obj)`

**Description**-
The

`length`

function may be used to get information about the length of an object. For simple scalar data-types, it returns 1. For arrays, it returns the total number of elements of the array. **Notes**-
If

`obj`

is a string,`length`

returns`1`

because a`String_Type`

object is considered to be a scalar. To get the number of characters in a string, use the`strlen`

function. **See Also**

**Synopsis**-
Get the maximum value of an array

**Usage**-
`result = max (Array_Type a [,Int_Type dim])`

**Description**-
The

`max`

function examines the elements of a numeric array and returns the value of the largest element. If a second argument is given, then it specifies the dimension of the array to be searched. In this case, an array of dimension one less than that of the input array will be returned with the corresponding elements in the specified dimension replaced by the maximum value in that dimension. **Example**-
Consider the 2-d array

generated by1 2 3 4 5 6 7 8 9 10

Thena = _reshape ([1:10], [2, 5]);

`max(a)`

will return`10`

, and`max(a,0)`

will return a 1-d array with elements6 7 8 9 10

**Notes**-
This function ignores NaNs in the input array.

**See Also**

**Synopsis**-
Get the maximum absolute value of an array

**Usage**-
`result = maxabs (Array_Type a [,Int_Type dim])`

**Description**-
The

`maxabs`

function behaves like the`max`

function except that it returns the maximum absolute value of the array. That is,`maxabs(x)`

is equivalent to`max(abs(x)`

. See the documentation for the`max`

function for more information. **See Also**

**Synopsis**-
Get the minimum value of an array

**Usage**-
`result = min (Array_Type a [,Int_Type dim])`

**Description**-
The

`min`

function examines the elements of a numeric array and returns the value of the smallest element. If a second argument is given, then it specifies the dimension of the array to be searched. In this case, an array of dimension one less than that of the input array will be returned with the corresponding elements in the specified dimension replaced by the minimum value in that dimension. **Example**-
Consider the 2-d array

generated by1 2 3 4 5 6 7 8 9 10

Thena = _reshape ([1:10], [2, 5]);

`min(a)`

will return`1`

, and`min(a,0)`

will return a 1-d array with elements1 2 3 4 5

**Notes**-
This function ignores NaNs in the input array.

**See Also**

**Synopsis**-
Get the minimum absolute value of an array

**Usage**-
`result = minabs (Array_Type a [,Int_Type dim])`

**Description**-
The

`minabs`

function behaves like the`min`

function except that it returns the minimum absolute value of the array. That is,`minabs(x)`

is equivalent to`min(abs(x)`

. See the documentation for the`min`

function for more information. **See Also**

**Synopsis**-
Copy an array to a new shape

**Usage**-
`Array_Type _reshape (Array_Type A, Array_Type I)`

**Description**-
The

`_reshape`

function creates a copy of an array`A`

, reshapes it to the form specified by`I`

and returns the result. The elements of`I`

specify the new dimensions of the copy of`A`

and must be consistent with the number of elements`A`

. **Example**-
If

`A`

is a`100`

element 1-d array, a new 2-d array of size`20`

by`5`

may be created from the elements of`A`

byB = _reshape (A, [20, 5]);

**Notes**-
The

`reshape`

function performs a similar function to`_reshape`

. In fact, the`_reshape`

function could have been implemented via:define _reshape (a, i) { a = @a; % Make a new copy reshape (a, i); return a; }

**See Also**

**Synopsis**-
Reshape an array

**Usage**-
`reshape (Array_Type A, Array_Type I)`

**Description**-
The

`reshape`

function changes the shape of`A`

to have the shape specified by the 1-d integer array`I`

. The elements of`I`

specify the new dimensions of`A`

and must be consistent with the number of elements`A`

. **Example**-
If

`A`

is a`100`

element 1-d array, it can be changed to a 2-d`20`

by`5`

array via

However,reshape (A, [20, 5]);

`reshape(A, [11,5])`

will result in an error because the`[11,5]`

array specifies`55`

elements. **Notes**-
Since

`reshape`

modifies the shape of an array, and arrays are treated as references, then all references to the array will reference the new shape. If this effect is unwanted, then use the`_reshape`

function instead. **See Also**

**Synopsis**-
Set the default sorting method

**Usage**-
`set_default_sort_method (String_Type method)`

**Description**-
This function may be used to set the default sorting method used by

`array_sort`

. The following methods are supported:"msort" Merge-Sort "qsort" Quick-Sort

**See Also**

**Synopsis**-
Sum over the elements of an array

**Usage**-
`result = sum (Array_Type a [, Int_Type dim])`

**Description**-
The

`sum`

function sums over the elements of a numeric array and returns its result. If a second argument is given, then it specifies the dimension of the array to be summed over. In this case, an array of dimension one less than that of the input array will be returned.If the input array is an integer type, then the resulting value will be a

`Double_Type`

. If the input array is a`Float_Type`

, then the result will be a`Float_Type`

. **Example**-
The mean of an array

`a`

of numbers issum(a)/length(a)

**See Also**

**Synopsis**-
Sum over the squares of the elements of an array

**Usage**-
`result = sumsq (Array_Type a [, Int_Type dim])`

**Description**-
The

`sumsq`

function sums over the squares of the elements of a numeric array and returns its result. If a second argument is given, then it specifies the dimension of the array to be summed over. In this case, an array of dimension one less than that of the input array will be returned.If the input array is an integer type, then the resulting value will be a

`Double_Type`

. If the input array is a`Float_Type`

, then the result will be a`Float_Type`

.For complex arrays, the sum will be over the squares of the moduli of the complex elements.

**See Also**

**Synopsis**-
Transpose an array

**Usage**-
`Array_Type transpose (Array_Type a)`

**Description**-
The

`transpose`

function returns the transpose of a specified array. By definition, the transpose of an array, say one with elements`a[i,j,...k]`

is an array whose elements are`a[k,...,j,i]`

. **See Also**

**Usage**-
`Array_Type where (Array_Type a [, Ref_Type jp])`

**Description**-
The

`where`

function examines a numeric array`a`

and returns an integer array giving the indices of`a`

where the corresponding element of`a`

is non-zero. The function accepts an optional`Ref_Type`

argument that will be set to complement set of indices, that is, the indices where`a`

is zero. In fact

andi = where (a); j = where (not a);

are equivalent, but the latter form is preferred since it executes about twice as fast as the former.i = where (a, &j);

The

`where`

function can also be used with relational operators and with the boolean binary`or`

and`and`

operators, e.g.,

Using in the last example the short-circuitinga = where (array == "a string"); a = where (array <= 5); a = where (2 <= array <= 10); a = where ((array == "a string") or (array == "another string"));

`||`

and`&&`

operators, will result in a`TypeMismatchError`

exception.Although this function may appear to be simple or even trivial, it is arguably one of the most important and powerful functions for manipulating arrays.

**Example**-
Consider the following:

Here the variablevariable X = [0.0:10.0:0.01]; variable A = sin (X); variable I = where (A < 0.0); A[I] = cos (X) [I];

`X`

has been assigned an array of doubles whose elements range from`0.0`

through`10.0`

in increments of`0.01`

. The second statement assigns`A`

to an array whose elements are the`sin`

of the elements of`X`

. The third statement uses the`where`

function to get the indices of the elements of`A`

that are less than 0. Finally, the last statement replaces those elements of`A`

by the cosine of the corresponding elements of`X`

. **Notes**-
Support for the optional argument was added to version 2.1.0.

**See Also**-
wherefirst, wherelast, wherenot, wherediff, array_info, array_shape, _isnull

**Synopsis**-
Get the indices where adjacent elements differ

**Usage**-
`Array_Type wherediff (Array_Type A [, Ref_Type jp])`

**Description**-
This function returns an array of the indices where adjacent elements of the array

`A`

differ. If the optional second argument is given, it must be a reference to a variable whose value will be set to the complement indices (those where adjacient elements are the same).The returned array of indices will consist of those elements

`i`

where`A[i] != A[i-1]`

. Since no element preceeds the 0th element,`A[0]`

differs from its non-existing preceeding element; hence the index`0`

will a member of the returned array. **Example**-
Suppose that

`A = [1, 1, 3, 0, 0, 4, 7, 7]`

. Then,

will result ini = wherediff (A, &j);

`i = [0, 2, 3, 5, 6]`

and`j = [1, 4, 7]`

. **Notes**-
Higher dimensional arrays are treated as a 1-d array of contiguous elements.

**See Also**

**Synopsis**-
Get the index of the first non-zero array element

**Usage**-
`Int_Type wherefirst (Array_Type a [,start_index])`

**Description**-
The

`wherefirst`

function returns the index of the first non-zero element of a specified array. If the optional parameter`start_index`

is given, the search will take place starting from that index. If a non-zero element is not found, the function will return`NULL`

. **Notes**-
The single parameter version of this function is equivalent to

define wherefirst (a) { variable i = where (a); if (length(i)) return i[0]; else return NULL; }

**See Also**-
where, wherelast, wherelast<@@ref>wherfirstminwherfirstmin, wherelast<@@ref>wherfirstminwherfirstmin<@@ref>wherfirstmaxwherfirstmax

**Synopsis**-
Get the index of the first maximum array value

**Usage**-
`Int_Type wherefirstmax (Array_Type a)`

**Description**-
This function is equivalent to

It executes about 3 times faster, and does not require the creation of temporary arrays.index = wherefirst (a == max(a));

**See Also**

**Synopsis**-
Get the index of the first minimum array value

**Usage**-
`Int_Type wherefirstmin (Array_Type a)`

**Description**-
This function is equivalent to

It executes about 3 times faster, and does not require the creation of temporary arrays.index = wherefirst (a == min(a));

**See Also**

**Synopsis**-
Get the index of the last non-zero array element

**Usage**-
`Int_Type wherelast (Array_Type a [,start_index])`

**Description**-
The

`wherelast`

function returns the index of the last non-zero element of a specified array. If the optional parameter`start_index`

is given, the backward search will take place starting from that index. If a non-zero element is not found, the function will return`NULL`

. **Notes**-
The single parameter version of this function is equivalent to

define wherelast (a) { variable i = where (a); if (length(i)) return i[-1]; else return NULL; }

**See Also**

**Synopsis**-
Get the index of the last maximum array value

**Usage**-
`Int_Type wherelastmax (Array_Type a)`

**Description**-
This function is equivalent to

It executes about 3 times faster, and does not require the creation of temporary arrays.index = wherelast (a == max(a));

**See Also**

**Synopsis**-
Get the index of the last minimum array value

**Usage**-
`Int_Type wherelastmin (Array_Type a)`

**Description**-
This function is equivalent to

It executes about 3 times faster, and does not require the creation of temporary arrays.index = wherelast (a == min(a));

**See Also**

**Synopsis**-
Get indices where a numeric array is 0

**Usage**-
`Array_Type wherenot (Array_Type a)`

**Description**-
This function is equivalent to

`where(not a)`

. See the documentation for`where`

for more information. **See Also**

Next Previous Contents