Next Previous Contents

## 2. Array Functions

## 2.1 all

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

  > `

  >           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]

  > `

See Also

  `where, any`

## 2.2 any

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

  > `

  >           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

  > `

See Also

  `where, all`

## 2.3 array_info

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

  `typeof, array_info, array_shape, length, reshape, _reshape`

## 2.4 array_map

Synopsis

  Apply a function to each element of an array

Usage

  `Array_Type array_map (type, func, arg0, ...)`

  > `

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

Example

  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"];

  > `

Notes

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

  > `

See Also

  `array_info, strlen, strcat, sin`

## 2.5 array_reverse

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

  > `

  >         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.
See Also

  `array_swap, transpose`

## 2.6 array_shape

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

  `array_info, reshape`

## 2.7 array_sort

Synopsis

  Sort an array

Usage

  `Array_Type array_sort (Array_Type a [, String_Type or Ref_Type f])`

Description

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

Example

  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)];

  > `

See Also

  `strcmp`

## 2.8 array_swap

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

  > `

  >         (a[i], a[j]) = (a[j], a[i]);

  > `

  except that it executes several times faster than the above construct.
See Also

  `array_reverse, transpose`

## 2.9 cumsum

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

  `sum`

## 2.10 init_char_array

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 character array `a` by setting the elements of the array `a` to the corresponding characters of the string `s`.

Example

  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"`.
Notes

  The character array must be large enough to hold all the characters of the initialization string.

See Also

  `bstring_to_array, strlen, strcat`

## 2.11 _isnull

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

  `where, array_map`

## 2.12 length

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

  `array_info, array_shape, typeof, strlen`

## 2.13 max

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

  > `

  >           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

  > `

Notes

  This function ignores NaNs in the input array.

See Also

  `min, sum, reshape`

## 2.14 min

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

  > `

  >           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

  > `

Notes

  This function ignores NaNs in the input array.

See Also

  `max, sum, reshape`

## 2.15 _reshape

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

  > `

  >           B = _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

  `reshape, array_shape, array_info`

## 2.16 reshape

Synopsis

  Reshape an array

Usage

  `reshape (Array_Type A, Array_Type I)`

Description

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

Example

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

  `_reshape, array_info, array_shape`

## 2.17 sum

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 is

  > `

  >         sum(a)/length(a)

  > `

See Also

  `cumsum, transpose, reshape`

## 2.18 transpose

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

  `_reshape, reshape, sum, array_info, array_shape`

## 2.19 where

Synopsis

  Get indices where a numeric array is non-zero

Usage

  `Array_Type where (Array_Type a)`

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.

  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:

  > `

  >         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`.
See Also

  `array_info, array_shape, _isnull`

Next Previous Contents