Tests if all elements of an array are non-zero
Char_Type all (Array_Type a [,Int_Type dim])
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.
Consider the 2-d array
1 2 3 4 5
6 7 8 9 10
a = _reshape ([1:10], [2, 5]);
all(a) will return 1, and all(a>3, 0) will return
a 1-d array
[0, 0, 0, 1, 1]
all(a>3, 1) will return the 1-d array
[0,1]
Test if any element of an array is non-zero
Char_Type any (Array_Type a [,Int_Type dim])
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.
Consider the 2-d array
1 2 3 4 5
6 7 8 9 10
a = _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
Returns information about an array
(Array_Type, Integer_Type, DataType_Type) array_info (Array_Type a)
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.
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];
}
Apply a function to each element of an array
Array_Type array_map (type, func, args...)
(Array_Type, ...) array_map (type, ..., func, args...)
DataType_Type type, ...;
Ref_Type func;
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.
The first example illustrates how to apply the strlen function
to an array of strings.
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
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);
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.
Reverse the elements of an array
array_reverse (Array_Type a [,Int_Type i0, Int_Type i1] [,Int_Type dim])
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.
If a is a one dimensional array, then
array_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.
Get the shape or dimensions of an array
dims = array_shape (Array_Type a)
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.
Sort an array or opaque object
Array_Type array_sort (obj [, &func [, n]])
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.
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".
An array of strings may be sorted using the strcmp function
since it fits the specification for the sorting function described
above:
A = ["gamma", "alpha", "beta"];
I = array_sort (A, &strcmp);
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)];
A homogeneous list may be sorted by using the opaque form of the
array_sort 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];
a = list_to_array (list);
i = array_sort(a);
% Rearrange the elements
list[*] = a[i];
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));
set_default_sort_method, get_default_sort_method, strcmp, list_to_array
Swap elements of an array
array_swap (Array_Type a, Int_Type i, Int_Type j)
The array_swap function swaps the specified elements of an
array. It is equivalent to
(a[i], a[j]) = (a[j], a[i]);
Compute the cumulative sum of an array
result = cumsum (Array_Type a [, Int_Type dim])
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].
Get the default sorting method
String_Type get_default_sort_method ()
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
Initialize an array of characters
init_char_array (Array_Type a, String_Type s)
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.
The statements
variable a = Char_Type [10];
init_char_array (a, "HelloWorld");
"HelloWorld".
The character array must be large enough to hold all the characters of the initialization string. This function uses byte-semantics.
Check an array for NULL elements
Char_Type[] = _isnull (a[])
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.
Set all NULL elements of a string array A to the empty
string "":
A[where(_isnull(A))] = "";
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.
Get the length of an object
Integer_Type length (obj)
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.
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.
Get the maximum value of an array
result = max (Array_Type a [,Int_Type dim])
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.
Consider the 2-d array
1 2 3 4 5
6 7 8 9 10
a = _reshape ([1:10], [2, 5]);
max(a) will return 10, and max(a,0) will return
a 1-d array with elements
6 7 8 9 10
This function ignores NaNs in the input array.
Get the maximum absolute value of an array
result = maxabs (Array_Type a [,Int_Type dim])
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.
Get the minimum value of an array
result = min (Array_Type a [,Int_Type dim])
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.
Consider the 2-d array
1 2 3 4 5
6 7 8 9 10
a = _reshape ([1:10], [2, 5]);
min(a) will return 1, and min(a,0) will return
a 1-d array with elements
1 2 3 4 5
This function ignores NaNs in the input array.
Get the minimum absolute value of an array
result = minabs (Array_Type a [,Int_Type dim])
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.
Copy an array to a new shape
Array_Type _reshape (Array_Type A, Array_Type I)
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.
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
by
B = _reshape (A, [20, 5]);
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;
}
Reshape an array
reshape (Array_Type A, Array_Type I)
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.
If A is a 100 element 1-d array, it can be changed to a
2-d 20 by 5 array via
reshape (A, [20, 5]);
reshape(A, [11,5]) will result in an error because
the [11,5] array specifies 55 elements.
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.
Set the default sorting method
set_default_sort_method (String_Type method)
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
Sum over the elements of an array
result = sum (Array_Type a [, Int_Type dim])
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.
The mean of an array a of numbers is
sum(a)/length(a)
Sum over the squares of the elements of an array
result = sumsq (Array_Type a [, Int_Type dim])
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.
Transpose an array
Array_Type transpose (Array_Type a)
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].
Array_Type where (Array_Type a [, Ref_Type jp])
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
i = where (a);
j = where (not a);
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.,
a = 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.
Consider the following:
variable 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.
Support for the optional argument was added to version 2.1.0.
wherefirst, wherelast, wherenot, wherediff, array_info, array_shape, _isnull
Get the indices where adjacent elements differ
Array_Type wherediff (Array_Type A [, Ref_Type jp])
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.
Suppose that A = [1, 1, 3, 0, 0, 4, 7, 7]. Then,
i = wherediff (A, &j);
i = [0, 2, 3, 5, 6] and j = [1, 4, 7].
Higher dimensional arrays are treated as a 1-d array of contiguous elements.
Get the index of the first non-zero array element
Int_Type wherefirst (Array_Type a [,start_index])
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.
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;
}
where, wherelast, wherelast<@@ref>wherfirstminwherfirstmin, wherelast<@@ref>wherfirstminwherfirstmin<@@ref>wherfirstmaxwherfirstmax
Get the index of the first maximum array value
Int_Type wherefirstmax (Array_Type a)
This function is equivalent to
index = wherefirst (a == max(a));
Get the index of the first minimum array value
Int_Type wherefirstmin (Array_Type a)
This function is equivalent to
index = wherefirst (a == min(a));
Get the index of the last non-zero array element
Int_Type wherelast (Array_Type a [,start_index])
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.
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;
}
Get the index of the last maximum array value
Int_Type wherelastmax (Array_Type a)
This function is equivalent to
index = wherelast (a == max(a));
Get the index of the last minimum array value
Int_Type wherelastmin (Array_Type a)
This function is equivalent to
index = wherelast (a == min(a));
Get indices where a numeric array is 0
Array_Type wherenot (Array_Type a)
This function is equivalent to where(not a). See the
documentation for where for more information.