Description: Documentation

## function _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 array 2-d array of size 20 by 5 may be created from the elements of A by

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

In this example, the original array was no longer needed. Hence, it is preferable to make use of the __tmp operator to avoid the creation of a new array, i.e.,

          A = _reshape (__tmp(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_info

## function 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 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];
        }

For 1-d arrays, this information is more easily obtained from the length function.

### See also

typeof , reshape , length , _reshape

## function 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 result as an array of a 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 mathemetical 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

## function 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 SLang user-defined 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 comparision 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 preformed using strcmp . The integer array returned by this function is simply an index 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:

         variable A = String_Type [3];
         A[0] = "gamma"; A[1] = "alpha"; A[2] = "beta";

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

### See also

strcmp

## function 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

## function 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 , typeof , strlen

## function reshape

### Synopsis

Reshape an array

### Usage

reshape (Array_Type A, Array_Type I)

### Description

The reshape function changes the size of A to have the size 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 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

## function transpose

### Synopsis

Transpose a 2d 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 , array_info

## function where

### Synopsis

Get indices where an integer array is non-zero

### Usage

Array_Type where (Array_Type a)

### Description

The where function examines an integer array a and returns a 2-d integer array whose rows are the indices of a where the corresponding element of a is non-zero.

### 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.0 . Finally, the last statement substitutes into A the cos of the elements of X at the positions of A where the corresponding sin is less than 0 . The end result is that the elements of A are a mixture of sines and cosines.

### See also

array_info , sin , cos