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
generated by
a = _reshape ([1:10], [2, 5]);
Then all(a)
will return 1, and all(a>3, 0)
will return
a 1-d array
[0, 0, 0, 1, 1]
Similarly, all(a>3, 1)
will return the 1-d array
[0,1]
where, any
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
generated by
a = _reshape ([1:10], [2, 5]);
Then any(a==3)
will return 1, and any(a==3, 0)
will return a 1-d array with elements:
0 0 1 0 0
where, all
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];
}
typeof, array_info, array_shape, length, reshape, _reshape
Apply a function to each element of an array
Array_Type array_map (type, func, arg0, ...)
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. The arg0
parameter should be an array
and is used to determine the dimensions of the resulting array. If
any subsequent arguments correspond to an array of the same size,
then those array elements will be passed in parallel with the first
arrays arguments.
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);
This is equivalent to:
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"];
Many mathematical functions already work transparantly on arrays. For example, the following two statements produce identical results:
B = sin (A);
B = array_map (Double_Type, &sin, A);
array_info, strlen, strcat, sin
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]];
are equivalent to one another. However, the form using
array_reverse
is about 10 times faster than the version that
uses explicit array indexing.
array_swap, transpose
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.
array_info, reshape
Sort an array
Array_Type array_sort (Array_Type a [, String_Type or Ref_Type f])
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.
If f
is present, then it must be either a string representing
the name of the comparison function, or a reference to the function.
The sort function represented by f
must be a S-Lang function
that takes two arguments. The function must return an integer that
is less than zero if the first parameter is considered to be less
than the second, zero if they are equal, and a value greater than
zero if the first is greater than the second.
If the comparison function is not specified, then a built-in comparison
function appropriate for the data type will be used. For example,
if a
is an array of character strings, then the sort will be
performed using the strcmp
function.
The integer array returned by this function is simply an index array
that indicates the order of the sorted array. The input array
a
is not changed.
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);
Alternatively, one may use
variable I = array_sort (A);
to use the built-in comparison function.
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)];
strcmp
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]);
except that it executes several times faster than the above construct.
array_reverse, transpose
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]
.
sum
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
character array a
by setting the elements of the array
a
to the corresponding characters of the string s
.
The statements
variable a = Char_Type [10];
init_char_array (a, "HelloWorld");
creates an character array and initializes its elements to the
characters in the string "HelloWorld"
.
The character array must be large enough to hold all the characters of the initialization string.
bstring_to_array, strlen, strcat
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.
where, array_map
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.
array_info, array_shape, typeof, strlen
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
generated by
a = _reshape ([1:10], [2, 5]);
Then 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.
min, sum, reshape
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
generated by
a = _reshape ([1:10], [2, 5]);
Then 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.
max, sum, reshape
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, array_shape, array_info
Reshape an array
reshape (Array_Type A, Array_Type I)
The reshape
function changes the shaper 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]);
However, 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.
_reshape, array_info, array_shape
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)
cumsum, transpose, reshape
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]
.
_reshape, reshape, sum, array_info, array_shape
Get indices where a numeric array is non-zero
Array_Type where (Array_Type a)
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.
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];
Here the variable 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
.
array_info, array_shape, _isnull