slangfun.txt

一个C格式的脚本处理函数库源代码,可让你的C程序具有执行C格式的脚本文件

_isnull

 SYNOPSIS
   Check 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
--------------------------------------------------------------

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

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

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

 SEE ALSO
   typeof, reshape, length, _reshape
--------------------------------------------------------------

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

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

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

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

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

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 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 `max(a)' will return `10', and `max(a,0)' will return
   a 1-d array with elements

         6       7       8       9       10


 SEE ALSO
   max, sum, reshape
--------------------------------------------------------------

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


 SEE ALSO
   max, sum, reshape
--------------------------------------------------------------

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

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

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

where

 SYNOPSIS
   Get indices where an integer array is non-zero

 USAGE
   Array_Type where (Array_Type a)

 DESCRIPTION
   The `where' function examines an 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.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
--------------------------------------------------------------

assoc_delete_key

 SYNOPSIS
   Delete a key from an Associative Array

 USAGE
   assoc_delete_key (Assoc_Type a, String_Type k)

 DESCRIPTION