libslang2 2.2.4-3ubuntu1 / usr / share / doc / libslang2 / slangfun.txt

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

--------------------------------------------------------------

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

--------------------------------------------------------------

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_shape, length, reshape, _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 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 transparently 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_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

--------------------------------------------------------------

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

--------------------------------------------------------------

array_sort

 SYNOPSIS
  Sort an array or opaque object

 USAGE
  Array_Type array_sort (obj [, &func [, n]])

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

 QUALIFIERS
  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"'.

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


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

  Alternatively one may first convert it to an array and use the
  built-in comparison function:

    a = list_to_array (list);
    i = array_sort(a);

    % Rearrange the elements
    list[*] = a[i];

  to get the effect of an "in-place" sort.

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


 SEE ALSO
  set_default_sort_method, get_default_sort_method, strcmp, list_to_array

--------------------------------------------------------------

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

--------------------------------------------------------------

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

--------------------------------------------------------------

get_default_sort_method

 SYNOPSIS
  Get the default sorting method

 USAGE
  String_Type get_default_sort_method ()

 DESCRIPTION
  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


 SEE ALSO
  set_default_sort_method, array_sort

--------------------------------------------------------------

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

--------------------------------------------------------------

_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

--------------------------------------------------------------

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

--------------------------------------------------------------

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, maxabs, sum, reshape

--------------------------------------------------------------

maxabs

 SYNOPSIS
  Get the maximum absolute value of an array

 USAGE
  result = maxabs (Array_Type a [,Int_Type dim])

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

 SEE ALSO
  min, max, minabs

--------------------------------------------------------------

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

--------------------------------------------------------------

minabs

 SYNOPSIS
  Get the minimum absolute value of an array

 USAGE
  result = minabs (Array_Type a [,Int_Type dim])

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

 SEE ALSO
  min, max, maxabs

--------------------------------------------------------------

_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

--------------------------------------------------------------

reshape

 SYNOPSIS
  Reshape an array

 USAGE
  reshape (Array_Type A, Array_Type I)

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

 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

--------------------------------------------------------------

set_default_sort_method

 SYNOPSIS
  Set the default sorting method

 USAGE
  set_default_sort_method (String_Type method)

 DESCRIPTION
  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


 SEE ALSO
  get_default_sort_method, array_sort

--------------------------------------------------------------

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, sumsq, transpose, reshape

--------------------------------------------------------------

sumsq

 SYNOPSIS
  Sum over the squares of the elements of an array

 USAGE
  result = sumsq (Array_Type a [, Int_Type dim])

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

 SEE ALSO
  cumsum, sumsq, hypot, 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, array_shape

--------------------------------------------------------------

where

 USAGE
  Array_Type where (Array_Type a [, Ref_Type jp])

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

  and

     i = where (a, &j);

  are equivalent, but the latter form is preferred since it executes
  about twice as fast as the former.

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

 NOTES
  Support for the optional argument was added to version 2.1.0.

 SEE ALSO
  wherefirst, wherelast, wherenot, array_info, array_shape, _isnull

--------------------------------------------------------------

wherenot

 SYNOPSIS
  Get indices where a numeric array is 0

 USAGE
  Array_Type wherenot (Array_Type)

 DESCRIPTION
  This function is equivalent to `where(not a)'.  See the
  documentation for `where' for more information.

 SEE ALSO
  where, wherefirst, wherelast

--------------------------------------------------------------

wherefirst

 SYNOPSIS
  Get the index of the first non-zero array element

 USAGE
  Int_Type wherefirst (Array_Type a [,start_index])

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

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


 SEE ALSO
  where, wherelast

--------------------------------------------------------------

wherelast

 SYNOPSIS
  Get the index of the last non-zero array element

 USAGE
  Int_Type wherelast (Array_Type a [,start_index])

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

 NOTES
  The single parameter version of this function is equivalent to

     define wherefirst (a)
     {
        variable i = where (a);
        if (length(i))
          return i[-1];
        else
          return NULL;
     }


 SEE ALSO
  where, wherefirst

--------------------------------------------------------------

assoc_delete_key

 SYNOPSIS
  Delete a key from an Associative Array

 USAGE
  assoc_delete_key (Assoc_Type a, String_Type k)

 DESCRIPTION
  The `assoc_delete_key' function deletes a key given by `k'
  from the associative array `a'.  If the specified key does not
  exist in `a', then this function has no effect.

 SEE ALSO
  assoc_key_exists, assoc_get_keys

--------------------------------------------------------------

assoc_get_keys

 SYNOPSIS
  Return all the key names of an Associative Array

 USAGE
  String_Type[] assoc_get_keys (Assoc_Type a)

 DESCRIPTION
  This function returns all the key names of an associative array
  `a' as an ordinary one dimensional array of strings.  If the
  associative array contains no keys, an empty array will be returned.

 SEE ALSO
  assoc_get_values, assoc_key_exists, assoc_delete_key, length

--------------------------------------------------------------

assoc_get_values

 SYNOPSIS
  Return all the values of an Associative Array

 USAGE
  Array_Type assoc_get_keys (Assoc_Type a)

 DESCRIPTION
  This function returns all the values in the associative array
  `a' as an array of proper type.  If the associative array
  contains no keys, an empty array will be returned.

 EXAMPLE
  Suppose that `a' is an associative array of type
  Integer_Type, i.e., it was created via

      variable a = Assoc_Type[Integer_Type];

  The the following may be used to print the values of the array in
  ascending order:

      define print_sorted_values (a)
      {
         variable v = assoc_get_values (a);
         variable i = array_sort (v);
         v = v[i];
         foreach (v)
           {
              variable vi = ();
              () = fprintf (stdout, "%d\n", vi);
           }
      }


 SEE ALSO
  assoc_get_values, assoc_key_exists, assoc_delete_key, array_sort

--------------------------------------------------------------

assoc_key_exists

 SYNOPSIS
  Check to see whether a key exists in an Associative Array

 USAGE
  Integer_Type assoc_key_exists (Assoc_Type a, String_Type k)

 DESCRIPTION
  The `assoc_key_exists' function may be used to determine whether
  or not a specified key `k' exists in an associative array `a'.
  It returns 1 if the key exists, or 0 if it does not.

 SEE ALSO
  assoc_get_keys, assoc_get_values, assoc_delete_key

--------------------------------------------------------------

array_to_bstring

 SYNOPSIS
  Convert an array to a binary string

 USAGE
  BString_Type array_to_bstring (Array_Type a)

 DESCRIPTION
   The `array_to_bstring' function returns the elements of an
   array `a' as a binary string.

 SEE ALSO
  bstring_to_array, init_char_array

--------------------------------------------------------------

bstring_to_array

 SYNOPSIS
  Convert a binary string to an array of characters

 USAGE
  UChar_Type[] bstring_to_array (BString_Type b)

 DESCRIPTION
   The `bstring_to_array' function returns an array of unsigned
   characters whose elements correspond to the bytes in the
   binary string.

 SEE ALSO
  array_to_bstring, init_char_array

--------------------------------------------------------------

bstrlen

 SYNOPSIS
  Get the length of a binary string

 USAGE
  UInt_Type bstrlen (BString_Type s)

 DESCRIPTION
  The `bstrlen' function may be used to obtain the length of a
  binary string.  A binary string differs from an ordinary string (a C
  string) in that a binary string may include null characters.

 EXAMPLE

    s = "hello\0";
    len = bstrlen (s);      % ==> len = 6
    len = strlen (s);       % ==> len = 5


 SEE ALSO
  strlen, length

--------------------------------------------------------------

count_byte_occurrences

 SYNOPSIS
  Count the number of occurrences of a byte in a binary string

 USAGE
  UInt_Type count_byte_occurrences (bstring, byte)

 DESCRIPTION
  This function returns the number of times the specified byte
  occurs in the binary string `bstr'.

 NOTES
  This function uses byte-semantics.  If character semantics are
  desired, use the `count_char_occurrences' function.

 SEE ALSO
  count_char_occurrences

--------------------------------------------------------------

pack

 SYNOPSIS
  Pack objects into a binary string

 USAGE
  BString_Type pack (String_Type fmt, ...)

 DESCRIPTION
  The `pack' function combines zero or more objects (represented
  by the ellipses above) into a binary string according to the format
  string `fmt'.

  The format string consists of one or more data-type specification
  characters defined by the following table:

     c     signed byte
     C     unsigned byte
     h     short
     H     unsigned short
     i     int
     I     unsigned int
     l     long
     L     unsigned long
     m     long long
     M     unsigned long long
     j     16 bit int
     J     16 bit unsigned int
     k     32 bit int
     K     32 bit unsigned int
     q     64 bit int
     Q     64 bit unsigned int
     f     float
     d     double
     F     32 bit float
     D     64 bit float
     s     character string, null padded
     S     character string, space padded
     z     character string, null padded
     x     a null pad character

  A decimal length specifier may follow the data-type specifier.  With
  the exception of the `s' and `S' specifiers, the length
  specifier indicates how many objects of that data type are to be
  packed or unpacked from the string.  When used with the `s',
  `S', or `z' specifiers, it indicates the field width to be
  used.  If the length specifier is not present, the length defaults
  to one.

  When packing, unlike the `s' specifier, the `z' specifier
  guarantees that at least one null byte will be written even if the
  field has to be truncated to do so.

  With the exception of `c', `C', `s', `S', and
  `x', each of these may be prefixed by a character that indicates
  the byte-order of the object:

     >    big-endian order (network order)
     <    little-endian order
     =    native byte-order

  The default is to use native byte order.

  When unpacking via the `unpack' function, if the length
  specifier is greater than one, then an array of that length will be
  returned.  In addition, trailing whitespace and null characters are
  stripped when unpacking an object given by the `S' specifier.
  Trailing null characters will be stripped from an object represented
  by the `z' specifier.  No such stripping is performed by the `s'
  specifier.

 EXAMPLE

     a = pack ("cc", 'A', 'B');         % ==> a = "AB";
     a = pack ("c2", 'A', 'B');         % ==> a = "AB";
     a = pack ("xxcxxc", 'A', 'B');     % ==> a = "\0\0A\0\0B";
     a = pack ("h2", 'A', 'B');         % ==> a = "\0A\0B" or "\0B\0A"
     a = pack (">h2", 'A', 'B');        % ==> a = "\0\xA\0\xB"
     a = pack ("<h2", 'A', 'B');        % ==> a = "\0B\0A"
     a = pack ("s4", "AB", "CD");       % ==> a = "AB\0\0"
     a = pack ("s4s2", "AB", "CD");     % ==> a = "AB\0\0CD"
     a = pack ("S4", "AB", "CD");       % ==> a = "AB  "
     a = pack ("S4S2", "AB", "CD");     % ==> a = "AB  CD"
     a = pack ("z4", "AB");             % ==> a = "AB\0\0"
     a = pack ("s4", "ABCDEFG");        % ==> a = "ABCD"
     a = pack ("z4", "ABCDEFG");        % ==> a = "ABC\0"


 SEE ALSO
  unpack, sizeof_pack, pad_pack_format, sprintf

--------------------------------------------------------------

pad_pack_format

 SYNOPSIS
  Add padding to a pack format

 USAGE
  BString_Type pad_pack_format (String_Type fmt)

 DESCRIPTION
  The `pad_pack_format' function may be used to add the
  appropriate padding characters to the format `fmt' such that the
  data types specified by the format will be properly aligned on word
  boundaries.  This is especially important when reading or writing files
  that assume the native alignment.

 SEE ALSO
  pack, unpack, sizeof_pack

--------------------------------------------------------------

sizeof_pack

 SYNOPSIS
  Compute the size implied by a pack format string

 USAGE
  UInt_Type sizeof_pack (String_Type fmt)

 DESCRIPTION
  The `sizeof_pack' function returns the size of the binary string
  represented by the format string `fmt'.  This information may be
  needed when reading a structure from a file.

 SEE ALSO
  pack, unpack, pad_pack_format

--------------------------------------------------------------

unpack

 SYNOPSIS
  Unpack Objects from a Binary String

 USAGE
  (...) = unpack (String_Type fmt, BString_Type s)

 DESCRIPTION
  The `unpack' function unpacks objects from a binary string
  `s' according to the format `fmt' and returns the objects to
  the stack in the order in which they were unpacked.  See the
  documentation of the `pack' function for details about the
  format string.

 EXAMPLE

    (x,y) = unpack ("cc", "AB");          % ==> x = 'A', y = 'B'
    x = unpack ("c2", "AB");              % ==> x = ['A', 'B']
    x = unpack ("x<H", "\0\xAB\xCD");     % ==> x = 0xCDABuh
    x = unpack ("xxs4", "a b c\0d e f");  % ==> x = "b c\0"
    x = unpack ("xxS4", "a b c\0d e f");  % ==> x = "b c"


 SEE ALSO
  pack, sizeof_pack, pad_pack_format

--------------------------------------------------------------

Assoc_Type

 SYNOPSIS
  An associative array or hash type

 DESCRIPTION
  An Assoc_Type object is like an array except that it is
  indexed using strings and not integers.  Unlike an Array_Type
  object, the size of an associative array is not fixed, but grows as
  objects are added to the array.  Another difference is that ordinary
  arrays represent ordered object; however, the ordering of the
  elements of an `Assoc_Type' object is unspecified.

  An Assoc_Type object whose elements are of some data-type
  `d' may be created using using

    A = Assoc_Type[d];

  For example,

    A = Assoc_Type[Int_Type];

  will create an associative array of integers.  To create an
  associative array capable of storing an arbitrary type, use the form

    A = Assoc_Type[];


  An optional parameter may be used to specify a default value for
  array elements.  For example,

   A = Assoc_Type[Int_Type, -1];

  creates an integer-valued associative array with a default element
  value of -1.  Then `A["foo"]' will return -1 if the key
  `"foo"' does not exist in the array.  Default values are
  available only if the type was specified when the associative array
  was created.

  The following functions may be used with associative arrays:

    assoc_get_keys
    assoc_get_values
    assoc_key_exists
    assoc_delete_key

  The `length' function may be used to obtain the number of
  elements in the array.

  The `foreach' construct may be used with associative arrays via
  one of the following forms:

      foreach k,v (A) {...}
      foreach k (A) using ("keys") { ... }
      foreach v (A) using ("values") { ... }
      foreach k,v (A) using ("keys", "values") { ... }

  In all the above forms, the loop is over all elements of the array
  such that `v=A[k]'.

 SEE ALSO
  List_Type, Array_Type, Struct_Type

--------------------------------------------------------------

List_Type

 SYNOPSIS
  A list object

 DESCRIPTION
  An object of type `List_Type' represents a list, which is
  defined as an ordered heterogeneous collection of objects.
  A list may be created using, e.g.,

    empty_list = {};
    list_with_4_items = {[1:10], "three", 9, {1,2,3}};

  Note that the last item of the list in the last example is also a
  list.  A List_Type object may be manipulated by the following
  functions:

    list_new
    list_insert
    list_append
    list_delete
    list_reverse
    list_pop

  A `List_Type' object may be indexed using an array syntax with
  the first item on the list given by an index of 0.  The
  `length' function may be used to obtain the number of elements
  in the list.

  A copy of the list may be created using the @ operator, e.g.,
  `copy = @list'.

  The `foreach' statement may be used with a List_Type
  object to loop over its elements:

    foreach elem (list) {....}


 SEE ALSO
  Array_Type, Assoc_Type, Struct_Type

--------------------------------------------------------------

String_Type

 SYNOPSIS
  A string object

 DESCRIPTION
  An object of type `String_Type' represents a string of bytes or
  characters, which in general have different semantics depending upon
  the UTF-8 mode.

  The string obeys byte-semantics when indexed as an
  array.  That is, `S[0]' will return the first byte of the
  string `S'.  For character semantics, the nth character in the
  string may be obtained using `substr' function.

  The `foreach' statement may be used with a String_Type
  object `S' to loop over its bytes:

    foreach b (S) {....}
    foreach b (S) using ("bytes") {....}

  To loop over its characters, the following form may be used:

    foreach c (S) using ("chars") {...}

  When UTF-8 mode is not in effect, the byte and character forms will
  produce the same sequence.  Otherwise, the string will be decoded
  to generate the (wide) character sequence.  If the string contains
  an invalid UTF-8 encoded character, successive bytes of the invalid
  sequence will be returned as negative integers.  For example,
  `"a\xAB\x{AB}"' specifies a string composed of the character
  `a', a byte `0xAB', and the character `0xAB'.  In
  this case,

     foreach c ("a\xAB\x{AB}") {...}

  will produce the integer-valued sequence `'a', -0xAB, 0xAB'.

 SEE ALSO
  Array_Type, _slang_utf8_ok

--------------------------------------------------------------

Struct_Type

 SYNOPSIS
  A structure datatype

 DESCRIPTION
  A Struct_Type object with fields `f1', `f2',...,
  `fN' may be created using

    s = struct { f1, f2, ..., fN };

  The fields may be accessed via the "dot" operator, e.g.,

     s.f1 = 3;
     if (s12.f1 == 4) s.f1++;

  By default, all fields will be initialized to NULL.

  A structure may also be created using the dereference operator (@):

    s = @Struct_Type ("f1", "f2", ..., "fN");
    s = @Struct_Type ( ["f1", "f2", ..., "fN"] );

  Functions for manipulating structure fields include:

     _push_struct_field_values
     get_struct_field
     get_struct_field_names
     set_struct_field
     set_struct_fields


  The `foreach' loop may be used to loop over elements of a linked
  list.  Suppose that first structure in the list is called
  `root', and that the `child' field is used to form the
  chain.  Then one may walk the list using:

     foreach s (root) using ("child")
      {
         % s will take on successive values in the list
          .
          .
      }

  The loop will terminate when the last elements `child' field is
  NULL.  If no ``linking'' field is specified, the field name will
  default to `next'.

  User-defined data types are similar to the `Struct_Type'.  A
  type, e.g., `Vector_Type' may be created using:

    typedef struct { x, y, z } Vector_Type;

  Objects of this type may be created via the @ operator, e.g.,

    v = @Vector_Type;

  It is recommended that this be used in a function for creating such
  types, e.g.,

    define vector (x, y, z)
    {
       variable v = @Vector_Type;
       v.x = x;
       v.y = y;
       v.z = z;
       return v;
    }

  The action of the binary and unary operators may be defined for such
  types.  Consider the "+" operator.  First define a function for
  adding two `Vector_Type' objects:

    static define vector_add (v1, v2)
    {
       return vector (v1.x+v2.x, v1.y+v2.y, v1.z, v2.z);
    }

  Then use

    __add_binary ("+", Vector_Type, &vector_add, Vector_Type, Vector_Type);

  to indicate that the function is to be called whenever the "+"
  binary operation between two `Vector_Type' objects takes place,
  e.g.,

    V1 = vector (1, 2, 3);
    V2 = vector (8, 9, 1);
    V3 = V1 + V2;

  will assigned the vector (9, 11, 4) to `V3'.  Similarly, the
  `"*"' operator between scalars and vectors may be defined using:

    static define vector_scalar_mul (v, a)
    {
       return vector (a*v.x, a*v.y, a*v.z);
    }
    static define scalar_vector_mul (a, v)
    {
       return vector_scalar_mul (v, a);
    }
    __add_binary ("*", Vector_Type, &scalar_vector_mul, Any_Type, Vector_Type);
    __add_binary ("*", Vector_Type, &vector_scalar_mul, Vector_Type, Any_Type);

  Related functions include:

    __add_unary
    __add_string
    __add_destroy


 SEE ALSO
  List_Type, Assoc_Type

--------------------------------------------------------------

File_Type

 SYNOPSIS
  A type representing a C stdio object

 DESCRIPTION
  An File_Type is the interpreter's representation of a C
  stdio FILE object and is usually created using the `fopen'
  function, i.e.,

    fp = fopen ("file.dat", "r");

  Functions that utilize the File_Type include:

    fopen
    fclose
    fgets
    fputs
    ferror
    feof
    fflush
    fprintf
    fseek
    ftell
    fread
    fwrite
    fread_bytes

  The `foreach' construct may be used with File_Type
  objects via one of the following forms:

   foreach line (fp) {...}
   foreach byte (A) using ("char") { ... }   % read bytes
   foreach line (A) using ("line") { ... }   % read lines (default)
   foreach line (A) using ("wsline") { ... } % whitespace stripped from lines


 SEE ALSO
  List_Type, Array_Type, Struct_Type

--------------------------------------------------------------

_bofeof_info

 SYNOPSIS
  Control the generation of function callback code

 USAGE
  Int_Type _bofeof_info

 DESCRIPTION
 This value of this variable dictates whether or not the S-Lang
 interpreter will generate code to call the beginning and end of
 function callback handlers.  The value of this variable is local to
 the compilation unit, but is inherited by other units loaded by the
 current unit.

 If the value of this variable is 1 when a function is defined, then
 when the function is executed, the callback handlers defined via
 `_set_bof_handler' and `_set_eof_handler' will be called.

 SEE ALSO
  _set_bof_handler, _set_eof_handler, _boseos_info

--------------------------------------------------------------

_boseos_info

 SYNOPSIS
  Control the generation of BOS/EOS callback code

 USAGE
  Int_Type _boseos_info

 DESCRIPTION
 This value of this variable dictates whether or not the S-Lang
 interpreter will generate code to call the beginning and end of
 statement callback handlers.  The value of this variable is local to
 the compilation unit, but is inherited by other units loaded by the
 current unit.

 The lower 8 bits of `_boseos_info' controls the generation of code for
 callbacks as follows:

   Value      Description
   -----------------------------------------------------------------
     0        No code for making callbacks will be produced.
     1        Callback generation will take place for all non-branching
              and looping statements.
     2        Same as for 1 with the addition that code will also be
              generated for branching statements (if, !if, loop, ...)
     3        Same as 2, but also including break and continue
              statements.

 A non-branching statement is one that does not effect chain of
 execution.  Branching statements include all looping statements,
 conditional statement, `break', `continue', and `return'.

 If bit 0x100 is set, callbacks will be generated for preprocessor
 statements.

 EXAMPLE
 Consider the following:

   _boseos_info = 1;
   define foo ()
   {
      if (some_expression)
        some_statement;
   }
   _boseos_info = 2;
   define bar ()
   {
      if (some_expression)
        some_statement;
   }

 The function `foo' will be compiled with code generated to call the
 BOS and EOS handlers when `some_statement' is executed.  The
 function `bar' will be compiled with code to call the handlers
 for both `some_expression' and `some_statement'.

 NOTES
 The `sldb' debugger and `slsh''s `stkcheck.sl' make use of this
 facility.

 SEE ALSO
  _set_bos_handler, _set_eos_handler, _bofeof_info

--------------------------------------------------------------

_clear_error

 SYNOPSIS
  Clear an error condition (deprecated)

 USAGE
  _clear_error ()

 DESCRIPTION
  This function has been deprecated.  New code should make use of
  try-catch exception handling.

  This function may be used in error-blocks to clear the error that
  triggered execution of the error block.  Execution resumes following
  the statement, in the scope of the error-block, that triggered the
  error.

 EXAMPLE
  Consider the following wrapper around the `putenv' function:

    define try_putenv (name, value)
    {
       variable status;
       ERROR_BLOCK
        {
          _clear_error ();
          status = -1;
        }
       status = 0;
       putenv (sprintf ("%s=%s", name, value);
       return status;
    }

  If `putenv' fails, it generates an error condition, which the
  `try_putenv' function catches and clears.  Thus `try_putenv'
  is a function that returns -1 upon failure and 0 upon
  success.

 SEE ALSO
  _trace_function, _slangtrace, _traceback

--------------------------------------------------------------

_set_bof_handler

 SYNOPSIS
  Set the beginning of function callback handler

 USAGE
  _set_bof_handler (Ref_Type func)

 DESCRIPTION
 This function is used to set the function to be called prior to the
 execution of the body S-Lang function but after its arguments have
 been evaluated, provided that function was defined
 with `_bofeof_info' set appropriately.  The callback function
 must be defined to take a single parameter representing the name of
 the function and must return nothing.

 EXAMPLE

    private define bof_handler (fun)
    {
      () = fputs ("About to execute $fun"$, stdout);
    }
    _set_bos_handler (&bof_handler);


 SEE ALSO
  _set_eof_handler, _boseos_info, _set_bos_handler

--------------------------------------------------------------

_set_bos_handler

 SYNOPSIS
  Set the beginning of statement callback handler

 USAGE
  _set_bos_handler (Ref_Type func)

 DESCRIPTION
 This function is used to set the function to be called prior to the
 beginning of a statement.  The function will be passed two
 parameters: the name of the file and the line number of the statement
 to be executed.  It should return nothing.

 EXAMPLE

    private define bos_handler (file, line)
    {
      () = fputs ("About to execute $file:$line\n"$, stdout);
    }
    _set_bos_handler (&bos_handler);


 NOTES
 The beginning and end of statement handlers will be called for
 statements in a file only if that file was compiled with the variable
 `_boseos_info' set to a non-zero value.

 SEE ALSO
  _set_eos_handler, _boseos_info, _bofeof_info

--------------------------------------------------------------

_set_eof_handler

 SYNOPSIS
  Set the beginning of function callback handler

 USAGE
  _set_eof_handler (Ref_Type func)

 DESCRIPTION
 This function is used to set the function to be called at the end of
 execution of a S-Lang function, provided that function was compiled with
 `_bofeof_info' set accordingly.

 The callback function will be passed no parameters and it must return
 nothing.

 EXAMPLE

   private define eof_handler ()
   {
     () = fputs ("Done executing the function\n", stdout);
   }
   _set_eof_handler (&eof_handler);


 SEE ALSO
  _set_bof_handler, _bofeof_info, _boseos_info

--------------------------------------------------------------

_set_eos_handler

 SYNOPSIS
  Set the end of statement callback handler

 USAGE
  _set_eos_handler (Ref_Type func)

 DESCRIPTION
 This function is used to set the function to be called at the end of
 a statement.  The function will be passed no parameters and it should
 return nothing.

 EXAMPLE

   private define eos_handler ()
   {
     () = fputs ("Done executing the statement\n", stdout);
   }
   _set_eos_handler (&eos_handler);


 NOTES
 The beginning and end of statement handlers will be called for
 statements in a file only if that file was compiled with the variable
 `_boseos_info' set to a non-zero value.

 SEE ALSO
  _set_bos_handler, _boseos_info, _bofeof_info

--------------------------------------------------------------

_slangtrace

 SYNOPSIS
  Turn function tracing on or off

 USAGE
  Integer_Type _slangtrace

 DESCRIPTION
  The `_slangtrace' variable is a debugging aid that when set to a
  non-zero value enables tracing when function declared by
  `_trace_function' is entered.  If the value is greater than
  zero, both intrinsic and user defined functions will get traced.
  However, if set to a value less than zero, intrinsic functions will
  not get traced.

 SEE ALSO
  _trace_function, _traceback, _print_stack

--------------------------------------------------------------

_traceback

 SYNOPSIS
  Generate a traceback upon error

 USAGE
  Integer_Type _traceback

 DESCRIPTION
  `_traceback' is an intrinsic integer variable whose bitmapped value
  controls the generation of the call-stack traceback upon error.
  When set to 0, no traceback will be generated.  Otherwise its value
  is the bitwise-or of the following integers:

       1        Create a full traceback
       2        Omit local variable information
       4        Generate just one line of traceback

  The default value of this variable is 4.

 NOTES
  Running `slsh' with the `-g' option causes this variable to be
  set to 1.

 SEE ALSO
  _boseos_info

--------------------------------------------------------------

_trace_function

 SYNOPSIS
  Set the function to trace

 USAGE
  _trace_function (String_Type f)

 DESCRIPTION
  `_trace_function' declares that the S-Lang function with name
  `f' is to be traced when it is called.  Calling
  `_trace_function' does not in itself turn tracing on.  Tracing
  is turned on only when the variable `_slangtrace' is non-zero.

 SEE ALSO
  _slangtrace, _traceback

--------------------------------------------------------------

_get_frame_info

 SYNOPSIS
  Get information about a stack frame

 USAGE
  Struct_Type _get_frame_info (Integer_Type depth)

 DESCRIPTION
  `_get_frame_info' returns a structure with information about
  the function call stack from of depth `depth'. The structure
  contains the following fields:

    file: The file that contains the code of the stack frame.
    line: The line number the file the stack frame is in.
    function: the name of the function containing the code of the stack
      frame; it might be NULL if the code isn't inside a function.
    locals: Array of String_Type containing the names of variables local
      to the stack frame; it might be NULL if the stack frame doesn't
      belong to a function.
    namespace: The namespace the code of this stack frame is in.


 SEE ALSO
  _get_frame_variable, _use_frame_namespace

--------------------------------------------------------------

_get_frame_variable

 SYNOPSIS
  Get the value of a variable local to a stack frame

 USAGE
  Any_Type _get_frame_variable (Integer_Type depth, String_Type name)

 DESCRIPTION
  This function returns value of the variable `name' in the stack
  frame at depth `depth'.  This might not only be a local variable but
  also variables from outer scopes, e.g., a variable private to the
  namespace.

  If no variable with this name is found an `UndefinedNameError'
  will be thrown.  An `VariableUninitializedError' will be
  generated if the variable has no value.

 SEE ALSO
  _get_frame_info, _use_frame_namespace

--------------------------------------------------------------

_use_frame_namespace

 SYNOPSIS
  Selects the namespace of a stack frame

 USAGE
  _use_frame_namespace (Integer_Type depth)

 DESCRIPTION
  This function sets the current namespace to the one belonging to the
  call stack frame at depth `depth'.

 SEE ALSO
  _get_frame_info, _get_frame_variable

--------------------------------------------------------------

access

 SYNOPSIS
  Check to see if a file is accessible

 USAGE
  Int_Type access (String_Type pathname, Int_Type mode)

 DESCRIPTION
 This functions checks to see if the current process has access to the
 specified pathname.  The `mode' parameter determines the type of
 desired access.  Its value is given by the bitwise-or of one or more
 of the following constants:

    R_OK   Check for read permission
    W_OK   Check for write permission
    X_OK   Check for execute permission
    F_OK   Check for existence


 The function will return 0 if process has the requested access
 permissions to the file, otherwise it will return -1 and set
 `errno' accordingly.

 Access to a file depend not only upon the file itself, but also upon
 the permissions of each of the directories in the pathname.  The
 checks are done using the real user and group ids of the process, and
 not using the effective ids.

 SEE ALSO
  stat_file

--------------------------------------------------------------

chdir

 SYNOPSIS
  Change the current working directory

 USAGE
  Int_Type chdir (String_Type dir)

 DESCRIPTION
  The `chdir' function may be used to change the current working
  directory to the directory specified by `dir'.  Upon success it
  returns zero.  Upon failure it returns `-1' and sets
  `errno' accordingly.

 SEE ALSO
  mkdir, stat_file

--------------------------------------------------------------

chmod

 SYNOPSIS
  Change the mode of a file

 USAGE
  Int_Type chmod (String_Type file, Int_Type mode)

 DESCRIPTION
  The `chmod' function changes the permissions of the specified
  file to those given by `mode'.  It returns `0' upon
  success, or `-1' upon failure setting `errno' accordingly.

  See the system specific documentation for the C library
  function `chmod' for a discussion of the `mode' parameter.

 SEE ALSO
  chown, stat_file

--------------------------------------------------------------

chown

 SYNOPSIS
  Change the owner of a file

 USAGE
  Int_Type chown (String_Type file, Int_Type uid, Int_Type gid)

 DESCRIPTION
  The `chown' function is used to change the user-id and group-id of
  `file' to `uid' and `gid', respectively.  It returns
  0 upon success and -1 upon failure, with `errno'
  set accordingly.

 NOTES
  On most systems, only the superuser can change the ownership of a
  file.

  Some systems do not support this function.

 SEE ALSO
  chmod, stat_file

--------------------------------------------------------------

getcwd

 SYNOPSIS
  Get the current working directory

 USAGE
  String_Type getcwd ()

 DESCRIPTION
  The `getcwd' function returns the absolute pathname of the
  current working directory.  If an error occurs or it cannot
  determine the working directory, it returns NULL and sets
  `errno' accordingly.

 NOTES
  Under Unix, OS/2, and MSDOS, the pathname returned by this function
  includes the trailing slash character.  It may also include
  the drive specifier for systems where that is meaningful.

 SEE ALSO
  mkdir, chdir, errno

--------------------------------------------------------------

hardlink

 SYNOPSIS
  Create a hard-link

 USAGE
  Int_Type hardlink (String_Type oldpath, String_Type newpath)

 DESCRIPTION
  The `hardlink' function creates a hard-link called
  `newpath' to the existing file `oldpath'.  If the link was
  successfully created, the function will return 0.  Upon error, the
  function returns -1 and sets `errno' accordingly.

 NOTES
  Not all systems support the concept of a hard-link.

 SEE ALSO
  symlink

--------------------------------------------------------------

listdir

 SYNOPSIS
  Get a list of the files in a directory

 USAGE
  String_Type[] listdir (String_Type dir)

 DESCRIPTION
  The `listdir' function returns the directory listing of all the
  files in the specified directory `dir' as an array of strings.
  It does not return the special files `".."' and `"."' as
  part of the list.

 SEE ALSO
  stat_file, stat_is, length

--------------------------------------------------------------

lstat_file

 SYNOPSIS
  Get information about a symbolic link

 USAGE
  Struct_Type lstat_file (String_Type file)

 DESCRIPTION
  The `lstat_file' function behaves identically to `stat_file'
  but if `file' is a symbolic link, `lstat_file' returns
  information about the link itself, and not the file that it
  references.

  See the documentation for `stat_file' for more information.

 NOTES
  On systems that do not support symbolic links, there is no
  difference between this function and the `stat_file' function.

 SEE ALSO
  stat_file, stat_is, stat_mode_to_string, readlink

--------------------------------------------------------------

mkdir

 SYNOPSIS
  Create a new directory

 USAGE
  Int_Type mkdir (String_Type dir [,Int_Type mode])

 DESCRIPTION
  The `mkdir' function creates a directory whose name is specified
  by the `dir' parameter with permissions given by the optional
  `mode' parameter.  Upon success `mkdir' returns 0, or it
  returns `-1' upon failure setting `errno' accordingly.  In
  particular, if the directory already exists, the function will fail
  and set errno to EEXIST.

 EXAMPLE
  The following function creates a new directory, if it does not
  already exist (indicated by `errno==EEXIST').

     define my_mkdir (dir)
     {
        if (0 == mkdir (dir)) return;
        if (errno == EEXIST) return;
        throw IOError,
           sprintf ("mkdir %s failed: %s", dir, errno_string (errno));
     }


 NOTES
  The `mode' parameter may not be meaningful on all systems.  On
  systems where it is meaningful, the actual permissions on the newly
  created directory are modified by the process's umask.

 SEE ALSO
  rmdir, getcwd, chdir, fopen, errno

--------------------------------------------------------------

readlink

 SYNOPSIS
  String_Type readlink (String_Type path)

 USAGE
  Get the value of a symbolic link

 DESCRIPTION
  The `readlink' function returns the value of a symbolic link.
  Upon failure, NULL is returned and `errno' set accordingly.

 NOTES
  Not all systems support this function.

 SEE ALSO
  symlink, lstat_file, stat_file, stat_is

--------------------------------------------------------------

remove

 SYNOPSIS
  Delete a file

 USAGE
  Int_Type remove (String_Type file)

 DESCRIPTION
  The `remove' function deletes a file.  It returns 0 upon
  success, or -1 upon error and sets `errno' accordingly.

 SEE ALSO
  rename, rmdir

--------------------------------------------------------------

rename

 SYNOPSIS
  Rename a file

 USAGE
  Int_Type rename (String_Type old, String_Type new)

 DESCRIPTION
  The `rename' function renames a file from `old' to `new'
  moving it between directories if necessary.  This function may fail
  if the directories are not on the same file system.  It returns
  0 upon success, or -1 upon error and sets `errno' accordingly.

 SEE ALSO
  remove, errno

--------------------------------------------------------------

rmdir

 SYNOPSIS
  Remove a directory

 USAGE
  Int_Type rmdir (String_Type dir)

 DESCRIPTION
  The `rmdir' function deletes the specified directory.  It returns
  0 upon success or -1 upon error and sets `errno' accordingly.

 NOTES
  The directory must be empty before it can be removed.

 SEE ALSO
  rename, remove, mkdir

--------------------------------------------------------------

stat_file

 SYNOPSIS
  Get information about a file

 USAGE
  Struct_Type stat_file (String_Type file)

 DESCRIPTION
  The `stat_file' function returns information about `file'
  through the use of the system `stat' call.  If the stat call
  fails, the function returns NULL and sets errno accordingly.
  If it is successful, it returns a stat structure with the following
  integer-value fields:

    st_dev
    st_ino
    st_mode
    st_nlink
    st_uid
    st_gid
    st_rdev
    st_size
    st_atime
    st_mtime
    st_ctime

  See the C library documentation of `stat' for a discussion of the
  meanings of these fields.

 EXAMPLE
  The following example shows how the `stat_file' function may be
  used to get the size of a file:

     define file_size (file)
     {
        variable st;
        st = stat_file(file);
        if (st == NULL)
          throw IOError, "Unable to stat $file"$;
        return st.st_size;
     }


 SEE ALSO
  lstat_file, stat_is, stat_mode_to_string, utime

--------------------------------------------------------------

stat_is

 SYNOPSIS
  Parse the st_mode field of a stat structure

 USAGE
  Char_Type stat_is (String_Type type, Int_Type st_mode)

 DESCRIPTION
  The `stat_is' function returns a boolean value according to
  whether or not the `st_mode' parameter is of the specified type.
  Specifically, `type' must be one of the strings:

     "sock"     (socket)
     "fifo"     (fifo)
     "blk"      (block device)
     "chr"      (character device)
     "reg"      (regular file)
     "lnk"      (link)
     "dir"      (dir)

  It returns a non-zero value if `st_mode' corresponds to
  `type'.

 EXAMPLE
  The following example illustrates how to use the `stat_is'
  function to determine whether or not a file is a directory:

     define is_directory (file)
     {
        variable st;

        st = stat_file (file);
        if (st == NULL) return 0;
        return stat_is ("dir", st.st_mode);
     }


 SEE ALSO
  stat_file, lstat_file, stat_mode_to_string

--------------------------------------------------------------

stat_mode_to_string

 SYNOPSIS
  Format the file type code and access permission bits as a string

 USAGE
  String_Type stat_mode_to_string (Int_Type st_mode)

 DESCRIPTION
  The `stat_mode_to_string' function returns a 10 characters string
  that indicates the type and permissions of a file as represented by
  the `st_mode' parameter.  The returned string consists of the following
  characters:

     "s"      (socket)
     "p"      (fifo)
     "b"      (block device)
     "c"      (character device)
     "-"      (regular file)
     "l"      (link)
     "d"      (dir)

  The access permission bit is one of the following characters:

     "s"      (set-user-id)
     "w"      (writable)
     "x"      (executable)
     "r"      (readable)


 NOTES
  This function is an `slsh' intrinsic.  As such, it is not part of
  S-Lang proper.

 SEE ALSO
  stat_file, lstat_file, stat_is

--------------------------------------------------------------

symlink

 SYNOPSIS
  Create a symbolic link

 USAGE
  status = symlink (String_Type oldpath, String_Type new_path)

 DESCRIPTION
  The `symlink' function may be used to create a symbolic link
  named `new_path' for  `oldpath'.  If successful, the function
  returns 0, otherwise it returns -1 and sets `errno' appropriately.

 NOTES
  This function is not supported on all systems and even if supported,
  not all file systems support the concept of a symbolic link.

 SEE ALSO
  readlink, hardlink

--------------------------------------------------------------

utime

 SYNOPSIS
  Change a file's last access and modification times

 USAGE
  Int_Type utime(String_Type file, Double_Type actime, Double_Type modtime)

 DESCRIPTION
 This function may be used to change the last access (actime) and last
 modification (modtime) times associated with the specified file.  If
 sucessful, the function returns 0; otherwise it returns -1 and sets
 `errno' accordingly.

 NOTES
 The `utime' function will call the C library `utimes'
 function if available, which permits microsecond accuracy.
 Otherwise, it will truncate the time arguments to integers and call
 the `utime' function.

 SEE ALSO
  stat_file

--------------------------------------------------------------

_$

 SYNOPSIS
  Expand the dollar-escaped variables in a string

 USAGE
  String_Type _$(String_Type s)

 DESCRIPTION
 This function expands the dollar-escaped variables in a string and
 returns the resulting string.

 EXAMPLE
 Consider the following code fragment:

     private variable Format = "/tmp/foo-$time.$pid";
     define make_filename ()
     {
        variable pid = getpid ();
        variable time = _time ();
        return _$(Format);
     }

 Note that the variable `Format' contains dollar-escaped
 variables, but because the `$' suffix was omitted from the
 string literal, the variables are not expanded.  Instead expansion is
 deferred until execution of the `make_filename' function through
 the use of the `_$' function.

 SEE ALSO
  eval, getenv

--------------------------------------------------------------

autoload

 SYNOPSIS
  Load a function from a file

 USAGE
  autoload (String_Type funct, String_Type file)

 DESCRIPTION
  The `autoload' function is used to declare `funct' to the
  interpreter and indicate that it should be loaded from `file'
  when it is actually used.  If `func' contains a namespace
  prefix, then the file will be loaded into the corresponding
  namespace.  Otherwise, if the `autoload' function is called
  from an execution namespace that is not the Global namespace nor an
  anonymous namespace, then the file will be loaded into the execution
  namespace.

 EXAMPLE
    Suppose `bessel_j0' is a function defined in the file
    `bessel.sl'.  Then the statement

      autoload ("bessel_j0", "bessel.sl");

    will cause `bessel.sl' to be loaded prior to the execution of
    `bessel_j0'.

 SEE ALSO
  evalfile, import

--------------------------------------------------------------

byte_compile_file

 SYNOPSIS
  Compile a file to byte-code for faster loading.

 USAGE
  byte_compile_file (String_Type file, Int_Type method)

 DESCRIPTION
  The `byte_compile_file' function byte-compiles `file'
  producing a new file with the same name except a `'c'' is added
  to the output file name.  For example, `file' is
  `"site.sl"', then this function produces a new file named
  `site.slc'.

 NOTES
  The `method' parameter is not used in the current
  implementation, but may be in the future.  For now, set
  it to `0'.

 SEE ALSO
  evalfile

--------------------------------------------------------------

eval

 SYNOPSIS
  Interpret a string as S-Lang code

 USAGE
  eval (String_Type expression [,String_Type namespace])

 DESCRIPTION
  The `eval' function parses a string as S-Lang code and executes the
  result.  If called with the optional namespace argument, then the
  string will be evaluated in the specified namespace.  If that
  namespace does not exist it will be created first.

  This is a useful function in many contexts including those where
  it is necessary to dynamically generate function definitions.

 EXAMPLE

    if (0 == is_defined ("my_function"))
      eval ("define my_function () { message (\"my_function\"); }");


 SEE ALSO
  is_defined, autoload, evalfile

--------------------------------------------------------------

evalfile

 SYNOPSIS
  Interpret a file containing S-Lang code

 USAGE
  Int_Type evalfile (String_Type file [,String_Type namespace])

 DESCRIPTION
  The `evalfile' function loads `file' into the interpreter
  and executes it.  If called with the optional namespace argument,
  the file will be loaded into the specified namespace, which will be
  created if necessary.  If given no namespace argument and the file
  has already been loaded, then it will be loaded again into an
  anonymous namespace.  A namespace argument given by the empty string
  will also cause the file to be loaded into a new anonymous namespace.

  If no errors were encountered, 1 will be returned; otherwise,
  a S-Lang exception will be thrown and the function will return zero.

 EXAMPLE

    define load_file (file)
    {
       try
       {
         () = evalfile (file);
       }
       catch AnyError;
    }


 NOTES
  For historical reasons, the return value of this function is not
  really useful.

  The file is searched along an application-defined load-path.  The
  `get_slang_load_path' and `set_slang_load_path' functions
  may be used to set and query the path.

 SEE ALSO
  eval, autoload, set_slang_load_path, get_slang_load_path

--------------------------------------------------------------

get_slang_load_path

 SYNOPSIS
  Get the value of the interpreter's load-path

 USAGE
  String_Type get_slang_load_path ()

 DESCRIPTION
  This function retrieves the value of the delimiter-separated search
  path used for loading files.  The delimiter is OS-specific and may
  be queried using the `path_get_delimiter' function.

 NOTES
  Some applications may not support the built-in load-path searching
  facility provided by the underlying library.

 SEE ALSO
  set_slang_load_path, path_get_delimiter

--------------------------------------------------------------

set_slang_load_path

 SYNOPSIS
  Set the value of the interpreter's load-path

 USAGE
  set_slang_load_path (String_Type path)

 DESCRIPTION
  This function may be used to set the value of the
  delimiter-separated search path used by the `evalfile' and
  `autoload' functions for locating files.  The delimiter is
  OS-specific and may be queried using the `path_get_delimiter'
  function.

 EXAMPLE

    public define prepend_to_slang_load_path (p)
    {
       variable s = stat_file (p);
       if (s == NULL) return;
       if (0 == stat_is ("dir", s.st_mode))
         return;

       p = sprintf ("%s%c%s", p, path_get_delimiter (), get_slang_load_path ());
       set_slang_load_path (p);
    }


 NOTES
  Some applications may not support the built-in load-path searching
  facility provided by the underlying library.

 SEE ALSO
  get_slang_load_path, path_get_delimiter, evalfile, autoload

--------------------------------------------------------------

get_import_module_path

 SYNOPSIS
  Get the search path for dynamically loadable objects

 USAGE
  String_Type get_import_module_path ()

 DESCRIPTION
  The `get_import_module_path' may be used to get the search path
  for dynamically shared objects.  Such objects may be made accessible
  to the application via the `import' function.

 SEE ALSO
  import, set_import_module_path

--------------------------------------------------------------

import

 SYNOPSIS
  Dynamically link to a specified module

 USAGE
  import (String_Type module [, String_Type namespace])

 DESCRIPTION
  The `import' function causes the run-time linker to dynamically
  link to the shared object specified by the `module' parameter.
  It searches for the shared object as follows: First a search is
  performed along all module paths specified by the application.  Then
  a search is made along the paths defined via the
  `set_import_module_path' function.  If not found, a search is
  performed along the paths given by the `SLANG_MODULE_PATH'
  environment variable.  Finally, a system dependent search is
  performed (e.g., using the `LD_LIBRARY_PATH' environment
  variable).

  The optional second parameter may be used to specify a namespace
  for the intrinsic functions and variables of the module.  If this
  parameter is not present, the intrinsic objects will be placed into
  the active namespace, or global namespace if the active namespace is
  anonymous.

  This function throws an `ImportError' if the specified module is
  not found.

 NOTES
  The `import' function is not available on all systems.

 SEE ALSO
  set_import_module_path, use_namespace, current_namespace, getenv, evalfile

--------------------------------------------------------------

set_import_module_path

 SYNOPSIS
  Set the search path for dynamically loadable objects

 USAGE
  set_import_module_path (String_Type path_list)

 DESCRIPTION
  The `set_import_module_path' may be used to set the search path
  for dynamically shared objects.  Such objects may be made accessible
  to the application via the `import' function.

  The actual syntax for the specification of the set of paths will
  vary according to the operating system.  Under Unix, a colon
  character is used to separate paths in `path_list'.  For win32
  systems a semi-colon is used.  The `path_get_delimiter'
  function may be used to get the value of the delimiter.

 SEE ALSO
  import, get_import_module_path, path_get_delimiter

--------------------------------------------------------------

add_doc_file

 SYNOPSIS
  Make a documentation file known to the help system

 USAGE
  add_doc_file (String_Type file)

 DESCRIPTION
  The `add_doc_file' is used to add a documentation file to the
  system.  Such files are searched by the
  `get_doc_string_from_file' function.  The `file' must be
  specified using the full path.

 SEE ALSO
  set_doc_files, get_doc_files, get_doc_string_from_file

--------------------------------------------------------------

_apropos

 SYNOPSIS
  Generate a list of functions and variables

 USAGE
  Array_Type _apropos (String_Type ns, String_Type s, Integer_Type flags)

 DESCRIPTION
  The `_apropos' function may be used to get a list of all defined
  objects in the namespace `ns' whose name matches the regular
  expression `s' and whose type matches those specified by
  `flags'.  It returns an array of strings containing the names
  matched.

  The third parameter `flags' is a bit mapped value whose bits
  are defined according to the following table

     1          Intrinsic Function
     2          User-defined Function
     4          Intrinsic Variable
     8          User-defined Variable


 EXAMPLE

    define apropos (s)
    {
      variable n, name, a;
      a = _apropos ("Global", s, 0xF);

      vmessage ("Found %d matches:", length (a));
      foreach name (a)
        message (name);
    }

  prints a list of all matches.

 NOTES
  If the namespace specifier `ns' is the empty string `""',
  then the namespace will default to the static namespace of the
  current compilation unit.

 SEE ALSO
  is_defined, sprintf, _get_namespaces

--------------------------------------------------------------

_function_name

 SYNOPSIS
  Returns the name of the currently executing function

 USAGE
  String_Type _function_name ()

 DESCRIPTION
  This function returns the name of the currently executing function.
  If called from top-level, it returns the empty string.

 SEE ALSO
  _trace_function, is_defined

--------------------------------------------------------------

__get_defined_symbols

 SYNOPSIS
  Get the symbols defined by the preprocessor

 USAGE
  Int_Type __get_defined_symbols ()

 DESCRIPTION
  The `__get_defined_symbols' functions is used to get the list of
  all the symbols defined by the S-Lang preprocessor.  It pushes each
  of the symbols on the stack followed by the number of items pushed.

 SEE ALSO
  is_defined, _apropos, _get_namespaces

--------------------------------------------------------------

get_doc_files

 SYNOPSIS
  Get the list of documentation files

 USAGE
  String_Type[] = get_doc_files ()

 DESCRIPTION
  The `get_doc_files' function returns the internal list of
  documentation files as an array of strings.

 SEE ALSO
  set_doc_files, add_doc_file, get_doc_string_from_file

--------------------------------------------------------------

get_doc_string_from_file

 SYNOPSIS
  Read documentation from a file

 USAGE
  String_Type get_doc_string_from_file ([String_Type f,] String_Type t)

 DESCRIPTION
  If called with two arguments, `get_doc_string_from_file' opens
  the documentation file `f' and searches it for topic `t'.
  Otherwise, it will search an internal list of documentation files
  looking for the documentation associated with the topic `t'.  If
  found, the documentation for `t' will be returned, otherwise the
  function will return NULL.

  Files may be added to the internal list via the `add_doc_file'
  or `set_doc_files' functions.

 SEE ALSO
  add_doc_file, set_doc_files, get_doc_files, _slang_doc_dir

--------------------------------------------------------------

_get_namespaces

 SYNOPSIS
  Returns a list of namespace names

 USAGE
  String_Type[] _get_namespaces ()

 DESCRIPTION
  This function returns a string array containing the names of the
  currently defined namespaces.

 SEE ALSO
  _apropos, use_namespace, implements, __get_defined_symbols

--------------------------------------------------------------

is_defined

 SYNOPSIS
  Determine if a variable or function is defined

 USAGE
  Integer_Type is_defined (String_Type name)

 DESCRIPTION
   This function is used to determine whether or not a function or
   variable of the given name has been defined.  If the specified name
   has not been defined, the function returns 0.  Otherwise, it
   returns a non-zero value that depends on the type of object
   attached to the name. Specifically, it returns one of the following
   values:

     +1     intrinsic function
     +2     slang function
     -1     intrinsic variable
     -2     slang variable
      0     undefined


 EXAMPLE
    Consider the function:

    define runhooks (hook)
    {
       if (2 == is_defined(hook)) eval(hook);
    }

    This function could be called from another S-Lang function to
    allow customization of that function, e.g., if the function
    represents a mode, the hook could be called to setup keybindings
    for the mode.

 SEE ALSO
  typeof, eval, autoload, __get_reference, __is_initialized

--------------------------------------------------------------

__is_initialized

 SYNOPSIS
  Determine whether or not a variable has a value

 USAGE
  Integer_Type __is_initialized (Ref_Type r)

 DESCRIPTION
   This function returns non-zero of the object referenced by `r'
   is initialized, i.e., whether it has a value.  It returns 0 if the
   referenced object has not been initialized.

 EXAMPLE
   The function:

    define zero ()
    {
       variable f;
       return __is_initialized (&f);
    }

  will always return zero, but

    define one ()
    {
       variable f = 0;
       return __is_initialized (&f);
    }

  will return one.

 SEE ALSO
  __get_reference, __uninitialize, is_defined, typeof, eval

--------------------------------------------------------------

_NARGS

 SYNOPSIS
  The number of parameters passed to a function

 USAGE
  Integer_Type _NARGS
   The value of the `_NARGS' variable represents the number of
   arguments passed to the function.  This variable is local to each
   function.

 EXAMPLE
   This example uses the `_NARGS' variable to print the list of
   values passed to the function:

     define print_values ()
     {
        variable arg;

        if (_NARGS == 0)
          {
             message ("Nothing to print");
             return;
          }
        foreach arg (__pop_args (_NARGS))
          vmessage ("Argument value is: %S", arg.value);
     }


 SEE ALSO
  __pop_args, __push_args, typeof

--------------------------------------------------------------

set_doc_files

 SYNOPSIS
  Set the internal list of documentation files

 USAGE
  set_doc_files (String_Type[] list)

 DESCRIPTION
  The `set_doc_files' function may be used to set the internal
  list of documentation files.  It takes a single parameter, which is
  required to be an array of strings.  The internal file list is set
  to the files specified by the elements of the array.

 EXAMPLE
  The following example shows how to add all the files in a specified
  directory to the internal list.  It makes use of the `glob'
  function that is distributed as part of `slsh'.

     files = glob ("/path/to/doc/files/*.sld");
     set_doc_files ([files, get_doc_files ()]);


 SEE ALSO
  get_doc_files, add_doc_file, get_doc_string_from_file

--------------------------------------------------------------

_slang_doc_dir

 SYNOPSIS
  Installed documentation directory

 USAGE
  String_Type _slang_doc_dir

 DESCRIPTION
   The `_slang_doc_dir' variable is a read-only variable that
   specifies the compile-time installation location of the S-Lang
   documentation.

 SEE ALSO
  get_doc_string_from_file

--------------------------------------------------------------

_slang_version

 SYNOPSIS
  The S-Lang library version number

 USAGE
  Integer_Type _slang_version

 DESCRIPTION
   `_slang_version' is a read-only variable that gives the version
   number of the S-Lang library.

 SEE ALSO
  _slang_version_string

--------------------------------------------------------------

_slang_version_string

 SYNOPSIS
  The S-Lang library version number as a string

 USAGE
  String_Type _slang_version_string

 DESCRIPTION
  `_slang_version_string' is a read-only variable that gives a
  string representation of the version number of the S-Lang library.

 SEE ALSO
  _slang_version

--------------------------------------------------------------

list_append

 SYNOPSIS
  Append an object to a list

 USAGE
  list_append (List_Type list, object [,Int_Type nth])

 DESCRIPTION
  The `list_append' function is like `list_insert' except
  this function appends the object to the list.  The optional
  argument `nth' may be used to specify where the object is to be
  appended.  See the documentation on `list_insert' for more details.

 SEE ALSO
  list_concat, list_insert, list_join, list_delete, list_pop, list_new, list_reverse

--------------------------------------------------------------

list_concat

 SYNOPSIS
  Concatenate two lists to form a third

 USAGE
  List_Type = list_concat (List_Type a, List_Type b)

 DESCRIPTION
  This function creates a new list that is formed by concatenating the
  two lists `a' and `b' together.  Neither of the input
  lists are modified by this operation.

 SEE ALSO
  list_join, list_append, list_insert

--------------------------------------------------------------

list_delete

 SYNOPSIS
  Remove an item from a list

 USAGE
  list_delete (List_Type list, Int_Type nth)

 DESCRIPTION
  This function removes the `nth' item in the specified list.
  The first item in the list corresponds to a value of `nth'
  equal to zero.  If `nth' is negative, then the indexing is with
  respect to the end of the list with the last item corresponding to
  `nth' equal to -1.

 SEE ALSO
  list_insert, list_append, list_pop, list_new, list_reverse

--------------------------------------------------------------

list_insert

 SYNOPSIS
  Insert an item into a list

 USAGE
  list_insert (List_Type list, object [,Int_Type nth])

 DESCRIPTION
  This function may be used to insert an object into the specified
  list.  With just two arguments, the object will be inserted at the
  beginning of the list.  The optional third argument, `nth', may
  be used to specify the insertion point.  The first item in the list
  corresponds to a value of `nth' equal to zero.  If `nth'
  is negative, then the indexing is with respect to the end of the
  list with the last item given by a value of `nth' equal to -1.

 NOTES
  It is important to note that

    list_insert (list, object, 0);

  is not the same as

    list = {object, list}

  since the latter creates a new list with two items, `object'
  and the old list.

 SEE ALSO
  list_append, list_pop, list_delete, list_new, list_reverse

--------------------------------------------------------------

list_join

 SYNOPSIS
  Join the elements of a second list onto the end of the first

 USAGE
  list_join (List_Type a, List_Type b)

 DESCRIPTION
  This function modifies the list `a' by appending the elements
  of `b' to it.

 SEE ALSO
  list_concat, list_append, list_insert

--------------------------------------------------------------

list_new

 SYNOPSIS
  Create a new list

 USAGE
  List_Type list_new ()

 DESCRIPTION
  This function creates a new empty List_Type object.  Such a
  list may also be created using the syntax

     list = {};


 SEE ALSO
  list_delete, list_insert, list_append, list_reverse, list_pop

--------------------------------------------------------------

list_pop

 SYNOPSIS
  Extract an item from a list

 USAGE
  object = list_pop (List_Type list [, Int_Type nth])

 DESCRIPTION
  The `list_pop' function returns a object from a list deleting
  the item from the list in the process.  If the second argument is
  present, then it may be used to specify the position in the list
  where the item is to be obtained.  If called with a single argument,
  the first item in the list will be used.

 SEE ALSO
  list_delete, list_insert, list_append, list_reverse, list_new

--------------------------------------------------------------

list_reverse

 SYNOPSIS
  Reverse a list

 USAGE
  list_reverse (List_Type list)

 DESCRIPTION
  This function may be used to reverse the items in list.

 NOTES
  This function does not create a new list.  The list passed to the
  function will be reversed upon return from the function.  If it is
  desired to create a separate reversed list, then a separate copy
  should be made, e.g.,

     rev_list = @list;
     list_reverse (rev_list);


 SEE ALSO
  list_new, list_insert, list_append, list_delete, list_pop

--------------------------------------------------------------

list_to_array

 SYNOPSIS
  Convert a list into an array

 USAGE
  Array_Type list_to_array (List_Type list [,DataType_Type type])

 DESCRIPTION
 The `list_to_array' function converts a list of objects into an
 array of the same length and returns the result.  The optional
 argument may be used to specify the array's data type.  If no
 `type' is given, `list_to_array' tries to find the common
 data type of all list elements. This function will generate an
 exception if the list is empty and no type has been specified, or the
 objects in the list cannot be converted to a common type.

 NOTES
 A future version of this function may produce an Any_Type
 array for an empty or heterogeneous list.

 SEE ALSO
  length, typecast, __pop_list, typeof, array_sort

--------------------------------------------------------------

abs

 SYNOPSIS
  Compute the absolute value of a number

 USAGE
  y = abs(x)

 DESCRIPTION
  The `abs' function returns the absolute value of an arithmetic
  type.  If its argument is a complex number (Complex_Type),
  then it returns the modulus.  If the argument is an array, a new
  array will be created whose elements are obtained from the original
  array by using the `abs' function.

 SEE ALSO
  sign, sqr

--------------------------------------------------------------

acos

 SYNOPSIS
  Compute the arc-cosine of a number

 USAGE
  y = acos (x)

 DESCRIPTION
  The `acos' function computes the arc-cosine of a number and
  returns the result.  If its argument is an array, the
  `acos' function will be applied to each element and the result returned
  as an array.

 SEE ALSO
  cos, atan, acosh, cosh

--------------------------------------------------------------

acosh

 SYNOPSIS
  Compute the inverse cosh of a number

 USAGE
  y = acosh (x)

 DESCRIPTION
  The `acosh' function computes the inverse hyperbolic cosine of a number and
  returns the result.  If its argument is an array, the
  `acosh' function will be applied to each element and the result returned
  as an array.

 SEE ALSO
  cos, atan, acosh, cosh

--------------------------------------------------------------

asin

 SYNOPSIS
  Compute the arc-sine of a number

 USAGE
  y = asin (x)

 DESCRIPTION
  The `asin' function computes the arc-sine of a number and
  returns the result.  If its argument is an array, the
  `asin' function will be applied to each element and the result returned
  as an array.

 SEE ALSO
  cos, atan, acosh, cosh

--------------------------------------------------------------

asinh

 SYNOPSIS
  Compute the inverse-sinh of a number

 USAGE
  y = asinh (x)

 DESCRIPTION
  The `asinh' function computes the inverse hyperbolic sine of a number and
  returns the result.  If its argument is an array, the
  `asinh' function will be applied to each element and the result returned
  as an array.

 SEE ALSO
  cos, atan, acosh, cosh

--------------------------------------------------------------

atan

 SYNOPSIS
  Compute the arc-tangent of a number

 USAGE
  y = atan (x)

 DESCRIPTION
  The `atan' function computes the arc-tangent of a number and
  returns the result.  If its argument is an array, the
  `atan' function will be applied to each element and the result returned
  as an array.

 SEE ALSO
  atan2, cos, acosh, cosh

--------------------------------------------------------------

atan2

 SYNOPSIS
  Compute the arc-tangent of the ratio of two variables

 USAGE
  z = atan2 (y, x)

 DESCRIPTION
  The `atan2' function computes the arc-tangent of the ratio
  `y/x' and returns the result as a value that has the
  proper sign for the quadrant where the point (x,y) is located.  The
  returned value `z' will satisfy (-PI < z <= PI).  If either of the
  arguments is an array, an array of the corresponding values will be returned.

 SEE ALSO
  hypot, cos, atan, acosh, cosh

--------------------------------------------------------------

atanh

 SYNOPSIS
  Compute the inverse-tanh of a number

 USAGE
  y = atanh (x)

 DESCRIPTION
  The `atanh' function computes the inverse hyperbolic tangent of a number and
  returns the result.  If its argument is an array, the
  `atanh' function will be applied to each element and the result returned
  as an array.

 SEE ALSO
  cos, atan, acosh, cosh

--------------------------------------------------------------

ceil

 SYNOPSIS
  Round x up to the nearest integral value

 USAGE
  y = ceil (x)

 DESCRIPTION
  This function rounds its numeric argument up to the nearest integral
  value. If the argument is an array, the corresponding array will be
  returned.

 SEE ALSO
  floor, round

--------------------------------------------------------------

Conj

 SYNOPSIS
  Compute the complex conjugate of a number

 USAGE
  z1 = Conj (z)

 DESCRIPTION
  The `Conj' function returns the complex conjugate of a number.
  If its argument is an array, the `Conj' function will be applied to each
  element and the result returned as an array.

 SEE ALSO
  Real, Imag, abs

--------------------------------------------------------------

cos

 SYNOPSIS
  Compute the cosine of a number

 USAGE
  y = cos (x)

 DESCRIPTION
  The `cos' function computes the cosine of a number and
  returns the result.  If its argument is an array, the
  `cos' function will be applied to each element and the result returned
  as an array.

 SEE ALSO
  cos, atan, acosh, cosh

--------------------------------------------------------------

cosh

 SYNOPSIS
  Compute the hyperbolic cosine of a number

 USAGE
  y = cosh (x)

 DESCRIPTION
  The `cosh' function computes the hyperbolic cosine of a number and
  returns the result.  If its argument is an array, the
  `cosh' function will be applied to each element and the result returned
  as an array.

 SEE ALSO
  cos, atan, acosh, cosh

--------------------------------------------------------------

_diff

 SYNOPSIS
  Compute the absolute difference of two values

 USAGE
  y = _diff (x, y)

 DESCRIPTION
  The `_diff' function returns a floating point number equal to
  the absolute value of the difference of its two arguments.
  If either argument is an array, an array of the corresponding values
  will be returned.

 SEE ALSO
  abs

--------------------------------------------------------------

exp

 SYNOPSIS
  Compute the exponential of a number

 USAGE
  y = exp (x)

 DESCRIPTION
  The `exp' function computes the exponential of a number and
  returns the result.  If its argument is an array, the
  `exp' function will be applied to each element and the result returned
  as an array.

 SEE ALSO
  expm1, cos, atan, acosh, cosh

--------------------------------------------------------------

expm1

 SYNOPSIS
  Compute exp(x)-1

 USAGE
  y = expm1(x)

 DESCRIPTION
  The `expm1' function computes `exp(x)-1' and returns the
  result.  If its argument is an array, the `expm1' function will
  be applied to each element and the results returned as an array.

  This function should be called whenever `x' is close to 0 to
  avoid the numerical error that would arise in a naive computation of
  `exp(x)-1'.

 SEE ALSO
  expm1, log1p, cos, atan, acosh, cosh

--------------------------------------------------------------

feqs

 SYNOPSIS
  Test the approximate equality of two numbers

 USAGE
  Char_Type feqs (a, b [,reldiff [,absdiff]]

 DESCRIPTION
 This function compares two floating point numbers `a' and
 `b', and returns a non-zero value if they are equal to within a
 specified tolerance; otherwise 0 will be returned.  If either is an
 array, a corresponding boolean array will be returned.

 The tolerances are specified as relative and absolute differences via
 the optional third and fourth arguments.  If no optional arguments
 are present, the tolerances default to `reldiff=0.01' and
 `absdiff=1e-6'.  If only the relative difference has been
 specified, the absolute difference (`absdiff') will be taken to
 be 0.0.

 For the case when `|b|>=|a|', `a' and `b' are
 considered to be equal to within the specified tolerances if either
 `|b-a|<=absdiff' or `|b-a|/|b|<=reldiff' is true.

 SEE ALSO
  fneqs, fgteqs, flteqs

--------------------------------------------------------------

fgteqs

 SYNOPSIS
  Compare two numbers using specified tolerances
.

 USAGE
  Char_Type feqs (a, b [,reldiff [,absdiff]]

 DESCRIPTION
  This function is functionally equivalent to:

     (a >= b) or feqs(a,b,...)

  See the documentation of `feqs' for more information.

 SEE ALSO
  feqs, fneqs, flteqs

--------------------------------------------------------------

floor

 SYNOPSIS
  Round x down to the nearest integer

 USAGE
  y = floor (x)

 DESCRIPTION
  This function rounds its numeric argument down to the nearest
  integral value. If the argument is an array, the corresponding array
  will be returned.

 SEE ALSO
  ceil, round, nint

--------------------------------------------------------------

flteqs

 SYNOPSIS
  Compare two numbers using specified tolerances
.

 USAGE
  Char_Type feqs (a, b [,reldiff [,absdiff]]

 DESCRIPTION
  This function is functionally equivalent to:

     (a <= b) or feqs(a,b,...)

  See the documentation of `feqs' for more information.

 SEE ALSO
  feqs, fneqs, fgteqs

--------------------------------------------------------------

fneqs

 SYNOPSIS
  Test the approximate inequality of two numbers

 USAGE
  Char_Type feqs (a, b [,reldiff [,absdiff]]

 DESCRIPTION
  This function is functionally equivalent to:

    not fneqs(a,b,...)

  See the documentation of `feqs' for more information.

 SEE ALSO
  feqs, fgteqs, flteqs

--------------------------------------------------------------

get_float_format

 SYNOPSIS
  Get the format for printing floating point values.

 USAGE
  String_Type get_float_format ()

 DESCRIPTION
 The `get_float_format' retrieves the format string used for
 printing single and double precision floating point numbers.  See the
 documentation for the `set_float_format' function for more
 information about the format.

 SEE ALSO
  set_float_format

--------------------------------------------------------------

hypot

 SYNOPSIS
  Compute sqrt(x1^2+x2^2+...+xN^2)

 USAGE
  r = hypot (x1 [,x2,..,xN])

 DESCRIPTION
  If given two or more arguments, `x1,...,xN', the `hypot'
  function computes the quantity `sqrt(x1^2+...+xN^2)' using an
  algorithm that tries to avoid arithmetic overflow.  If any of the
  arguments is an array, an array of the corresponding values will be
  returned.

  If given a single array argument `x', the `hypot' function
  computes `sqrt(sumsq(x))', where `sumsq(x)' computes
  the sum of the squares of the elements of `x'.

 EXAMPLE
  A vector in Euclidean 3 dimensional space may be represented by an
  array of three values representing the components of the vector in
  some orthogonal cartesian coordinate system.  Then the length of the
  vector may be computed using the `hypot' function, e.g.,

      A = [2,3,4];
      len_A = hypot (A);

  The dot-product or scalar-product between two such vectors `A'
  and `B' may be computed using the `sum(A*B)'.  It is well
  known that this is also equal to the product of the lengths of the
  two vectors and the cosine of the angle between them.  Hence, the
  angle between the vectors `A' and `B' may be computed using

      ahat = A/hypot(A);
      bhat = B/hypot(B);
      theta = acos(\sum(ahat*bhat));

  Here, `ahat' and `bhat' are the unit vectors associated
  with the vectors `A' and `B', respectively.
  Unfortunately, the above method for computing the angle between the
  vectors is numerically unstable when `A' and `B' are
  nearly parallel.  An alternative method is to use:

      ahat = A/hypot(A);
      bhat = B/hypot(B);
      ab = sum(ahat*bhat);
      theta = atan2 (hypot(bhat - ab*ahat), ab);


 SEE ALSO
  atan2, cos, atan, acosh, cosh, sum, sumsq

--------------------------------------------------------------

Imag

 SYNOPSIS
  Compute the imaginary part of a number

 USAGE
  i = Imag (z)

 DESCRIPTION
  The `Imag' function returns the imaginary part of a number.
  If its argument is an array, the `Imag' function will be applied to each
  element and the result returned as an array.

 SEE ALSO
  Real, Conj, abs

--------------------------------------------------------------

isinf

 SYNOPSIS
  Test for infinity

 USAGE
  y = isinf (x)

 DESCRIPTION
  This function returns 1 if x corresponds to an IEEE infinity, or 0
  otherwise. If the argument is an array, an array of the
  corresponding values will be returned.

 SEE ALSO
  isnan, _Inf

--------------------------------------------------------------

isnan

 SYNOPSIS
  isnan

 USAGE
  y = isnan (x)

 DESCRIPTION
  This function returns 1 if x corresponds to an IEEE NaN (Not a Number),
  or 0 otherwise.  If the argument is an array, an array of
  the corresponding values will be returned.

 SEE ALSO
  isinf, _NaN

--------------------------------------------------------------

log

 SYNOPSIS
  Compute the logarithm of a number

 USAGE
  y = log (x)

 DESCRIPTION
  The `log' function computes the natural logarithm of a number and
  returns the result.  If its argument is an array, the
  `log' function will be applied to each element and the result returned
  as an array.

 SEE ALSO
  cos, atan, acosh, cosh, log1p

--------------------------------------------------------------

log10

 SYNOPSIS
  Compute the base-10 logarithm of a number

 USAGE
  y = log10 (x)

 DESCRIPTION
  The `log10' function computes the base-10 logarithm of a number and
  returns the result.  If its argument is an array, the
  `log10' function will be applied to each element and the result returned
  as an array.

 SEE ALSO
  cos, atan, acosh, cosh

--------------------------------------------------------------

log1p

 SYNOPSIS
  Compute the logarithm of 1 plus a number

 USAGE
  y = log1p (x)

 DESCRIPTION
  The `log1p' function computes the natural logarithm of 1.0 plus
  `x' returns the result.  If its argument is an array, the
  `log1p' function will be applied to each element and the results
  returned as an array.

  This function should be used instead of `log(1+x)' to avoid
  numerical errors whenever `x' is close to 0.

 SEE ALSO
  log, expm1, cos, atan, acosh, cosh

--------------------------------------------------------------

_max

 SYNOPSIS
  Compute the maximum of two or more numeric values

 USAGE
  z = _max (x1,...,xN)

 DESCRIPTION
  The `_max' function returns a floating point number equal to
  the maximum value of its arguments.  If any of the argiments are
  arrays (of equal length), an array of the corresponding values will
  be returned.

 NOTES
  This function returns a floating point result even when the
  arguments are integers.

 SEE ALSO
  _min, min, max

--------------------------------------------------------------

_min

 SYNOPSIS
  Compute the minimum of two or more numeric values

 USAGE
  z = _min (x1,...,xN)

 DESCRIPTION
  The `_min' function returns a floating point number equal to
  the minimum value of its arguments.  If any of the argiments are
  arrays (of equal length), an array of the corresponding values will
  be returned.

 NOTES
  This function returns a floating point result even when the
  arguments are integers.

 SEE ALSO
  min, _max, max

--------------------------------------------------------------

mul2

 SYNOPSIS
  Multiply a number by 2

 USAGE
  y = mul2(x)

 DESCRIPTION
  The `mul2' function multiplies an arithmetic type by two and
  returns the result.  If its argument is an array, a new array will
  be created whose elements are obtained from the original array by
  using the `mul2' function.

 SEE ALSO
  sqr, abs

--------------------------------------------------------------

nint

 SYNOPSIS
  Round to the nearest integer

 USAGE
  i = nint(x)

 DESCRIPTION
  The `nint' rounds its argument to the nearest integer and
  returns the result.  If its argument is an array, a new array will
  be created whose elements are obtained from the original array
  elements by using the `nint' function.

 SEE ALSO
  round, floor, ceil

--------------------------------------------------------------

polynom

 SYNOPSIS
  Evaluate a polynomial

 USAGE
  Double_Type polynom([a0,a1,...aN], x [,use_factorial])

 DESCRIPTION
 The `polynom' function returns the value of the polynomial expression

     a0 + a1*x + a2*x^2 + ... + aN*x^N

 where the coefficients are given by an array of values
 `[a0,...,aN]'.  If `x' is an array, the function will
 return a corresponding array.  If the value of the optional
 `use_factorial' parameter is non-zero, then each term in the sum
 will be normalized by the corresponding factorial, i.e.,

     a0/0! + a1*x/1! + a2*x^2/2! + ... + aN*x^N/N!


 NOTES
  Prior to version 2.2, this function had a different calling syntax
  and and was less useful.

  The `polynom' function does not yet support complex-valued
  coefficients.

  For the case of a scalar value of `x' and a small degree
  polynomial, it is more efficient to use an explicit expression.

 SEE ALSO
  exp

--------------------------------------------------------------

Real

 SYNOPSIS
  Compute the real part of a number

 USAGE
  r = Real (z)

 DESCRIPTION
  The `Real' function returns the real part of a number. If its
  argument is an array, the `Real' function will be applied to
  each element and the result returned as an array.

 SEE ALSO
  Imag, Conj, abs

--------------------------------------------------------------

round

 SYNOPSIS
  Round to the nearest integral value

 USAGE
  y = round (x)

 DESCRIPTION
  This function rounds its argument to the nearest integral value and
  returns it as a floating point result. If the argument is an array,
  an array of the corresponding values will be returned.

 SEE ALSO
  floor, ceil, nint

--------------------------------------------------------------

set_float_format

 SYNOPSIS
  Set the format for printing floating point values.

 USAGE
  set_float_format (String_Type fmt)

 DESCRIPTION
  The `set_float_format' function is used to set the floating
  point format to be used when floating point numbers are printed.
  The routines that use this are the traceback routines and the
  `string' function, any anything based upon the `string'
  function. The default value is `"%S"', which causes the number
  to be displayed with enough significant digits such that
  `x==atof(string(x))'.

 EXAMPLE

     set_float_format ("%S");        % default
     s = string (PI);                %  --> s = "3.141592653589793"
     set_float_format ("%16.10f");
     s = string (PI);                %  --> s = "3.1415926536"
     set_float_format ("%10.6e");
     s = string (PI);                %  --> s = "3.141593e+00"


 SEE ALSO
  get_float_format, string, sprintf, atof, double

--------------------------------------------------------------

sign

 SYNOPSIS
  Compute the sign of a number

 USAGE
  y = sign(x)

 DESCRIPTION
  The `sign' function returns the sign of an arithmetic type.  If
  its argument is a complex number (Complex_Type), the
  `sign' will be applied to the imaginary part of the number.  If
  the argument is an array, a new array will be created whose elements
  are obtained from the original array by using the `sign'
  function.

  When applied to a real number or an integer, the `sign' function
  returns -1, 0, or `+1' according to whether the number is
  less than zero, equal to zero, or greater than zero, respectively.

 SEE ALSO
  abs

--------------------------------------------------------------

sin

 SYNOPSIS
  Compute the sine of a number

 USAGE
  y = sin (x)

 DESCRIPTION
  The `sin' function computes the sine of a number and
  returns the result.  If its argument is an array, the
  `sin' function will be applied to each element and the result returned
  as an array.

 SEE ALSO
  cos, atan, acosh, cosh

--------------------------------------------------------------

sinh

 SYNOPSIS
  Compute the hyperbolic sine of a number

 USAGE
  y = sinh (x)

 DESCRIPTION
  The `sinh' function computes the hyperbolic sine of a number and
  returns the result.  If its argument is an array, the
  `sinh' function will be applied to each element and the result returned
  as an array.

 SEE ALSO
  cos, atan, acosh, cosh

--------------------------------------------------------------

sqr

 SYNOPSIS
  Compute the square of a number

 USAGE
  y = sqr(x)

 DESCRIPTION
  The `sqr' function returns the square of an arithmetic type.  If its
  argument is a complex number (Complex_Type), then it returns
  the square of the modulus.  If the argument is an array, a new array
  will be created whose elements are obtained from the original array
  by using the `sqr' function.

 NOTES
  For real scalar numbers, using `x*x' instead of `sqr(x)'
  will result in faster executing code.  However, if `x' is an
  array, then `sqr(x)' will execute faster.

 SEE ALSO
  abs, mul2

--------------------------------------------------------------

sqrt

 SYNOPSIS
  Compute the square root of a number

 USAGE
  y = sqrt (x)

 DESCRIPTION
  The `sqrt' function computes the square root of a number and
  returns the result.  If its argument is an array, the
  `sqrt' function will be applied to each element and the result returned
  as an array.

 SEE ALSO
  sqr, cos, atan, acosh, cosh

--------------------------------------------------------------

tan

 SYNOPSIS
  Compute the tangent of a number

 USAGE
  y = tan (x)

 DESCRIPTION
  The `tan' function computes the tangent of a number and
  returns the result.  If its argument is an array, the
  `tan' function will be applied to each element and the result returned
  as an array.

 SEE ALSO
  cos, atan, acosh, cosh

--------------------------------------------------------------

tanh

 SYNOPSIS
  Compute the hyperbolic tangent of a number

 USAGE
  y = tanh (x)

 DESCRIPTION
  The `tanh' function computes the hyperbolic tangent of a number and
  returns the result.  If its argument is an array, the
  `tanh' function will be applied to each element and the result returned
  as an array.

 SEE ALSO
  cos, atan, acosh, cosh

--------------------------------------------------------------

_ispos

 SYNOPSIS
  Test if a number is greater than 0

 USAGE
  Char_Type _ispos(x)

 DESCRIPTION
  This function returns 1 if a number is greater than 0, and zero
  otherwise.  If the argument is an array, then the corresponding
  array of boolean (Char_Type) values will be returned.

 SEE ALSO
  _isneg, _isnonneg

--------------------------------------------------------------

_isneg

 SYNOPSIS
  Test if a number is less than 0

 USAGE
  Char_Type _isneg(x)

 DESCRIPTION
  This function returns 1 if a number is less than 0, and zero
  otherwise.  If the argument is an array, then the corresponding
  array of boolean (Char_Type) values will be returned.

 SEE ALSO
  _ispos, _isnonneg

--------------------------------------------------------------

_isnonneg

 SYNOPSIS
  Test if a number is greater than or equal to 0

 USAGE
  Char_Type _isnonneg(x)

 DESCRIPTION
  This function returns 1 if a number is greater or equal to 0, and zero
  otherwise.  If the argument is an array, then the corresponding
  array of boolean (Char_Type) values will be returned.

 SEE ALSO
  _isneg, _isnonneg

--------------------------------------------------------------

errno

 SYNOPSIS
  Error code set by system functions

 USAGE
  Int_Type errno

 DESCRIPTION
  A system function can fail for a variety of reasons.  For example, a
  file operation may fail because lack of disk space, or the process
  does not have permission to perform the operation.  Such functions
  will return -1 and set the variable `errno' to an error
  code describing the reason for failure.

  Particular values of `errno' may be specified by the following
  symbolic constants (read-only variables) and the corresponding
  `errno_string' value:

     E2BIG            "Arg list too long"
     EACCES           "Permission denied"
     EBADF            "Bad file number"
     EBUSY            "Mount device busy"
     ECHILD           "No children"
     EEXIST           "File exists"
     EFAULT           "Bad address"
     EFBIG            "File too large"
     EINTR            "Interrupted system call"
     EINVAL           "Invalid argument"
     EIO              "I/O error"
     EISDIR           "Is a directory"
     ELOOP            "Too many levels of symbolic links"
     EMFILE           "Too many open files"
     EMLINK           "Too many links"
     ENAMETOOLONG     "File name too long"
     ENFILE           "File table overflow"
     ENODEV           "No such device"
     ENOENT           "No such file or directory"
     ENOEXEC          "Exec format error"
     ENOMEM           "Not enough core"
     ENOSPC           "No space left on device"
     ENOTBLK          "Block device required"
     ENOTDIR          "Not a directory"
     ENOTEMPTY        "Directory not empty"
     ENOTTY           "Not a typewriter"
     ENXIO            "No such device or address"
     EPERM            "Operation not permitted"
     EPIPE            "Broken pipe"
     EROFS            "Read-only file system"
     ESPIPE           "Illegal seek"
     ESRCH            "No such process"
     ETXTBSY          "Text file busy"
     EXDEV            "Cross-device link"


 EXAMPLE
  The `mkdir' function will attempt to create a directory.  If it
  fails, the function will throw an IOError exception with a message
  containing the string representation of the `errno' value.

    if (-1 == mkdir (dir))
       throw IOError, sprintf ("mkdir %s failed: %s",
                               dir, errno_string (errno));


 SEE ALSO
  errno_string, error, mkdir

--------------------------------------------------------------

errno_string

 SYNOPSIS
  Return a string describing an errno.

 USAGE
  String_Type errno_string ( [Int_Type err ])

 DESCRIPTION
  The `errno_string' function returns a string describing the
  integer errno code `err'.  If the `err' parameter is
  omitted, the current value of `errno' will be used. See the
  description for `errno' for more information.

 EXAMPLE
  The `errno_string' function may be used as follows:

    define sizeof_file (file)
    {
       variable st = stat_file (file);
       if (st == NULL)
         throw IOError, sprintf ("%s: %s", file, errno_string (errno));
       return st.st_size;
    }


 SEE ALSO
  errno, stat_file

--------------------------------------------------------------

error

 SYNOPSIS
  Generate an error condition (deprecated)

 USAGE
  error (String_Type msg)

 DESCRIPTION
  This function has been deprecated in favor of `throw'.

  The `error' function generates a S-Lang `RunTimeError'
  exception. It takes a single string parameter which is displayed on
  the stderr output device.

 EXAMPLE

    define add_txt_extension (file)
    {
       if (typeof (file) != String_Type)
         error ("add_extension: parameter must be a string");
       file += ".txt";
       return file;
    }


 SEE ALSO
  verror, message

--------------------------------------------------------------

__get_exception_info

 SYNOPSIS
  Get information about the current exception

 USAGE
  Struct_Type __get_exception_info ()

 DESCRIPTION
 This function returns information about the currently active
 exception in the form as a structure with the
 following fields:

    error            The current exception, e.g., RunTimeError
    descr            A description of the exception
    file             Name of the file generating the exception
    line             Line number where the exception originated
    function         Function where the exception originated
    object           A user-defined object thrown by the exception
    message          A user-defined message
    traceback        Traceback messages

 If no exception is active, NULL will be returned.

 This same information may also be obtained via the optional argument
 to the `try' statement:

     variable e = NULL;
     try (e)
       {
          do_something ();
       }
     finally
       {
          if (e != NULL)
            vmessage ("An error occurred: %s", e.message);
       }


 SEE ALSO
  error

--------------------------------------------------------------

message

 SYNOPSIS
  Print a string onto the message device

 USAGE
  message (String_Type s)

 DESCRIPTION
  The `message' function will print the string specified by
  `s' onto the message device.

 EXAMPLE

     define print_current_time ()
     {
       message (time ());
     }


 NOTES
  The message device will depend upon the application.  For example,
  the output message device for the jed editor corresponds to the
  line at the bottom of the display window.  The default message
  device is the standard output device.

 SEE ALSO
  vmessage, sprintf, error

--------------------------------------------------------------

new_exception

 SYNOPSIS
  Create a new exception

 USAGE
  new_exception (String_Type name, Int_Type baseclass, String_Type descr)

 DESCRIPTION
  This function creates a new exception called `name' subclassed
  upon `baseclass'.  The description of the exception is
  specified by `descr'.

 EXAMPLE

  new_exception ("MyError", RunTimeError, "My very own error");
  try
    {
       if (something_is_wrong ())
         throw MyError;
    }
  catch RunTimeError;

  In this case, catching `RunTimeError' will also catch
  `MyError' since it is a subclass of `RunTimeError'.

 SEE ALSO
  error, verror

--------------------------------------------------------------

usage

 SYNOPSIS
  Generate a usage error

 USAGE
  usage (String_Type msg)

 DESCRIPTION
  The `usage' function generates a `UsageError' exception and
  displays `msg' to the message device.

 EXAMPLE
  Suppose that a function called `plot' plots an array of `x' and
  `y' values.  Then such a function could be written to issue a
  usage message if the wrong number of arguments was passed:

    define plot ()
    {
       variable x, y;

       if (_NARGS != 2)
         usage ("plot (x, y)");

       (x, y) = ();
       % Now do the hard part
          .
          .
    }


 SEE ALSO
  error, message

--------------------------------------------------------------

verror

 SYNOPSIS
  Generate an error condition (deprecated)

 USAGE
  verror (String_Type fmt, ...)

 DESCRIPTION
  This function has been deprecated in favor or `throw'.

  The `verror' function performs the same role as the `error'
  function.  The only difference is that instead of a single string
  argument, `verror' takes a sprintf style argument list.

 EXAMPLE

    define open_file (file)
    {
       variable fp;

       fp = fopen (file, "r");
       if (fp == NULL) verror ("Unable to open %s", file);
       return fp;
    }


 NOTES
  In the current implementation, the `verror' function is not an
  intrinsic function.  Rather it is a predefined S-Lang function using
  a combination of `sprintf' and `error'.

  To generate a specific exception, a `throw' statement should be
  used.  In fact, a `throw' statement such as:

     if (fp == NULL)
       throw OpenError, "Unable to open $file"$;

  is preferable to the use of `verror' in the above example.

 SEE ALSO
  error, Sprintf, vmessage

--------------------------------------------------------------

vmessage

 SYNOPSIS
  Print a formatted string onto the message device

 USAGE
  vmessage (String_Type fmt, ...)

 DESCRIPTION
  The `vmessage' function formats a sprintf style argument list
  and displays the resulting string onto the message device.

 NOTES
  In the current implementation, the `vmessage' function is not an
  intrinsic function.  Rather it is a predefined S-Lang function using
  a combination of `Sprintf' and `message'.

 SEE ALSO
  message, sprintf, Sprintf, verror

--------------------------------------------------------------

_auto_declare

 SYNOPSIS
  Set automatic variable declaration mode

 USAGE
  Integer_Type _auto_declare

 DESCRIPTION
  The `_auto_declare' variable may be used to have undefined
  variable implicitly declared.  If set to zero, any
  variable must be declared with a `variable' declaration before it
  can be used.  If set to one, then any undeclared variable will be
  declared as a `static' variable.

  The `_auto_declare' variable is local to each compilation unit and
  setting its value in one unit has no effect upon its value in other
  units.   The value of this variable has no effect upon the variables
  in a function.

 EXAMPLE
  The following code will not compile if `X' not been
  declared:

    X = 1;

  However,

    _auto_declare = 1;   % declare variables as static.
    X = 1;

  is equivalent to

    static variable X = 1;


 NOTES
  This variable should be used sparingly and is intended primarily for
  interactive applications where one types S-Lang commands at a
  prompt.

--------------------------------------------------------------

__class_id

 SYNOPSIS
  Return the class-id of a specified type

 USAGE
  Int_Type __class_id (DataType_Type type)

 DESCRIPTION
  This function returns the internal class-id of a specified data type.

 SEE ALSO
  typeof, _typeof, __class_type, __datatype

--------------------------------------------------------------

__class_type

 SYNOPSIS
  Return the class-type of a specified type

 USAGE
  Int_Type __class_type (DataType_Type type))

 DESCRIPTION
  Internally S-Lang objects are classified according to four types:
  scalar, vector, pointer, and memory managed types.  For example, an
  integer is implemented as a scalar, a complex number as a vector,
  and a string is represented as a pointer.  The `__class_type'
  function returns an integer representing the class-type associated
  with the specified data type. Specifically, it returns:

       0    memory-managed
       1    scalar
       2    vector
       3    pointer


 SEE ALSO
  typeof, _typeof, __class_id, __datatype

--------------------------------------------------------------

current_namespace

 SYNOPSIS
  Get the name of the current namespace

 USAGE
  String_Type current_namespace ()

 DESCRIPTION
   The `current_namespace' function returns the name of the
   static namespace associated with the compilation unit.  If there is
   no such namespace associated with the compilation unit, then the
   empty string `""' will be returned.

 SEE ALSO
  implements, use_namespace, import, evalfile

--------------------------------------------------------------

__datatype

 SYNOPSIS
  Get the DataType_Type for a specified internal class-id

 USAGE
  DataType_Type __datatype (Int_Type id)

 DESCRIPTION
 This function is the inverse of __class_type in the sense that it
 returns the DataType_Type for the specified class-id.  If no
 such class exists, the function will return NULL.

 NOTES
 One should not expect distinct interpreter instances to always return
 the same value for a dynamically assigned class-id such as one
 defined by a module or one stemming from a `typedef' statement.

 SEE ALSO
  __class_id, __class_type, typeof

--------------------------------------------------------------

_eqs

 SYNOPSIS
  Test for equality of two objects

 USAGE
  Int_Type _eqs (a, b)

 DESCRIPTION
  This function tests its two arguments for equality and returns 1 if
  they are equal or 0 otherwise. What it means to be equal depends
  upon the data types of the objects being compared.  If the types are
  numeric, they are regarded as equal if their numerical values are
  equal.  If they are arrays, then they are equal if they have the
  same shape with equal elements. If they are structures, then they
  are equal if they contain identical fields, and the corresponding
  values are equal.

 EXAMPLE
   _eqs (1, 1)             ===> 1
   _eqs (1, 1.0)           ===> 1
   _eqs ("a", 1)           ===> 0
   _eqs ([1,2], [1.0,2.0]) ===> 1

 SEE ALSO
  typeof, _eqs, __get_reference, __is_callable

 NOTES
   For testing sameness, use `__is_same'.

--------------------------------------------------------------

getenv

 SYNOPSIS
  Get the value of an environment variable

 USAGE
  String_Type getenv(String_Type var)

 DESCRIPTION
   The `getenv' function returns a string that represents the
   value of an environment variable `var'.  It will return
   NULL if there is no environment variable whose name is given
   by `var'.

 EXAMPLE

    if (NULL != getenv ("USE_COLOR"))
      {
        set_color ("normal", "white", "blue");
        set_color ("status", "black", "gray");
        USE_ANSI_COLORS = 1;
      }


 SEE ALSO
  putenv, strlen, is_defined

--------------------------------------------------------------

__get_reference

 SYNOPSIS
  Get a reference to a global object

 USAGE
  Ref_Type __get_reference (String_Type nm)

 DESCRIPTION
  This function returns a reference to a global variable or function
  whose name is specified by `nm'.  If no such object exists, it
  returns NULL, otherwise it returns a reference.

 EXAMPLE
   Consider the function:

    define runhooks (hook)
    {
       variable f;
       f = __get_reference (hook);
       if (f != NULL)
         @f ();
    }

   This function could be called from another S-Lang function to allow
   customization of that function, e.g., if the function represents a
   jed editor mode, the hook could be called to setup keybindings for
   the mode.

 SEE ALSO
  is_defined, typeof, eval, autoload, __is_initialized, __uninitialize

--------------------------------------------------------------

implements

 SYNOPSIS
  Create a new static namespace

 USAGE
  implements (String_Type name)

 DESCRIPTION
  The `implements' function may be used to create a new static
  namespace and have it associated with the current compilation unit.
  If a namespace with the specified name already exists, a
  `NamespaceError' exception will be thrown.

  In addition to creating a new static namespace and associating it
  with the compilation unit, the function will also create a new
  private namespace.  As a result, any symbols in the previous private
  namespace will be no longer be accessible.  For this reason, it is
  recommended that this function should be used before any private
  symbols have been created.

 EXAMPLE
  Suppose that some file `t.sl' contains:

     implements ("My");
     define message (x)
     {
        Global->message ("My's message: $x"$);
     }
     message ("hello");

  will produce `"My's message: hello"'.  This `message'
  function may be accessed from outside the namespace via:

    My->message ("hi");


 NOTES
  Since `message' is an intrinsic function, it is public and may
  not be redefined in the public namespace.

  The `implements' function should rarely be used.  It is
  preferable to allow a static namespace to be associated with a
  compilation unit using, e.g., `evalfile'.

 SEE ALSO
  use_namespace, current_namespace, import

--------------------------------------------------------------

__is_callable

 SYNOPSIS
  Determine whether or not an object is callable

 USAGE
  Int_Type __is_callable (obj)

 DESCRIPTION
  This function may be used to determine if an object is callable by
  dereferencing the object.  It returns 1 if the argument is callable,
  or zero otherwise.

 EXAMPLE
   __is_callable (7)      ==> 0
   __is_callable (&sin)   ==> 1
   a = [&sin];
   __is_callable (a[0])   ==> 1
   __is_callable (&a[0])  ==> 0

 SEE ALSO
  __is_numeric, is_defined

--------------------------------------------------------------

__is_numeric

 SYNOPSIS
  Determine whether or not an object is a numeric type

 USAGE
  Int_Type __is_numeric (obj)

 DESCRIPTION
  This function may be used to determine if an object represents a
  numeric type.  It returns 0 if the argument is non-numeric, 1 if it
  is an integer, 2 if a floating point number, and 3 if it is complex.
  If the argument is an array, then the array type will be used for
  the test.

 EXAMPLE
   __is_numeric ("foo");  ==> 0
   __is_numeric ("0");    ==> 0
   __is_numeric (0);      ==> 1
   __is_numeric (PI);     ==> 2
   __is_numeric (2j);     ==> 3
   __is_numeric ([1,2]);  ==> 1
   __is_numeric ({1,2});  ==> 0

 SEE ALSO
  typeof, __is_datatype_numeric

--------------------------------------------------------------

__is_datatype_numeric

 SYNOPSIS
  Determine whether or not a type is a numeric type

 USAGE
  Int_Type __is_datatype_numeric (DataType_Type type)

 DESCRIPTION
  This function may be used to determine if the specified datatype
  represents a numeric type.  It returns 0 if the datatype does not
  represents a numeric type; otherwise it returns 1 for an
  integer type, 2 for a floating point type, and 3 for a complex type.

 SEE ALSO
  typeof, __is_numeric, __is_callable

--------------------------------------------------------------

__is_same

 SYNOPSIS
  Test for sameness of two objects

 USAGE
  Int_Type __is_same (a, b)

 DESCRIPTION
  This function tests its two arguments for sameness and returns 1
  if they are the same, or 0 otherwise.  To be the same, the data type of
  the arguments must match and the values of the objects must
  reference the same underlying object.

 EXAMPLE
   __is_same (1, 1)         ===> 1
   __is_same (1, 1.0)       ===> 0
   __is_same ("a", 1)       ===> 0
   __is_same ([1,2], [1,2]) ===> 0

 SEE ALSO
  typeof, _eqs, __get_reference, __is_callable

 NOTES
   For testing equality, use `_eqs'.

--------------------------------------------------------------

putenv

 SYNOPSIS
  Add or change an environment variable

 USAGE
  putenv (String_Type s)

 DESCRIPTION
    This functions adds string `s' to the environment.  Typically,
    `s' should of the form `"name=value"'.  The function
    throws an `OSError' upon failure.

 NOTES
    This function may not be available on all systems.

 SEE ALSO
  getenv, sprintf

--------------------------------------------------------------

_slang_install_prefix

 SYNOPSIS
  S-Lang's installation prefix

 USAGE
  String_Type _slang_install_prefix

 DESCRIPTION
  The value of this variable is set at the S-Lang library's
  compilation time.  On Unix systems, the value corresponds to the
  value of the `prefix' variable in the Makefile.  For normal
  installations, the library itself will be located in the `lib'
  subdirectory of the `prefix' directory.

 NOTES
  The value of this variable may or may not have anything to do with
  where the slang library is located.  As such, it should be regarded
  as a hint.  A standard installation will have the `slsh'
  library files located in the `share/slsh' subdirectory of the
  installation prefix.

 SEE ALSO
  _slang_doc_dir

--------------------------------------------------------------

_slang_utf8_ok

 SYNOPSIS
  Test if the interpreter running in UTF-8 mode

 USAGE
  Int_Type _slang_utf8_ok

 DESCRIPTION
  If the value of this variable is non-zero, then the interpreter is
  running in UTF-8 mode.  In this mode, characters in strings are
  interpreted as variable length byte sequences according to the
  semantics of the UTF-8 encoding.

 NOTES
  When running in UTF-8 mode, one must be careful not to confuse a
  character with a byte.  For example, in this mode the `strlen'
  function returns the number of characters in a string which may be
  different than the number of bytes.  The latter information may be
  obtained by the `strbytelen' function.

 SEE ALSO
  strbytelen, strlen, strcharlen

--------------------------------------------------------------

__uninitialize

 SYNOPSIS
  Uninitialize a variable

 USAGE
  __uninitialize (Ref_Type x)

 DESCRIPTION
  The `__uninitialize' function may be used to uninitialize the
  variable referenced by the parameter `x'.

 EXAMPLE
  The following two lines are equivalent:

     () = __tmp(z);
     __uninitialize (&z);


 SEE ALSO
  __tmp, __is_initialized

--------------------------------------------------------------

__tmp

 SYNOPSIS
  Returns the value of a variable and uninitialize the variable

 USAGE
  __tmp (x)

 DESCRIPTION
  The `__tmp' function takes a single argument, a variable,
  returns the value of the variable, and then undefines the variable.
  The purpose of this pseudo-function is to free any memory
  associated with a variable if that variable is going to be
  re-assigned.

 EXAMPLE

     x = 3;
     y = __tmp(x);

  will result in `y' having a value of `3' and `x' will be undefined.

 NOTES
  This function is a pseudo-function because a syntax error results if
  used like

      __tmp(sin(x));


 SEE ALSO
  __uninitialize, __is_initialized

--------------------------------------------------------------

use_namespace

 SYNOPSIS
  Change to another namespace

 USAGE
  use_namespace (String_Type name)

 DESCRIPTION
   The `use_namespace' function changes the current static namespace to
   the one specified by the parameter.  If the specified namespace
   does not exist, a `NamespaceError' exception will be generated.

 SEE ALSO
  implements, current_namespace, import

--------------------------------------------------------------

path_basename

 SYNOPSIS
  Get the basename part of a filename

 USAGE
  String_Type path_basename (String_Type filename)

 DESCRIPTION
   The `path_basename' function returns the basename associated
   with the `filename' parameter.  The basename is the non-directory
   part of the filename, e.g., on unix `c' is the basename of
   `/a/b/c'.

 SEE ALSO
  path_dirname, path_extname, path_concat, path_is_absolute

--------------------------------------------------------------

path_basename_sans_extname

 SYNOPSIS
  Get the basename part of a filename but without the extension

 USAGE
  String_Type path_basename_sans_extname (String_Type path)

 DESCRIPTION
   The `path_basename_sans_extname' function returns the basename
   associated with the `filename' parameter, omitting the
   extension if present.  The basename is the non-directory part of
   the filename, e.g., on unix `c' is the basename of
   `/a/b/c'.

 SEE ALSO
  path_dirname, path_basename, path_extname, path_concat, path_is_absolute

--------------------------------------------------------------

path_concat

 SYNOPSIS
  Combine elements of a filename

 USAGE
  String_Type path_concat (String_Type dir, String_Type basename)

 DESCRIPTION
   The `path_concat' function combines the arguments `dir' and
   `basename' to produce a filename.  For example, on Unix if
   `dir' is `x/y' and `basename' is `z', then the
   function will return `x/y/z'.

 SEE ALSO
  path_dirname, path_basename, path_extname, path_is_absolute

--------------------------------------------------------------

path_dirname

 SYNOPSIS
  Get the directory name part of a filename

 USAGE
  String_Type path_dirname (String_Type filename)

 DESCRIPTION
   The `path_dirname' function returns the directory name
   associated with a specified filename.

 NOTES
   On systems that include a drive specifier as part of the filename,
   the value returned by this function will also include the drive
   specifier.

 SEE ALSO
  path_basename, path_extname, path_concat, path_is_absolute

--------------------------------------------------------------

path_extname

 SYNOPSIS
  Return the extension part of a filename

 USAGE
  String_Type path_extname (String_Type filename)

 DESCRIPTION
   The `path_extname' function returns the extension portion of the
   specified filename.  If an extension is present, this function will
   also include the dot as part of the extension, e.g., if `filename'
   is `"file.c"', then this function will return `".c"'.  If no
   extension is present, the function returns an empty string `""'.

 NOTES
   Under VMS, the file version number is not returned as part of the
   extension.

 SEE ALSO
  path_sans_extname, path_dirname, path_basename, path_concat, path_is_absolute

--------------------------------------------------------------

path_get_delimiter

 SYNOPSIS
  Get the value of a search-path delimiter

 USAGE
  Char_Type path_get_delimiter ()

 DESCRIPTION
  This function returns the value of the character used to delimit
  fields of a search-path.

 SEE ALSO
  set_slang_load_path, get_slang_load_path

--------------------------------------------------------------

path_is_absolute

 SYNOPSIS
  Determine whether or not a filename is absolute

 USAGE
  Int_Type path_is_absolute (String_Type filename)

 DESCRIPTION
   The `path_is_absolute' function will return non-zero is
   `filename' refers to an absolute filename, otherwise it returns zero.

 SEE ALSO
  path_dirname, path_basename, path_extname, path_concat

--------------------------------------------------------------

path_sans_extname

 SYNOPSIS
  Strip the extension from a filename

 USAGE
  String_Type path_sans_extname (String_Type filename)

 DESCRIPTION
  The `path_sans_extname' function removes the file name extension
  (including the dot) from the filename and returns the result.

 SEE ALSO
  path_basename_sans_extname, path_extname, path_basename, path_dirname, path_concat

--------------------------------------------------------------

close

 SYNOPSIS
  Close an open file descriptor

 USAGE
  Int_Type close (FD_Type fd)

 DESCRIPTION
  The `close' function is used to close and open file descriptor
  created by the `open' function.  Upon success 0 is returned,
  otherwise the function returns -1 and sets `errno' accordingly.

 SEE ALSO
  open, fclose, read, write

--------------------------------------------------------------

dup_fd

 SYNOPSIS
  Duplicate a file descriptor

 USAGE
  FD_Type dup_fd (FD_Type fd)

 DESCRIPTION
  The `dup_fd' function duplicates a specified file descriptor and
  returns the duplicate.  If the function fails, NULL will be
  returned and `errno' set accordingly.

 NOTES
  This function is essentially a wrapper around the POSIX `dup'
  function.

 SEE ALSO
  open, close

--------------------------------------------------------------

_fileno

 SYNOPSIS
  Get the underlying integer file descriptor

 USAGE
  Int_Type fileno (File_Type|FD_Type fp)

 DESCRIPTION
  The `_fileno' function returns the underlying integer
  descriptor for a specified stdio File_Type or
  FD_Type object.  Upon failure it returns -1 and sets
  `errno' accordingly.

 SEE ALSO
  fileno, fopen, open, fclose, close, dup_fd

--------------------------------------------------------------

fileno

 SYNOPSIS
  Convert a stdio File_Type object to a FD_Type descriptor

 USAGE
  FD_Type fileno (File_Type fp)

 DESCRIPTION
  The `fileno' function returns the FD_Type descriptor
  associated with the stdio File_Type file pointer.  Upon failure,
  NULL is returned.

 NOTES
  Closing the resulting file descriptor will have no effect.

 SEE ALSO
  fopen, open, fclose, close, dup_fd, _fileno

--------------------------------------------------------------

isatty

 SYNOPSIS
  Determine if an open file descriptor refers to a terminal

 USAGE
  Int_Type isatty (FD_Type or File_Type fd)

 DESCRIPTION
  This function returns 1 if the file descriptor `fd' refers to a
  terminal; otherwise it returns 0.  The object `fd' may either
  be a File_Type stdio descriptor or a lower-level FD_Type
  object.

 SEE ALSO
  fopen, fclose, fileno

--------------------------------------------------------------

lseek

 SYNOPSIS
  Reposition a file descriptor's file pointer

 USAGE
  Long_Type lseek (FD_Type fd, LLong_Type ofs, int mode)
   The `lseek' function repositions the file pointer associated
   with the open file descriptor `fd' to the offset `ofs'
   according to the mode parameter.  Specifically, `mode' must be
   one of the values:

     SEEK_SET   Set the offset to ofs from the beginning of the file
     SEEK_CUR   Add ofs to the current offset
     SEEK_END   Add ofs to the current file size

   Upon error, `lseek' returns -1 and sets `errno'.  If
   successful, it returns the new filepointer offset.

 NOTES
   Not all file descriptors are capable of supporting the seek
   operation, e.g., a descriptor associated with a pipe.

   By using SEEK_END with a positive value of the `ofs'
   parameter, it is possible to position the file pointer beyond the
   current size of the file.

 SEE ALSO
  fseek, ftell, open, close

--------------------------------------------------------------

open

 SYNOPSIS
  Open a file

 USAGE
  FD_Type open (String_Type filename, Int_Type flags [,Int_Type mode])

 DESCRIPTION
  The `open' function attempts to open a file specified by the
  `filename' parameter according to the `flags' parameter,
  which must be one of the following values:

     O_RDONLY   (read-only)
     O_WRONLY   (write-only)
     O_RDWR     (read/write)

  In addition, `flags' may also be bitwise-or'd with any of the
  following:

     O_BINARY   (open the file in binary mode)
     O_TEXT     (open the file in text mode)
     O_CREAT    (create the file if it does not exist)
     O_EXCL     (fail if the file already exists)
     O_NOCTTY   (do not make the device the controlling terminal)
     O_TRUNC    (truncate the file if it exists)
     O_APPEND   (open the file in append mode)
     O_NONBLOCK (open the file in non-blocking mode)

   Some of these flags make sense only when combined with other flags.
   For example, if O_EXCL is used, then O_CREAT must also be
   specified, otherwise unpredictable behavior may result.

   If O_CREAT is used for the `flags' parameter then the
   `mode' parameter must be present. `mode' specifies the
   permissions to use if a new file is created. The actual file
   permissions will be affected by the process's `umask' via
   `mode&~umask'.  The `mode' parameter's value is
   constructed via bitwise-or of the following values:

     S_IRWXU    (Owner has read/write/execute permission)
     S_IRUSR    (Owner has read permission)
     S_IWUSR    (Owner has write permission)
     S_IXUSR    (Owner has execute permission)
     S_IRWXG    (Group has read/write/execute permission)
     S_IRGRP    (Group has read permission)
     S_IWGRP    (Group has write permission)
     S_IXGRP    (Group has execute permission)
     S_IRWXO    (Others have read/write/execute permission)
     S_IROTH    (Others have read permission)
     S_IWOTH    (Others have write permission)
     S_IXOTH    (Others have execute permission)

   Upon success `open' returns a file descriptor object
   (FD_Type), otherwise NULL is returned and `errno'
   is set.

 NOTES
   If you are not familiar with the `open' system call, then it
   is recommended that you use `fopen' instead and use the higher
   level stdio interface.

 SEE ALSO
  fopen, close, read, write, stat_file

--------------------------------------------------------------

read

 SYNOPSIS
  Read from an open file descriptor

 USAGE
  UInt_Type read (FD_Type fd, Ref_Type buf, UInt_Type num)

 DESCRIPTION
  The `read' function attempts to read at most `num' bytes
  into the variable indicated by `buf' from the open file
  descriptor `fd'.  It returns the number of bytes read, or -1
  upon failure and sets `errno'.  The number of bytes
  read may be less than `num', and will be zero if an attempt is
  made to read past the end of the file.

 NOTES
  `read' is a low-level function and may return -1 for a variety
  of reasons.  For example, if non-blocking I/O has been specified for
  the open file descriptor and no data is available for reading then
  the function will return -1 and set `errno' to EAGAIN.

 SEE ALSO
  fread, open, close, write

--------------------------------------------------------------

write

 SYNOPSIS
  Write to an open file descriptor

 USAGE
  UInt_Type write (FD_Type fd, BString_Type buf)

 DESCRIPTION
   The `write' function attempts to write the bytes specified by
   the `buf' parameter to the open file descriptor `fd'.  It
   returns the number of bytes successfully written, or -1 and sets
   `errno' upon failure.  The number of bytes written may be less
   than `length(buf)'.

 SEE ALSO
  read, fwrite, open, close

--------------------------------------------------------------

getegid

 SYNOPSIS
  Get the effective group id of the current process

 USAGE
  Int_Type getegid ()

 DESCRIPTION
  The `getegid' function returns the effective group ID of the
  current process.

 NOTES
  This function is not supported by all systems.

 SEE ALSO
  getgid, geteuid, setgid

--------------------------------------------------------------

geteuid

 SYNOPSIS
  Get the effective user-id of the current process

 USAGE
  Int_Type geteuid ()

 DESCRIPTION
  The `geteuid' function returns the effective user-id of the
  current process.

 NOTES
  This function is not supported by all systems.

 SEE ALSO
  getuid, setuid, setgid

--------------------------------------------------------------

getgid

 SYNOPSIS
  Get the group id of the current process

 USAGE
  Integer_Type getgid ()

 DESCRIPTION
  The `getgid' function returns the real group id of the current
  process.

 NOTES
  This function is not supported by all systems.

 SEE ALSO
  getpid, getppid

--------------------------------------------------------------

getpid

 SYNOPSIS
  Get the current process id

 USAGE
  Integer_Type getpid ()

 DESCRIPTION
  The `getpid' function returns the current process identification
  number.

 SEE ALSO
  getppid, getgid

--------------------------------------------------------------

getppid

 SYNOPSIS
  Get the parent process id

 USAGE
  Integer_Type getppid ()

 DESCRIPTION
  The `getpid' function returns the process identification
  number of the parent process.

 NOTES
  This function is not supported by all systems.

 SEE ALSO
  getpid, getgid

--------------------------------------------------------------

getpriority

 SYNOPSIS
  Get a process's scheduling priority

 USAGE
  result = getpriority (which, who)

 DESCRIPTION
 The `setpriority' function may be used to obtain the kernel's
 scheduling priority for a process, process group, or a user depending
 upon the values of the `which' and `who' parameters.
 Specifically, if the value of `which' is `PRIO_PROCESS',
 then the value of `who' specifies the process id of the affected
 process. If `which' is `PRIO_PGRP', then `who'
 specifies a process group id.  If `which' is `PRIO_USER',
 then the value of `who' is interpreted as a user id.  For the
 latter two cases, where `which' refers to a set of processes,
 the value returned corresponds to the highest priority of a process
 in the set.  A value of 0 may be used for who to denote the process
 id, process group id, or real user ID of the current process.

 Upon success, the function returns the specified priority value.  If
 an error occurs, the function will return NULL with `errno' set
 accordingly.

 SEE ALSO
  setpriority, getpid, getppid

--------------------------------------------------------------

getuid

 SYNOPSIS
  Get the user-id of the current process

 USAGE
  Int_Type getuid ()

 DESCRIPTION
  The `getuid' function returns the user-id of the current
  process.

 NOTES
  This function is not supported by all systems.

 SEE ALSO
  getuid, getegid

--------------------------------------------------------------

kill

 SYNOPSIS
  Send a signal to a process

 USAGE
  Integer_Type kill (Integer_Type pid, Integer_Type sig)

 DESCRIPTION
  This function may be used to send a signal given by the integer `sig'
  to the process specified by `pid'.  The function returns zero upon
  success or `-1' upon failure setting `errno' accordingly.

 EXAMPLE
  The `kill' function may be used to determine whether or not
  a specific process exists:

    define process_exists (pid)
    {
       if (-1 == kill (pid, 0))
         return 0;     % Process does not exist
       return 1;
    }


 NOTES
  This function is not supported by all systems.

 SEE ALSO
  getpid

--------------------------------------------------------------

mkfifo

 SYNOPSIS
  Create a named pipe

 USAGE
  Int_Type mkfifo (String_Type name, Int_Type mode)

 DESCRIPTION
  The `mkfifo' attempts to create a named pipe with the specified
  name and mode (modified by the process's umask).  The function
  returns 0 upon success, or -1 and sets `errno' upon failure.

 NOTES
  Not all systems support the `mkfifo' function and even on
  systems that do implement the `mkfifo' system call, the
  underlying file system may not support the concept of a named pipe,
  e.g, an NFS filesystem.

 SEE ALSO
  stat_file

--------------------------------------------------------------

setgid

 SYNOPSIS
  Set the group-id of the current process

 USAGE
  Int_Type setgid (Int_Type gid)

 DESCRIPTION
  The `setgid' function sets the effective group-id of the current
  process.  It returns zero upon success, or -1 upon error and sets
  `errno' appropriately.

 NOTES
  This function is not supported by all systems.

 SEE ALSO
  getgid, setuid

--------------------------------------------------------------

setpgid

 SYNOPSIS
  Set the process group-id

 USAGE
  Int_Type setpgid (Int_Type pid, Int_Type gid)

 DESCRIPTION
  The `setpgid' function sets the group-id `gid' of the
  process whose process-id is `pid'.  If `pid' is 0, then the
  current process-id will be used.  If `pgid' is 0, then the pid
  of the affected process will be used.

  If successful 0 will be returned, otherwise the function will
  return -1 and set `errno' accordingly.

 NOTES
  This function is not supported by all systems.

 SEE ALSO
  setgid, setuid

--------------------------------------------------------------

setpriority

 SYNOPSIS
  Set the scheduling priority for a process

 USAGE
  Int_Type setpriority (which, who, prio)

 DESCRIPTION
 The `setpriority' function may be used to set the kernel's
 scheduling priority for a process, process group, or a user depending
 upon the values of the `which' and `who' parameters.
 Specifically, if the value of `which' is `PRIO_PROCESS', then the
 value of `who' specifies the process id of the affected process.
 If `which' is `PRIO_PGRP', then `who' specifies a process
 group id.  If `which' is `PRIO_USER',  then the value of
 `who' is interpreted as a user id.  A value of 0 may be used for
 who to denote the process id, process group id, or real user ID of
 the current process.

 Upon sucess, the `setpriority' function returns 0.  If an error occurs,
 -1 is returned and errno will be set accordingly.

 EXAMPLE
  The `getpriority' and `setpriority' functions may be used
  to implement a `nice' function for incrementing the priority of
  the current process as follows:

   define nice (dp)
   {
      variable p = getpriority (PRIO_PROCESS, 0);
      if (p == NULL)
        return -1;
      variable s = setpriority (PRIO_PROCESS, 0, p + dp);
      if (s == -1)
        return -1;
      return getpriority (PRIO_PROCESS, 0);
   }


 NOTES
 Priority values are sometimes called "nice" values.  The actual
 range of priority values is system dependent but commonly range from
 -20 to 20, with -20 being the highest scheduling priority, and +20
 the lowest.

 SEE ALSO
  getpriority, getpid

--------------------------------------------------------------

setuid

 SYNOPSIS
  Set the user-id of the current process

 USAGE
  Int_Type setuid (Int_Type id)

 DESCRIPTION
  The `setuid' function sets the effective user-id of the current
  process.  It returns zero upon success, or -1 upon error and sets
  `errno' appropriately.

 NOTES
  This function is not supported by all systems.

 SEE ALSO
  setgid, setpgid, getuid, geteuid

--------------------------------------------------------------

sleep

 SYNOPSIS
  Pause for a specified number of seconds

 USAGE
  sleep (Double_Type n)

 DESCRIPTION
  The `sleep' function delays the current process for the
  specified number of seconds.  If it is interrupted by a signal, it
  will return prematurely.

 NOTES
  Not all system support sleeping for a fractional part of a second.

--------------------------------------------------------------

system

 SYNOPSIS
  Execute a shell command

 USAGE
  Integer_Type system (String_Type cmd)

 DESCRIPTION
  The `system' function may be used to execute the string
  expression `cmd' in an inferior shell.  This function is an
  interface to the C `system' function which returns an
  implementation-defined result.   On Linux, it returns 127 if the
  inferior shell could not be invoked, -1 if there was some other
  error, otherwise it returns the return code for `cmd'.

 EXAMPLE

    define dir ()
    {
       () = system ("DIR");
    }

  displays a directory listing of the current directory under MSDOS or
  VMS.

 SEE ALSO
  system_intr, new_process, popen

--------------------------------------------------------------

system_intr

 SYNOPSIS
  Execute a shell command

 USAGE
  Integer_Type system_intr (String_Type cmd)

 DESCRIPTION
 The `system_intr' function performs the same task as the
 `system' function, except that the `SIGINT' signal will not
 be ignored by the calling process.  This means that if a S-Lang script
 calls `system_intr' function, and Ctrl-C is pressed, both the
 command invoked by the `system_intr' function and the script
 will be interrupted.  In contrast, if the command were invoked using
 the `system' function, only the command called by it would be
 interrupted, but the script would continue executing.

 SEE ALSO
  system, new_process, popen

--------------------------------------------------------------

umask

 SYNOPSIS
  Set the file creation mask

 USAGE
  Int_Type umask (Int_Type m)

 DESCRIPTION
  The `umask' function sets the file creation mask to the value of
  `m' and returns the previous mask.

 SEE ALSO
  stat_file

--------------------------------------------------------------

uname

 SYNOPSIS
  Get the system name

 USAGE
  Struct_Type uname ()

 DESCRIPTION
  The `uname' function returns a structure containing information
  about the operating system.  The structure contains the following
  fields:

       sysname  (Name of the operating system)
       nodename (Name of the node within the network)
       release  (Release level of the OS)
       version  (Current version of the release)
       machine  (Name of the hardware)


 NOTES
  Not all systems support this function.

 SEE ALSO
  getenv

--------------------------------------------------------------

qualifier

 SYNOPSIS
  Get the value of a qualifier

 USAGE
  value = qualifier (String_Type name [,default_value])

 DESCRIPTION
 This function may be used to get the value of a qualifier.  If the
 specified qualifier does not exist, `NULL' will be returned,
 unless a default value has been provided.

 EXAMPLE

    define echo (text)
    {
       variable fp = qualifier ("out", stdout);
       () = fputs (text, fp);
    }
    echo ("hello");              % writes hello to stdout
    echo ("hello"; out=stderr);  % writes hello to stderr


 NOTES
 Since `NULL' is a valid value for a qualifier, this function is
 unable to distinguish between a non-existent qualifier and one whose
 value is `NULL'.  If such a distinction is important, the
 `qualifier_exists' function can be used.  For example,

    define echo (text)
    {
       variable fp = stdout;
       if (qualifier_exists ("use_stderr"))
         fp = stderr;
       () = fputs (text, fp);
    }
    echo ("hello"; use_stderr);  % writes hello to stderr

 In this case, no value was provided for the `use_stderr'
 qualifier: it exists but has a value of `NULL'.

 SEE ALSO
  qualifier_exists, __qualifiers

--------------------------------------------------------------

__qualifiers

 SYNOPSIS
  Get the active set of qualifiers

 USAGE
  Struct_Type __qualifiers ()

 DESCRIPTION
 This function returns the set of qualifiers associated with the
 current execution context.  If qualifiers are active, then the result
 is a structure representing the names of the qualifiers and their
 corresponding values.  Otherwise `NULL' will be returned.

 One of the main uses of this function is to pass the current set of
 qualifiers to another another function.  For example, consider a
 plotting application with a function called called `lineto' that
 sets the pen-color before drawing the line to the specified point:

    define lineto (x, y)
    {
       % The color may be specified by a qualifier, defaulting to black
       variable color = qualifier ("color", "black");
       set_pen_color (color);
           .
           .
    }

 The `lineto' function permits the color to be specified by a
 qualifier.  Now consider a function that make use of lineto to draw a
 line segment between two points:

    define line_segment (x0, y0, x1, y1)
    {
       moveto (x0, y0);
       lineto (x1, y1 ; color=qualifier("color", "black"));
    }
    line_segment (1,1, 10,10; color="blue");

 Note that in this implementation of `line_segment', the
 `color' qualifier was explicitly passed to the `lineto'
 function.  However, this technique does not scale well.  For example, the
 `lineto' function might also take a qualifier that specifies the
 line-style, to be used as

    line_segment (1,1, 10,10; color="blue", linestyle="solid");

 But the above implementation of `line_segment' does not pass the
 `linestyle' qualifier.  In such a case, it is preferable to pass
 all the qualifiers, e.g.,

    define line_segment (x0, y0, x1, y1)
    {
       moveto (x0, y0);
       lineto (x1, y1 ;; __qualifiers());
    }

 Note the use of the double-semi colon in the `lineto'
 statement.  This tells the parser that the qualifiers are specified
 by a structure-valued argument and not a set of name-value pairs.

 SEE ALSO
  qualifier, qualifier_exists

--------------------------------------------------------------

qualifier_exists

 SYNOPSIS
  Check for the existence of a qualifier

 USAGE
  Int_Type qualifier_exists (String_Type name)

 DESCRIPTION
 This function will return 1 if a qualifier of the specified name
 exists, or 0 otherwise.

 SEE ALSO
  qualifier, __qualifiers

--------------------------------------------------------------

rline_bolp

 SYNOPSIS
  Test of the editing point is at the beginning of the line

 USAGE
  Int_Type rline_bolp()

 DESCRIPTION
  The `rline_bolp' function returns a non-zero value if the
  current editing position is at the beginning of the line.

 NOTES
 This function is part of the S-Lang readline interface.

 SEE ALSO
  rline_eolp, rline_get_point, rline_get_line

--------------------------------------------------------------

rline_eolp

 SYNOPSIS
  Test of the editing point is at the end of the line

 USAGE
  Int_Type rline_eolp()

 DESCRIPTION
  The `rline_bolp' function returns a non-zero value if the
  current editing position is at the end of the line.

 NOTES
 This function is part of the S-Lang readline interface.

 SEE ALSO
  rline_bolp, rline_get_point, rline_get_line

--------------------------------------------------------------

rline_call

 SYNOPSIS
  Invoke an internal readline function

 USAGE
  rline_call (String_Type func)

 DESCRIPTION
 Not all of the readline functions are available directly from the
 S-Lang interpreter.  For example, the "deleol" function, which
 deletes through the end of the line may be executed using

    rline_call("deleol");

  See the documentation for the `rline_setkey' function for a
  list of internal functions that may be invoked by `rline_call'.

 NOTES
 This function is part of the S-Lang readline interface.

 SEE ALSO
  rline_setkey, rline_del, rline_ins

--------------------------------------------------------------

rline_del

 SYNOPSIS
  Delete a specified number of characters at the current position

 USAGE
  rline_del(Int_Type n)

 DESCRIPTION
 This function delete a specified number of characters at the current
 editing position.  If the number `n' is less than zero, then the
 previous `n' characters will be deleted.  Otherwise, the next
 `n' characters will be deleted.

 NOTES
 This function is part of the S-Lang readline interface.

 SEE ALSO
  rline_ins, rline_setkey

--------------------------------------------------------------

rline_get_edit_width

 SYNOPSIS
  Get the width of the readline edit window

 USAGE
  Int_Type rline_get_edit_width ()

 DESCRIPTION
  This function returns the width of the edit window.  For `slsh', this
  number corresponds to the width of the terminal window.

 NOTES
 This function is part of the S-Lang readline interface.

 SEE ALSO
  rline_ins

--------------------------------------------------------------

rline_get_history

 SYNOPSIS
  Retrieve the readline history

 USAGE
  Array_Type rline_get_history ()

 DESCRIPTION
  This function returns the readline edit history as an array of
  strings.

 NOTES
 This function is part of the S-Lang readline interface.

 SEE ALSO
  rline_set_line

--------------------------------------------------------------

rline_get_line

 SYNOPSIS
  Get a copy of the line being edited

 USAGE
  String_Type rline_get_line ()

 DESCRIPTION
  This function returns the current edit line.

 NOTES
 This function is part of the S-Lang readline interface.

 SEE ALSO
  rline_set_line, rline_get_history

--------------------------------------------------------------

rline_get_point

 SYNOPSIS
  Get the current editing position

 USAGE
  Int_Type rline_get_point ()

 DESCRIPTION
 The `rline_get_point' function returns the byte-offset of the
 current editing position.

 NOTES
 This function is part of the S-Lang readline interface.

 SEE ALSO
  rline_set_point

--------------------------------------------------------------

rline_getkey

 SYNOPSIS
  Obtain the next byte in the readline input stream

 USAGE
  Int_Type rline_getkey ()

 DESCRIPTION
  This function returns the next byte in the readline input stream.
  If no byte is available, the function will wait until one is.

 NOTES
 This function is part of the S-Lang readline interface.

 SEE ALSO
  rline_input_pending, rline_setkey

--------------------------------------------------------------

rline_input_pending

 SYNOPSIS
  Test to see if readline input is available for reading

 USAGE
  Int_Type rline_input_pending (Int_Type tsecs)

 DESCRIPTION
  This function returns a non-zero value if readline input is
  available to be read.  If none is immediately available, it will
  wait for up to `tsecs' tenths of a second for input before
  returning.

 NOTES
 This function is part of the S-Lang readline interface.

 SEE ALSO
  rline_getkey

--------------------------------------------------------------

rline_ins

 SYNOPSIS
  Insert a string at the current editing point

 USAGE
  rline_ins (String_Type text)

 DESCRIPTION
  This function inserts the specified string into the line being edited.

 NOTES
 This function is part of the S-Lang readline interface.

 SEE ALSO
  rline_set_line, rline_del

--------------------------------------------------------------

rline_set_history

 SYNOPSIS
  Replace the current history list with a new one

 USAGE
  rline_set_history (Array_Type lines)

 DESCRIPTION
  The `rline_set_history' function replaces the current history
  by the specified array of strings.

 NOTES
 This function is part of the S-Lang readline interface.

 SEE ALSO
  rline_get_history

--------------------------------------------------------------

rline_set_line

 SYNOPSIS
  Replace the current line with a new one

 USAGE
  rline_set_line (String_Type line)

 DESCRIPTION
  The `rline_set_line' function replaces the line being edited by
  the specified one.

 NOTES
 This function is part of the S-Lang readline interface.

 SEE ALSO
  rline_get_line

--------------------------------------------------------------

rline_set_point

 SYNOPSIS
  Move the current editing position to another

 USAGE
  rline_set_point (Int_Type ofs)

 DESCRIPTION
 The `rline_set_point' function sets the editing point to the
 specified byte-offset from the beginning of the line.

 NOTES
 This function is part of the S-Lang readline interface.

 SEE ALSO
  rline_get_point

--------------------------------------------------------------

rline_setkey

 SYNOPSIS
  Bind a key in the readline keymap to a function

 USAGE
  rline_setkey (func, keyseq)

 DESCRIPTION
  The `rline_setkey' function binds the function `func' to
  the specified key sequence `keyseq'.  The value of `func'
  may be either a reference to a S-Lang function, or a string giving
  the name of an internal readline function.

  Functions that are internal to the readline interface include:

   bdel             Delete the previous character
   bol              Move to the beginning of the line
   complete         The command line completion function
   del              Delete the character at the current position
   delbol           Delete to the beginning of the line
   deleol           Delete through the end of the line
   down             Goto the next line in the history
   enter            Return to the caller of the readline function
   eol              Move to the end of the line
   kbd_quit         Abort editing of the current line
   left             Move left one character
   quoted_insert    Insert the next byte into the line
   redraw           Redraw the line
   right            Move right one character
   self_insert      Insert the byte that invoked the function
   trim             Remove whitespace about the current position
   up               Goto the previous line in the history


 NOTES
 This function is part of the S-Lang readline interface.

 SEE ALSO
  rline_unsetkey

--------------------------------------------------------------

rline_unsetkey

 SYNOPSIS
  Unset a key binding from the readline keymap

 USAGE
  rline_unsetkey (String_Type keyseq)

 DESCRIPTION
  The `rline_unsetkey' function unbinds the specified key sequence
  from the readline keymap.

 NOTES
 This function is part of the S-Lang readline interface.

 SEE ALSO
  rline_setkey

--------------------------------------------------------------

rline_set_list_completions_callback

 SYNOPSIS
  Set a callback function to display the list of completions

 USAGE
  rline_set_list_completions_callback (Ref_Type func)

 DESCRIPTION
  This function sets the S-Lang function that is to be used to display the
  list of possible completions for current word at the readline prompt.
  The callback function must be defined to accept a single parameter
  representing an array of completion strings.

 EXAMPLE
  This callback function writes the completions using the message
  functions:

     private define display_completions (strings)
     {
        variable str;
        vmessage ("There are %d completions:\n", length(strings));
        foreach str (strings) vmessage ("%s\n", str);
     }
     rline_set_list_completions_callback (&display_completions);


 SEE ALSO
  rline_set_completion_callback

--------------------------------------------------------------

rline_set_completion_callback

 SYNOPSIS
  Set the function to be used for completion at the readline prompt

 USAGE
  rline_set_completion_callback (Ref_Type func)

 DESCRIPTION
  This function sets the callback function to be used for completion at the
  readline prompt.  The callback function must be defined to accept
  two values, the first being a string containing the text of the line
  being edited, and an integer giving the position of the byte-offset
  into the string where completion was requested.

  The callback function must return two values: an array giving the
  list of possible completion strings, and an integer giving the byte
  offset into the string of the start of the text to be completed.

 EXAMPLE
  See completion-callback function defined in the `slsh' library file
  `rline/complete.sl'.

 NOTES
 This function is part of the S-Lang readline interface.

 SEE ALSO
  rline_set_list_completions_callback

--------------------------------------------------------------

alarm

 SYNOPSIS
  Schedule an alarm signal

 USAGE
  alarm (UInt_Type secs [, Ref_Type secs_remaining])

 DESCRIPTION
  The `alarm' function schedules the delivery of a SIGALRM
  signal in `secs' seconds.  Any previously scheduled alarm will
  be canceled.  If `secs' is zero, then no new alarm will be
  scheduled.  If the second argument is present, then it must be a
  reference to a variable whose value will be set upon return to the
  number of seconds remaining for a previously scheduled alarm to take
  place.

 EXAMPLE
  This example shows demonstrates how the `alarm' function may be
  used to read from a file within a specified amount of time:

    define sigalrm_handler (sig)
    {
       throw ReadError, "Read timed out";
    }
    define read_or_timeout (secs)
    {
       variable line, e;
       variable fp = fopen ("/dev/tty", "r");
       signal (SIGALRM, &sigalrm_handler);
       alarm (secs);
       try (e)
         {
            () = fputs ("Enter some text> ", stdout); () = fflush (stdout);
            if (-1 == fgets (&line, fp))
              line = NULL;
         }
       catch IOError: { message (e.message); line = NULL; }
       return line;
    }


 NOTES
  Some operating systems may implement the `sleep' function using
  `alarm'.  As a result, it is not a good idea to mix calls to
  `alarm' and `sleep'.

  The default action for SIGALRM is to terminate the process.
  Hence, if `alarm' is called it is wise to establish a signal
  handler for `SIGALRM'.

 SEE ALSO
  signal, sleep

--------------------------------------------------------------

signal

 SYNOPSIS
  Establish a signal handler

 USAGE
  signal (Int_Type sig, Ref_Type func [,Ref_Type old_func])

 DESCRIPTION
  The `signal' function assigns the signal handler represented by
  `func' to the signal `sig'.  Here `func' is usually
  reference to a function that takes an integer argument (the signal)
  and returns nothing, e.g.,

    define signal_handler (sig)
    {
       return;
    }

  Alternatively, `func' may be given by one of the symbolic
  constants SIG_IGN or SIG_DFL to indicate that the
  signal is to be ignored or given its default action, respectively.

  The first parameter, `sig', specifies the signal to be handled.
  The actual supported values vary with the OS.  Common values on Unix
  include `SIGHUP', `SIGINT', and `SIGTERM'.

  If a third argument is present, then it must be a reference to a
  variable whose value will be set to the value of the previously
  installed handler.

 EXAMPLE
  This example establishes a handler for `SIGTSTP'.

    static define sig_suspend ();  % forward declaration
    static define sig_suspend (sig)
    {
       message ("SIGTSTP received-- stopping");
       signal (sig, SIG_DFL);
       () = kill (getpid(), SIGSTOP);
       message ("Resuming");
       signal (sig, &sig_suspend);
    }
    signal (SIGTSTP, &sig_suspend);


 NOTES
  Currently the signal interface is supported only on systems that
  implement signals according to the POSIX standard.

  Once a signal has been received, it will remain blocked until after
  the signal handler has completed.  This is the reason SIGSTOP
  was used in the above signal handler instead of SIGTSTP.

 SEE ALSO
  alarm, sigsuspend, sigprocmask

--------------------------------------------------------------

sigprocmask

 SYNOPSIS
  Change the list of currently blocked signals

 USAGE
  sigprocmask (Int_Type how, Array_Type mask [,Ref_Type old_mask])

 DESCRIPTION
  The `sigprocmask' function may be used to change the list of
  signals that are currently blocked.  The first parameter indicates
  how this is accomplished.  Specifically, `how' must be one of
  the following values: SIG_BLOCK, SIG_UNBLOCK, or
  SIG_SETMASK.

  If `how' is SIG_BLOCK, then the set of blocked signals
  will be the union the current set with the values specified in the
  `mask' argument.

  If `how' is SIG_UNBLOCK, then the signals specified by
  the `mask' parameter will be removed from the currently blocked
  set.

  If `how' is SIG_SETMASK, then the set of blocked signals
  will be set to those given by the `mask'.

  If a third argument is present, then it must be a reference to a
  variable whose value will be set to the previous signal mask.

 SEE ALSO
  signal, sigsuspend, alarm

--------------------------------------------------------------

sigsuspend

 SYNOPSIS
  Suspend the process until a signal is delivered

 USAGE
  sigsuspend ([Array_Type signal_mask])

 DESCRIPTION
  The
sigsuspend
 function suspends the current process
  until a signal is received.  An optional array argument may be
  passed to the function to specify a list of signals that should be
  temporarily blocked while waiting for a signal.

 EXAMPLE
  The following example pauses the current process for 10 seconds
  while blocking the SIGHUP and SIGINT signals.

     static variable Tripped;
     define sigalrm_handler (sig)
     {
        Tripped = 1;
     }
     signal (SIGALRM, &sigalrm_handler);
     Tripped = 0;
     alarm (10);
     while (Tripped == 0) sigsuspend ([SIGHUP, SIGINT]);

  Note that in this example the call to `sigsuspend' was wrapped in
  a while-loop.  This was necessary because there is no guarantee that
  another signal would not cause `sigsuspend' to return.

 SEE ALSO
  signal, alarm, sigprocmask

--------------------------------------------------------------

dup

 SYNOPSIS
  Duplicate the value at the top of the stack

 USAGE
  dup ()

 DESCRIPTION
  This function returns an exact duplicate of the object on top of the
  stack.  For some objects such as arrays or structures, it creates a
  new reference to the object.  However, for simple scalar S-Lang types such
  as strings, integers, and doubles, it creates a new copy of the
  object.

 SEE ALSO
  pop, typeof

--------------------------------------------------------------

exch

 SYNOPSIS
  Exchange two items on the stack

 USAGE
  exch ()

 DESCRIPTION
  The `exch' swaps the two top items on the stack.

 SEE ALSO
  pop, _stk_reverse, _stk_roll

--------------------------------------------------------------

pop

 SYNOPSIS
  Discard an item from the stack

 USAGE
  pop ()

 DESCRIPTION
  The `pop' function removes the top item from the stack.

 SEE ALSO
  _pop_n, __pop_args

--------------------------------------------------------------

__pop_args

 SYNOPSIS
  Remove n function arguments from the stack

 USAGE
  args = __pop_args(Integer_Type n)

 DESCRIPTION
  This function, together with the companion function
  `__push_args', is useful for creating a function that takes a
  variable number of arguments, as well as passing the arguments of
  one function to another function.

  `__pop_args' removes the specified number of values from the
  stack and returns them as an array of structures of the corresponding
  length.  Each structure in the array consists of a single
  field called `value', which represents the value of the
  argument.

 EXAMPLE
  Consider the following function.  It prints all its arguments to
  `stdout' separated by spaces:

    define print_args ()
    {
       variable i;
       variable args = __pop_args (_NARGS);

       for (i = 0; i < _NARGS; i++)
         {
            () = fputs (string (args[i].value), stdout);
            () = fputs (" ", stdout);
         }
       () = fputs ("\n", stdout);
       () = fflush (stdout);
    }

  Now consider the problem of defining a function called `ones'
  that returns a multi-dimensional array with all the elements set to
  1.  For example, `ones(10)' should return a 1-d array of 10
  ones, whereas `ones(10,20)' should return a 10x20 array.

    define ones ()
    {
      !if (_NARGS) return 1;
      variable a;

      a = __pop_args (_NARGS);
      return @Array_Type (Integer_Type, [__push_args (a)]) + 1;
    }

  Here, `__push_args' was used to push the arguments passed to
  the `ones' function onto the stack to be used when dereferencing
  Array_Type.

 NOTES
  This function has been superseded by the `__pop_list' function,
  which returns the objects as a list instead of an array of structures.

 SEE ALSO
  __push_args, __pop_list, __push_list, typeof, _pop_n

--------------------------------------------------------------

__pop_list

 SYNOPSIS
  Convert items on the stack to a List_Type

 USAGE
  List_Type = __pop_list (Int_Type n)

 DESCRIPTION
 This function removes a specified number of items from the stack and
 converts returns them in the form of a list.

 EXAMPLE

  define print_args ()
  {
     variable list = __pop_list (_NARGS);
     variable i;
     _for i (0, length(list)-1, 1)
        {
           vmessage ("arg[%d]: %S", i, list[i]);
        }
  }


 SEE ALSO
  __push_list

--------------------------------------------------------------

_pop_n

 SYNOPSIS
  Remove objects from the stack

 USAGE
  _pop_n (Integer_Type n);

 DESCRIPTION
  The `_pop_n' function removes the specified number of objects
  from the top of the stack.

 SEE ALSO
  _stkdepth, pop

--------------------------------------------------------------

_print_stack

 SYNOPSIS
  Print the values on the stack.

 USAGE
  _print_stack ()

 DESCRIPTION
  This function dumps out what is currently on the S-Lang stack.  It does not
  alter the stack and it is usually used for debugging purposes.

 SEE ALSO
  _stkdepth, string, message

--------------------------------------------------------------

__push_args

 SYNOPSIS
  Move n function arguments onto the stack

 USAGE
  __push_args (Struct_Type args);

 DESCRIPTION
  This function together with the companion function `__pop_args'
  is useful for the creation of functions that take a variable number
  of arguments.  See the description of `__pop_args' for more
  information.

 NOTES
  This function has been superseded by the `__push_list' function.

 SEE ALSO
  __pop_args, __push_list, __pop_list, typeof, _pop_n

--------------------------------------------------------------

__push_list

 SYNOPSIS
  Push the elements of a list to the stack

 USAGE
  __push_list (List_Type list)

 DESCRIPTION
 This function pushes the elements of a list to the stack.

 EXAMPLE

 private define list_to_array (list)
 {
    return [__push_list (list)];
 }


 SEE ALSO
  __pop_list

--------------------------------------------------------------

_stkdepth

 USAGE
  Get the number of objects currently on the stack

 SYNOPSIS
  Integer_Type _stkdepth ()

 DESCRIPTION
  The `_stkdepth' function returns number of items on the stack.

 SEE ALSO
  _print_stack, _stk_reverse, _stk_roll

--------------------------------------------------------------

_stk_reverse

 SYNOPSIS
  Reverse the order of the objects on the stack

 USAGE
  _stk_reverse (Integer_Type n)

 DESCRIPTION
   The `_stk_reverse' function reverses the order of the top
   `n' items on the stack.

 SEE ALSO
  _stkdepth, _stk_roll

--------------------------------------------------------------

_stk_roll

 SYNOPSIS
  Roll items on the stack

 USAGE
  _stk_roll (Integer_Type n)

 DESCRIPTION
  This function may be used to alter the arrangement of objects on the
  stack.  Specifically, if the integer `n' is positive, the top
  `n' items on the stack are rotated up.  If
  `n' is negative, the top `abs(n)' items on the stack are
  rotated down.

 EXAMPLE
  If the stack looks like:

    item-0
    item-1
    item-2
    item-3

  where `item-0' is at the top of the stack, then
  `_stk_roll(-3)' will change the stack to:

    item-2
    item-0
    item-1
    item-3


 NOTES
  This function only has an effect if `abs(n) > 1'.

 SEE ALSO
  _stkdepth, _stk_reverse, _pop_n, _print_stack

--------------------------------------------------------------

clearerr

 SYNOPSIS
  Clear the error of a file stream

 USAGE
  clearerr (File_Type fp

 DESCRIPTION
  The `clearerr' function clears the error and end-of-file flags
  associated with the open file stream `fp'.

 SEE ALSO
  ferror, feof, fopen

--------------------------------------------------------------

fclose

 SYNOPSIS
  Close a file

 USAGE
  Integer_Type fclose (File_Type fp)

 DESCRIPTION
  The `fclose' function may be used to close an open file pointer
  `fp'.  Upon success it returns zero, and upon failure it sets
  `errno' and returns `-1'.  Failure usually indicates a that
  the file system is full or that `fp' does not refer to an open file.

 NOTES
  Many C programmers call `fclose' without checking the return
  value.  The S-Lang language requires the programmer to explicitly
  handle any value returned by a function.  The simplest way to
  handle the return value from `fclose' is to call it via:

     () = fclose (fp);


 SEE ALSO
  fopen, fgets, fflush, pclose, errno

--------------------------------------------------------------

fdopen

 SYNOPSIS
  Convert a FD_Type file descriptor to a stdio File_Type object

 USAGE
  File_Type fdopen (FD_Type, String_Type mode)

 DESCRIPTION
   The `fdopen' function creates and returns a stdio
   File_Type object from the open FD_Type
   descriptor `fd'.  The `mode' parameter corresponds to the
   `mode' parameter of the `fopen' function and must be
   consistent with the mode of the descriptor `fd'.  The function
   returns NULL upon failure and sets `errno'.

 NOTES
   Since the stdio File_Type object created by this function
   is derived from the FD_Type descriptor, the FD_Type
   is regarded as more fundamental than the File_Type object.
   This means that the descriptor must be in scope while the
   File_Type object is used.  In particular, if the descriptor
   goes out of scope, the descriptor will get closed causing I/O to the
   File_Type object to fail, e.g.,

     fd = open ("/path/to/file", O_RDONLY);
     fp = fdopen (fd);
     fd = 0;     % This will cause the FD_Type descriptor to go out of
                 % scope.  Any I/O on fp will now fail.


   Calling the `fclose' function on the File_Type object
   will cause the underlying descriptor to close.

   Any stdio File_Type object created by the `fdopen'
   function will remain associated with the FD_Type descriptor,
   unless the object is explicitly removed via `fclose'.  This
   means that code such as

      fd = open (...);
      loop (50)
        {
           fp = fdopen (fd, ...);
              .
              .
        }

   will result in 50 File_Type objects attached to `fd'
   after the loop has terminated.

 SEE ALSO
  fileno, fopen, open, close, fclose, dup_fd

--------------------------------------------------------------

feof

 SYNOPSIS
  Get the end-of-file status

 USAGE
  Integer_Type feof (File_Type fp)

 DESCRIPTION
  This function may be used to determine the state of the end-of-file
  indicator of the open file descriptor `fp'.  It returns zero
  if the indicator is not set, or non-zero if it is.  The end-of-file
  indicator may be cleared by the `clearerr' function.

 SEE ALSO
  ferror, clearerr, fopen

--------------------------------------------------------------

ferror

 SYNOPSIS
  Determine the error status of an open file descriptor

 USAGE
  Integer_Type ferror (File_Type fp)

 DESCRIPTION
  This function may be used to determine the state of the error
  indicator of the open file descriptor `fp'.  It returns zero
  if the indicator is not set, or non-zero if it is.  The error
  indicator may be cleared by the `clearerr' function.

 SEE ALSO
  feof, clearerr, fopen

--------------------------------------------------------------

fflush

 SYNOPSIS
  Flush an output stream

 USAGE
  Integer_Type fflush (File_Type fp)

 DESCRIPTION
  The `fflush' function may be used to update the stdio _output_
  stream specified by `fp'.  It returns 0 upon success, or
  -1 upon failure and sets `errno' accordingly.  In
  particular, this function will fail if `fp' does not represent
  an open output stream, or if `fp' is associated with a disk file and
  there is insufficient disk space.

 EXAMPLE
  This example illustrates how to use the `fflush' function
  without regard to the return value:

    () = fputs ("Enter value> ", stdout);
    () = fflush (stdout);


 SEE ALSO
  fopen, fclose

--------------------------------------------------------------

fgets

 SYNOPSIS
  Read a line from a file

 USAGE
  Integer_Type fgets (SLang_Ref_Type ref, File_Type fp)

 DESCRIPTION
  `fgets' reads a line from the open file specified by `fp'
  and places the characters in the variable whose reference is
  specified by `ref'.
  It returns -1 if `fp' is not associated with an open file
  or an attempt was made to read at the end the file; otherwise, it
  returns the number of characters read.

 EXAMPLE
  The following example returns the lines of a file via a linked list:

    define read_file (file)
    {
       variable buf, fp, root, tail;
       variable list_type = struct { text, next };

       root = NULL;

       fp = fopen(file, "r");
       if (fp == NULL)
         throw OpenError, "fopen failed to open $file for reading"$;
       while (-1 != fgets (&buf, fp))
         {
            if (root == NULL)
              {
                 root = @list_type;
                 tail = root;
              }
            else
              {
                 tail.next = @list_type;
                 tail = tail.next;
              }
            tail.text = buf;
            tail.next = NULL;
         }
       () = fclose (fp);
       return root;
    }


 SEE ALSO
  fgetslines, fopen, fclose, fputs, fread, error

--------------------------------------------------------------

fgetslines

 SYNOPSIS
  Read lines as an array from an open file

 USAGE
  String_Type[] fgetslines (File_Type fp [,Int_Type num])

 DESCRIPTION
  The `fgetslines' function reads lines a specified number of
  lines as an array of strings from the file associated with the
  file pointer `fp'.  If the number of lines to be read is left
  unspecified, the function will return the rest of the lines in the
  file.  If the file is empty, an empty string array will be returned.
  The function returns NULL upon error.

 EXAMPLE
  The following function returns the number of lines in a file:

    define count_lines_in_file (file)
    {
       variable fp, lines;

       fp = fopen (file, "r");
       if (fp == NULL)
         return -1;

       lines = fgetslines (fp);
       if (lines == NULL)
         return -1;

       return length (lines);
    }

  Note that the file was implicitly closed when the variable `fp'
  goes out of scope (in the case, when the function returns).

 SEE ALSO
  fgets, fread, fopen, fputslines

--------------------------------------------------------------

fopen

 SYNOPSIS
  Open a file

 USAGE
  File_Type fopen (String_Type f, String_Type m)

 DESCRIPTION
  The `fopen' function opens a file `f' according to the mode
  string `m'.  Allowed values for `m' are:

     "r"    Read only
     "w"    Write only
     "a"    Append
     "r+"   Reading and writing at the beginning of the file.
     "w+"   Reading and writing.  The file is created if it does not
              exist; otherwise, it is truncated.
     "a+"   Reading and writing at the end of the file.  The file is created
              if it does not already exist.

  In addition, the mode string can also include the letter `'b''
  as the last character to indicate that the file is to be opened in
  binary mode.

  Upon success, `fopen' returns a File_Type object which is
  meant to be used by other operations that require an open file
  pointer.  Upon failure, the function returns NULL.

 EXAMPLE
  The following function opens a file in append mode and writes a
  string to it:

    define append_string_to_file (str, file)
    {
       variable fp = fopen (file, "a");
       if (fp == NULL)
         throw OpenError, "$file could not be opened"$;
       () = fputs (str, fp);
       () = fclose (fp);
    }

  Note that the return values from `fputs' and `fclose' were
  ignored.

 NOTES
  There is no need to explicitly close a file opened with `fopen'.
  If the returned File_Type object goes out of scope, the
  interpreter will automatically close the file.  However, explicitly
  closing a file with `fclose' and checking its return value is
  recommended.

 SEE ALSO
  fclose, fgets, fputs, popen

--------------------------------------------------------------

fprintf

 SYNOPSIS
  Create and write a formatted string to a file

 USAGE
  Int_Type fprintf (File_Type fp, String_Type fmt, ...)

 DESCRIPTION
  `fprintf' formats the objects specified by the variable argument
  list according to the format `fmt' and write the result to the
  open file pointer `fp'.

  The format string obeys the same syntax and semantics as the
  `sprintf' format string.  See the description of the
  `sprintf' function for more information.

  `fprintf' returns the number of bytes written to the file,
  or -1 upon error.

 SEE ALSO
  fputs, printf, fwrite, message

--------------------------------------------------------------

fputs

 SYNOPSIS
  Write a string to an open stream

 USAGE
  Integer_Type fputs (String_Type s, File_Type fp)

 DESCRIPTION
  The `fputs' function writes the string `s' to the open file
  pointer `fp'. It returns -1 upon failure and sets `errno',
  otherwise it returns the length of the string.

 EXAMPLE
  The following function opens a file in append mode and uses the
  `fputs' function to write to it.

    define append_string_to_file (str, file)
    {
       variable fp;
       fp = fopen (file, "a");
       if (fp == NULL)
         throw OpenError, "Unable to open $file"$;
       if ((-1 == fputs (s, fp))
           or (-1 == fclose (fp)))
         throw WriteError, "Error writing to $file"$;
    }


 NOTES
  One must not disregard the return value from the `fputs'
  function.  Doing so may lead to a stack overflow error.

  To write an object that contains embedded null characters, use the
  `fwrite' function.

 SEE ALSO
  fclose, fopen, fgets, fwrite

--------------------------------------------------------------

fputslines

 SYNOPSIS
  Write an array of strings to an open file

 USAGE
  Int_Type fputslines (String_Type[]a, File_Type fp)

 DESCRIPTION
  The `fputslines' function writes an array of strings to the
  specified file pointer.  It returns the number of elements
  successfully written.  Any NULL elements in the array will be
  skipped.

 EXAMPLE

    if (length (lines) != fputslines (lines, fp))
      throw WriteError;


 SEE ALSO
  fputs, fgetslines, fopen

--------------------------------------------------------------

fread

 SYNOPSIS
  Read binary data from a file

 USAGE
  UInt_Type fread (Ref_Type b, DataType_Type t, UInt_Type n, File_Type fp)

 DESCRIPTION
  The `fread' function may be used to read `n' objects of type
  `t' from an open file pointer `fp'.  Upon success, it
  returns the number of objects read from the file and places the
  objects in variable specified by `b'.  Upon error or
  end-of-file, it returns -1 and sets `errno' accordingly.

  If more than one object is read from the file, those objects will be
  placed in an array of the appropriate size.

 EXAMPLE
  The following example illustrates how to read 50 integers from a file:

     define read_50_ints_from_a_file (file)
     {
        variable fp, n, buf;

        fp = fopen (file, "rb");
        if (fp == NULL)
          throw OpenError;
        n = fread (&buf, Int_Type, 50, fp);
        if (n == -1)
          throw ReadError, "fread failed";
        () = fclose (fp);
        return buf;
     }


 NOTES
  Use the `pack' and `unpack' functions to read data with a
  specific byte-ordering.

  The `fread_bytes' function may be used to read a specified number of
  bytes in the form of a binary string (`BString_Type').

  If an attempt is made to read at the end of a file, the function
  will return -1.  To distinguish this condition from a system error,
  the `feof' function should be used.  This distinction is
  particularly important when reading from a socket or pipe.

 SEE ALSO
  fread_bytes, fwrite, fgets, feof, ferror, fopen, pack, unpack

--------------------------------------------------------------

fread_bytes

 SYNOPSIS
  Read bytes from a file as a binary-string

 USAGE
  UInt_Type fread_bytes (Ref_Type b, UInt_Type n, File_Type fp)

 DESCRIPTION
  The `fread_bytes' function may be used to read `n' bytes
  from from an open file pointer `fp'.  Upon success, it returns
  the number of bytes read from the file and assigns to the variable
  attached to the reference `b' a binary string formed from the
  bytes read.  Upon error or end of file, the function returns
  -1 and sets `errno' accordingly.

 NOTES
  Use the `pack' and `unpack' functions to read data with a
  specific byte-ordering.

 SEE ALSO
  fread, fwrite, fgets, fopen, pack, unpack

--------------------------------------------------------------

fseek

 SYNOPSIS
  Reposition a stdio stream

 USAGE
  Integer_Type fseek (File_Type fp, LLong_Type ofs, Integer_Type whence

 DESCRIPTION
  The `fseek' function may be used to reposition the file position
  pointer associated with the open file stream `fp'. Specifically,
  it moves the pointer `ofs' bytes relative to the position
  indicated by `whence'.  If `whence' is set to one of the symbolic
  constants SEEK_SET, SEEK_CUR, or SEEK_END, the
  offset is relative to the start of the file, the current position
  indicator, or end-of-file, respectively.

  The function returns 0 upon success, or -1 upon failure and sets
  `errno' accordingly.

 EXAMPLE
    define rewind (fp)
    {
       if (0 == fseek (fp, 0, SEEK_SET)) return;
       vmessage ("rewind failed, reason: %s", errno_string (errno));
    }

 SEE ALSO
  ftell, fopen

--------------------------------------------------------------

ftell

 SYNOPSIS
  Obtain the current position in an open stream

 USAGE
  LLong_Type ftell (File_Type fp)

 DESCRIPTION
  The ftell function may be used to obtain the current position in the
  stream associated with the open file pointer `fp'.  It returns
  the position of the pointer measured in bytes from the beginning of
  the file.  Upon error, it returns `-1' and sets `errno'
  accordingly.

 SEE ALSO
  fseek, fopen

--------------------------------------------------------------

fwrite

 SYNOPSIS
  Write binary data to a file

 USAGE
  UInt_Type fwrite (b, File_Type fp)

 DESCRIPTION
  The `fwrite' function may be used to write the object represented by
  `b' to an open file.  If `b' is a string or an array, the
  function will attempt to write all elements of the object to the
  file.  It returns the number of elements successfully written,
  otherwise it returns -1 upon error and sets `errno'
  accordingly.

 EXAMPLE
  The following example illustrates how to write an integer array to a
  file.  In this example, `fp' is an open file descriptor:

     variable a = [1:50];     % 50 element integer array
     if (50 != fwrite (a, fp))
       throw WriteError;

  Here is how to write the array one element at a time:

     variable ai, a = [1:50];

     foreach ai (a)
       {
          if (1 != fwrite(ai, fp))
            throw WriteError;
       }


 NOTES
  Not all data types may be supported the `fwrite' function.  It
  is supported by all vector, scalar, and string objects.

 SEE ALSO
  fread, fputs, fopen, pack, unpack

--------------------------------------------------------------

pclose

 SYNOPSIS
  Close a process pipe

 USAGE
  Integer_Type pclose (File_Type fp)

 DESCRIPTION
  The `pclose' function waits for the process associated with
  `fp' to exit and the returns the exit status of the command.

 SEE ALSO
  pclose, fclose

--------------------------------------------------------------

popen

 SYNOPSIS
  Open a pipe to a process

 USAGE
  File_Type popen (String_Type cmd, String_Type mode)

 DESCRIPTION
  The `popen' function executes a process specified by `cmd'
  and opens a unidirectional pipe to the newly created process.  The
  `mode' indicates whether or not the pipe is open for reading
  or writing.  Specifically, if `mode' is `"r"', then the
  pipe is opened for reading, or if `mode' is `"w"', then the
  pipe will be open for writing.

  Upon success, a File_Type pointer will be returned, otherwise
  the function failed and NULL will be returned.

 NOTES
  This function is not available on all systems.

 The `process' module's `new_process' function provides a
 much more secure and powerful interface to process I/O.

 SEE ALSO
  new_process, pclose, fopen

--------------------------------------------------------------

printf

 SYNOPSIS
  Create and write a formatted string to stdout

 USAGE
  Int_Type printf (String_Type fmt, ...)

 DESCRIPTION
  `printf' formats the objects specified by the variable argument
  list according to the format `fmt' and write the result to
  `stdout'.  This function is equivalent to `fprintf' used
  with the `stdout' file pointer.  See `fprintf' for more
  information.

  `printf' returns the number of bytes written or -1 upon error.

 NOTES
  Many C programmers do not check the return status of the
  `printf' C library function.  Make sure that if you do not care
  about whether or not the function succeeds, then code it as in the
  following example:

     () = printf ("%s laid %d eggs\n", chicken_name, num_egg);


 SEE ALSO
  fputs, fprintf, fwrite, message

--------------------------------------------------------------

count_char_occurrences

 SYNOPSIS
  Count the number of occurrences of a character in a string

 USAGE
  UInt_Type count_char_occurrences (str, ch)

 DESCRIPTION
  This function returns the number of times the specified character
  `ch' occurs in the string `str'.

 NOTES
  If UTF-8 mode is in effect, then the character may correspond to
  more than one byte.  In such a case, the function returns the number
  of such byte-sequences in the string.  To count actual bytes, use
  the `count_byte_occurrences' function.

 SEE ALSO
  count_byte_occurrences

--------------------------------------------------------------

create_delimited_string

 SYNOPSIS
  Concatenate strings using a delimiter

 USAGE
  String_Type create_delimited_string (delim, s_1, s_2, ..., s_n, n)

    String_Type delim, s_1, ..., s_n
    Int_Type n


 DESCRIPTION
  `create_delimited_string' performs a concatenation operation on
  the `n' strings `s_1', ...,`s_n', using the string
  `delim' as a delimiter.  The resulting string is equivalent to
  one obtained via

      s_1 + delim + s_2 + delim + ... + s_n


 EXAMPLE

    create_delimited_string ("/", "user", "local", "bin", 3);

  will produce `"usr/local/bin"'.

 NOTES
  New code should use the `strjoin' function, which performs a
  similar task.

 SEE ALSO
  strjoin, is_list_element, extract_element, strchop, strcat

--------------------------------------------------------------

extract_element

 SYNOPSIS
  Extract the nth element of a string with delimiters

 USAGE
  String_Type extract_element (String_Type list, Int_Type nth, Int_Type delim)

 DESCRIPTION
  The `extract_element' function may be used to extract the
  `nth' substring of a string delimited by the character given by
  the `delim' parameter.  If the string contains fewer than the
  requested substring, the function will return NULL.  Substring
  elements are numbered from 0.

 EXAMPLE
  The expression

     extract_element ("element 0, element 1, element 2", 1, ',')

  returns the string `" element 1"', whereas

     extract_element ("element 0, element 1, element 2", 1, ' ')

  returns `"0,"'.

  The following function may be used to compute the number of elements
  in the list:

     define num_elements (list, delim)
     {
        variable nth = 0;
        while (NULL != extract_element (list, nth, delim))
          nth++;
        return nth;
     }

  Alternatively, the `strchop' function may be more useful.  In
  fact, `extract_element' may be expressed in terms of the
  function `strchop' as

    define extract_element (list, nth, delim)
    {
       list = strchop(list, delim, 0);
       if (nth >= length (list))
         return NULL;
       else
         return list[nth];
    }

   and the `num_elements' function used above may be recoded more
   simply as:

    define num_elements (list, delim)
    {
       return length (strchop (length, delim, 0));
    }


 NOTES
  New code should make use of the `List_Type' object for lists.

 SEE ALSO
  is_list_element, is_substr, strtok, strchop, create_delimited_string

--------------------------------------------------------------

glob_to_regexp

 SYNOPSIS
  Convert a globbing expression to a regular expression

 USAGE
  String_Type glob_to_regexp (String_Type g)

 DESCRIPTION
  This function may be used to convert a so-called globbing expression
  to a regular expression.  A globbing expression is frequently used
  for matching filenames where '?' represents a single character and
  '*' represents 0 or more characters.

 NOTES
  The `slsh' program that is distributed with the S-Lang library
  includes a function called `glob' that is a wrapper around
  `glob_to_regexp' and `listdir'.  It returns a list of
  filenames matching a globbing expression.

 SEE ALSO
  string_match, listdir

--------------------------------------------------------------

is_list_element

 SYNOPSIS
  Test whether a delimited string contains a specific element

 USAGE
  Int_Type is_list_element (String_Type list, String_Type elem, Int_Type delim)

 DESCRIPTION
  The `is_list_element' function may be used to determine whether
  or not a delimited list of substring, `list', contains the element
  `elem'.  If `elem' is not an element of `list', the function
  will return zero, otherwise, it returns 1 plus the matching element
  number.

 EXAMPLE
  The expression

     is_list_element ("element 0, element 1, element 2", "0,", ' ');

  returns `2' since `"0,"' is element number one of the list
  (numbered from zero).

 SEE ALSO
  extract_element, is_substr, create_delimited_string

--------------------------------------------------------------

is_substr

 SYNOPSIS
  Test for a specified substring within a string

 USAGE
  Int_Type is_substr (String_Type a, String_Type b)

 DESCRIPTION
  This function may be used to determine if `a' contains the
  string `b'.  If it does not, the function returns 0; otherwise it
  returns the position of the first occurrence of `b' in `a'
  expressed in terms of characters, not bytes.

 NOTES
  This function regards the first character of a string to be given by
  a position value of 1.

  The distinction between characters and bytes is significant in UTF-8
  mode.

  This function has been vectorized in the sense that if an array of strings
  is  passed for either of the string-valued arguments, then a
  corresponding array of integers will be returned.  If two arrays
  are passed then the arrays must have the same length.

 SEE ALSO
  substr, string_match, strreplace

--------------------------------------------------------------

make_printable_string

 SYNOPSIS
  Format a string suitable for parsing

 USAGE
  String_Type make_printable_string(String_Type str)

 DESCRIPTION
  This function formats a string in such a way that it may be used as
  an argument to the `eval' function.  The resulting string is
  identical to `str' except that it is enclosed in double quotes
  and the backslash, newline, control, and double quote characters are
  expanded.

 SEE ALSO
  eval, str_quote_string

--------------------------------------------------------------

Sprintf

 SYNOPSIS
  Format objects into a string (deprecated)

 USAGE
  String_Type Sprintf (String_Type format, ..., Int_Type n)

 DESCRIPTION
  This function performs a similar task as the `sprintf'
  function but requires an additional argument that specifies the
  number of items to format.  For this reason, the `sprintf'
  function should be used.

 SEE ALSO
  sprintf, string, sscanf, vmessage

--------------------------------------------------------------

strbskipchar

 SYNOPSIS
  Get an index to the previous character in a UTF-8 encoded string

 USAGE
  (p1, wch) = strbskipchar (str, p0 [,skip_combining])

 DESCRIPTION
  This function moves backward from the 0-based byte-offset `p0'
  in the string `str' to the previous character in the string.
  It returns the byte-offset (`p1' of the previous character and
  the decoded character value at that byte-offset.

  The optional third argument specifies the handling of
  combining characters.  If it is non-zero, combining characters will
  be ignored, otherwise a combining character will not be treated
  differently from other characters.  The default is to ignore such
  characters.

  If the byte-offset `p0' corresponds to the end of the string
  (`p0=0'), then `(p0,0)' will be returned.  Otherwise if
  the byte-offset specifies a value that lies outside the string, an
  `IndexError' exception will be thrown.  Finally, if the
  byte-offset corresponds to an illegally coded character, the
  character returned will be the negative byte-value at the position.

 SEE ALSO
  strskipchar, strskipbytes

--------------------------------------------------------------

sprintf

 SYNOPSIS
  Format objects into a string

 USAGE
  String_Type sprintf (String fmt, ...)

 DESCRIPTION
  The `sprintf' function formats a string from a variable number
  of arguments according to according to the format specification
  string `fmt'.

  The format string is a C library `sprintf' style format
  descriptor.  Briefly, the format string may consist of ordinary
  characters (not including the `%' character), which are copied
  into the output string as-is, and conversion specification sequences
  introduced by the `%' character.  The number of additional
  arguments passed to the `sprintf' function must be consistent
  with the number required by the format string.

  The `%' character in the format string starts a conversion
  specification that indicates how an object is to be formatted.
  Usually the percent character is followed immediately by a
  conversion specification character.  However, it may optionally be
  followed by flag characters, field width characters, and precision
  modifiers, as described below.

  The character immediately following the `%' character may be
  one or more of the following flag characters:

    -         Use left-justification
    #         Use alternate form for formatting.
    0         Use 0 padding
    +         Preceed a number by a plus or minus sign.
    (space)   Use a blank instead of a plus sign.


  The flag characters (if any) may be followed by an optional field
  width specification string represented by one or more digit
  characters.  If the size of the formatted object is less than the
  field width, it will be right-justified in the specified field
  width, unless the `-' flag was given, in which case it will be
  left justified.

  If the next character in the control sequence is a period, then it
  introduces a precision specification sequence.  The precision is
  given by the digit characters following the period.  If none are
  given the precision is taken to be 0.  The meaning of the precision
  specifier depends upon the type of conversion:  For integer
  conversions, it gives the minimum number digits to appear in the
  output.  For `e' and `f' floating point conversions, it
  gives the number of digits to appear after the decimal point.  For
  the `g' floating point conversion, it gives the maximum number
  of significant digits to appear.  Finally for the `s' and
  `S' conversions it specifies the maximum number of characters
  to be copied to the output string.

  The next character in the sequence may be a modifier that controls
  the size of object to be formatted. It may consist of the following
  characters:

     h    This character is ignored in the current implementation.
     l    The integer is be formatted as a long integer, or a
          character as a wide character.


  Finally the conversion specification sequence ends with the
  conversion specification character that describes how the object is
  to be
  formatted:

     s    as a string
     f    as a floating point number
     e    as a float using exponential form, e.g., 2.345e08
     g    format as e or f, depending upon its value
     c    as a character
     b    as a byte
     %    a literal percent character
     d    as a signed decimal integer
     u    as an unsigned decimal integer
     o    as an octal integer
     X,x  as hexadecimal
     B    as a binary integer
     S    convert object to a string and format accordingly

  The `S' conversion specifier is a S-Lang extension which will
  cause the corresponding object to be converted to a string using the
  `string' function, and then converted as `s'. formatted as
  string.  In fact, `sprintf("%S",x)' is equivalent to
  `sprintf("%s",string(x))'.

 EXAMPLE

    sprintf("%s","hello")               ===> "hello"
    sprintf("%s %s","hello", "world")   ===> "hello world"
    sprintf("Agent %.3d",7)             ===> "Agent 007"
    sprintf("%S",PI)                    ===> "3.141592653589793"
    sprintf("%g",PI)                    ===> "3.14159"
    sprintf("%.2g",PI)                  ===> "3.1"
    sprintf("%.2e",PI)                  ===> "3.14e+00"
    sprintf("%.2f",PI)                  ===> "3.14"
    sprintf("|% 8.2f|",PI)              ===> "|    3.14|"
    sprintf("|%-8.2f|",PI)              ===> "|3.14    |"
    sprintf("|%+8.2f|",PI)              ===> "|   +3.14|"
    sprintf("|%8B|", 21)                ===> "|   10101|"
    sprintf("|%.8B|", 21)               ===> "|00010101|"
    sprintf("|%#.8B|", 21)              ===> "|0b00010101|"
    sprintf("%S",{1,2,3})               ===> "List_Type with 3 elements"
    sprintf("%S",1+2i)                  ===> "(1 + 2i)"


 NOTES
  The `set_float_format' function controls the format for the
  `S' conversion of floating point numbers.

 SEE ALSO
  string, sscanf, message, pack

--------------------------------------------------------------

sscanf

 SYNOPSIS
  Parse a formatted string

 USAGE
  Int_Type sscanf (s, fmt, r1, ... rN)

    String_Type s, fmt;
    Ref_Type r1, ..., rN


 DESCRIPTION
 The `sscanf' function parses the string `s' according to the
 format `fmt' and sets the variables whose references are given by
 `r1', ..., `rN'.  The function returns the number of
 references assigned, or throws an exception upon error.

 The format string `fmt' consists of ordinary characters and
 conversion specifiers.  A conversion specifier begins with the
 special character `%' and is described more fully below.  A white
 space character in the format string matches any amount of whitespace
 in the input string.  Parsing of the format string stops whenever a
 match fails.

 The `%' character is used to denote a conversion specifier whose
 general form is given by `%[*][width][type]format' where the
 brackets indicate optional items.  If `*' is present, then the
 conversion will be performed but no assignment to a reference will be
 made.  The `width' specifier specifies the maximum field width to
 use for the conversion.  The `type' modifier is used to indicate
 the size of the object, e.g., a short integer, as follows.

 If _type_ is given as the character `h', then if the format
 conversion is for an integer (`dioux'), the object assigned will
 be a short integer.  If _type_ is `l', then the conversion
 will be to a long integer for integer conversions, or to a double
 precision floating point number for floating point conversions.

 The format specifier is a character that specifies the conversion:

       %     Matches a literal percent character.  No assignment is
             performed.
       d     Matches a signed decimal integer.
       D     Matches a long decimal integer (equiv to `ld')
       u     Matches an unsigned decimal integer
       U     Matches an unsigned long decimal integer (equiv to `lu')
       i     Matches either a hexadecimal integer, decimal integer, or
             octal integer.
       I     Equivalent to `li'.
       x     Matches a hexadecimal integer.
       X     Matches a long hexadecimal integer (same as `lx').
       e,f,g Matches a decimal floating point number (Float_Type).
       E,F,G Matches a double precision floating point number, same as `lf'.
       s     Matches a string of non-whitespace characters (String_Type).
       c     Matches one character.  If width is given, width
             characters are matched.
       n     Assigns the number of characters scanned so far.
       [...] Matches zero or more characters from the set of characters
             enclosed by the square brackets.  If '^' is given as the
             first character, then the complement set is matched.


 EXAMPLE
 Suppose that `s' is `"Coffee: (3,4,12.4)"'.  Then

    n = sscanf (s, "%[a-zA-Z]: (%d,%d,%lf)", &item, &x, &y, &z);

 will set `n' to 4, `item' to `"Coffee"', `x' to 3,
 `y' to 4, and `z' to the double precision number
 `12.4'.  However,

    n = sscanf (s, "%s: (%d,%d,%lf)", &item, &x, &y, &z);

 will set `n' to 1, `item' to `"Coffee:"' and the
 remaining variables will not be assigned.

 SEE ALSO
  sprintf, unpack, string, atof, int, integer, string_matches

--------------------------------------------------------------

strbytelen

 SYNOPSIS
  Get the number of bytes in a string

 USAGE
  Int_Type strbytelen (String_Type s)

 DESCRIPTION
  This function returns the number of bytes in a string.  In UTF-8
  mode, this value is generally different from the number of
  characters in a string.  For the latter information, the
  `strlen' or `strcharlen' functions should be used.

 NOTES
  This function has been vectorized in the sense that if an array of strings
  is passed to the function, then a corresponding array of integers
  will be returned.

 SEE ALSO
  strlen, strcharlen, length

--------------------------------------------------------------

strbytesub

 SYNOPSIS
  Replace a byte with another in a string.

 USAGE
  String_Type strsub (String_Type s, Int_Type pos, UChar_Type b)

 DESCRIPTION
  The `strbytesub' function may be be used to substitute the byte
  `b' for the byte at byte position `pos' of the string
  `s'.  The resulting string is returned.

 NOTES
  The first byte in the string `s' is specified by `pos'
  equal to 1.  This function uses byte semantics, not character
  semantics.

 SEE ALSO
  strsub, is_substr, strreplace, strbytelen

--------------------------------------------------------------

strcat

 SYNOPSIS
  Concatenate strings

 USAGE
  String_Type strcat (String_Type a_1, ...,  String_Type a_N)

 DESCRIPTION
   The `strcat' function concatenates its N string
   arguments `a_1', ... `a_N' together and returns the result.

 EXAMPLE

    strcat ("Hello", " ", "World");

   produces the string `"Hello World"'.

 NOTES
   This function is equivalent to the binary operation `a_1+...+a_N'.
   However, `strcat' is much faster making it the preferred method
   to concatenate strings.

 SEE ALSO
  sprintf, strjoin

--------------------------------------------------------------

strcharlen

 SYNOPSIS
  Get the number of characters in a string including combining characters

 USAGE
  Int_Type strcharlen (String_Type s)

 DESCRIPTION
  The `strcharlen' function returns the number of characters in a
  string.  If the string contains combining characters, then they are
  also counted.  Use the `strlen' function to obtain the
  character count ignoring combining characters.

 NOTES
  This function has been vectorized in the sense that if an array of strings
  is passed to the function, then a corresponding array of integers
  will be returned.

 SEE ALSO
  strlen, strbytelen

--------------------------------------------------------------

strchop

 SYNOPSIS
  Chop or split a string into substrings.

 USAGE
  String_Type[] strchop (String_Type str, Int_Type delim, Int_Type quote)

 DESCRIPTION
   The `strchop' function may be used to split-up a string
   `str' that consists of substrings delimited by the character
   specified by `delim'.  If the integer `quote' is non-zero,
   it will be taken as a quote character for the delimiter.  The
   function returns the substrings as an array.

 EXAMPLE
   The following function illustrates how to sort a comma separated
   list of strings:

     define sort_string_list (a)
     {
        variable i, b, c;
        b = strchop (a, ',', 0);

        i = array_sort (b);
        b = b[i];   % rearrange

        % Convert array back into comma separated form
        return strjoin (b, ",");
     }


 SEE ALSO
  strchopr, strjoin, strtok

--------------------------------------------------------------

strchopr

 SYNOPSIS
  Chop or split a string into substrings.

 USAGE
  String_Type[] strchopr (String_Type str, String_Type delim, String_Type quote)

 DESCRIPTION
  This routine performs exactly the same function as `strchop' except
  that it returns the substrings in the reverse order.  See the
  documentation for `strchop' for more information.

 SEE ALSO
  strchop, strtok, strjoin

--------------------------------------------------------------

strcmp

 SYNOPSIS
  Compare two strings

 USAGE
  Int_Type strcmp (String_Type a, String_Type b)

 DESCRIPTION
  The `strcmp' function may be used to perform a case-sensitive
  string comparison, in the lexicographic sense, on strings `a'
  and `b'.  It returns 0 if the strings are identical, a negative
  integer if `a' is less than `b', or a positive integer if
  `a' is greater than `b'.

 EXAMPLE
  The `strup' function may be used to perform a case-insensitive
  string comparison:

    define case_insensitive_strcmp (a, b)
    {
      return strcmp (strup(a), strup(b));
    }


 NOTES
  One may also use one of the binary comparison operators, e.g.,
  `a > b'.

  This function has been vectorized in the sense that if an array of strings
  is passed to the function, then a corresponding array of integers
  will be returned.

 SEE ALSO
  strup, strncmp

--------------------------------------------------------------

strcompress

 SYNOPSIS
  Remove excess whitespace characters from a string

 USAGE
  String_Type strcompress (String_Type s, String_Type white)

 DESCRIPTION
  The `strcompress' function compresses the string `s' by
  replacing a sequence of one or more characters from the set
  `white' by the first character of `white'. In addition, it
  also removes all leading and trailing characters from `s' that
  are part of `white'.

 EXAMPLE
  The expression

    strcompress (",;apple,,cherry;,banana", ",;");

  returns the string `"apple,cherry,banana"'.

 NOTES
  This function has been vectorized in the sense that if an array of strings
  is passed as the first argument then a corresponding array of strings
  will be returned.  Array values are not supported for the remaining
  arguments.

 SEE ALSO
  strtrim, strtrans, str_delete_chars

--------------------------------------------------------------

string_match

 SYNOPSIS
  Match a string against a regular expression

 USAGE
  Int_Type string_match(String_Type str, String_Type pat [,Int_Type pos])

 DESCRIPTION
  The `string_match' function returns zero if `str' does not
  match regular expression specified by `pat'.  This function
  performs the match starting at the first byte of the string.  The
  optional `pos' argument may be used to specify a different byte
  offse (numbered from 1).  This function returns the position in
  bytes (numbered from 1) of the start of the match in `str'.
  The exact substring matched may be found using
  `string_match_nth'.

 NOTES
  Positions in the string are specified using byte-offsets not
  character offsets. The value returned by this function is measured
  from the beginning of the string `str'.

  The function is not yet UTF-8 aware.  If possible, consider using
  the `pcre' module for better, more sophisticated regular
  expressions.

  The `pos' argument was made optional in version 2.2.3.

 SEE ALSO
  string_matches, string_match_nth, strcmp, strncmp

--------------------------------------------------------------

string_match_nth

 SYNOPSIS
  Get the result of the last call to string_match

 USAGE
  (Int_Type pos, Int_Type len) = string_match_nth(Int_Type nth)

 DESCRIPTION
  The `string_match_nth' function returns two integers describing
  the result of the last call to `string_match'.  It returns both
  the zero-based byte-position of the `nth' submatch and
  the length of the match.

  By convention, `nth' equal to zero means the entire match.
  Otherwise, `nth' must be an integer with a value 1 through 9,
  and refers to the set of characters matched by the `nth' regular
  expression enclosed by the pairs `\(, \)'.

 EXAMPLE
  Consider:

     variable matched, pos, len;
     matched = string_match("hello world", "\([a-z]+\) \([a-z]+\)"R, 1);
     if (matched)
       (pos, len) = string_match_nth(2);

  This will set `matched' to 1 since a match will be found at the
  first byte position, `pos' to 6 since `w' is offset 6 bytes
  from the beginning of the string, and `len' to 5 since
  `"world"' is 5 bytes long.

 NOTES
  The position offset is _not_ affected by the value of the offset
  parameter to the `string_match' function. For example, if the
  value of the last parameter to the `string_match' function had
  been 3, `pos' would still have been set to 6.

  The `string_matches' function may be used as an alternative to
  `string_match_nth'.

 SEE ALSO
  string_match, string_matches

--------------------------------------------------------------

string_matches

 SYNOPSIS
  Match a string against a regular expression and return the matches

 USAGE
  String_Type[] string_matches(String_Type str, String_Type pat [,Int_Type pos])

 DESCRIPTION
  The `string_matches' function combines the functionality of
  `string_match' and `string_match_nth'.  Like
  `string_match', it matches the test string `str' against
  the regular expression `pat'.  If the string does not match the
  pattern the function will return NULL.  Otherwise, the function
  will return an array of strings whose `ith' element is the string that
  corresponds to the return value of the `string_match_nth'
  function.

 EXAMPLE

    strs = string_matches ("p0.5keV_27deg.dat",
                           "p\([0-9.]+\)keV_\([0-9.]+\)deg\.dat"R, 1);
    % ==> strs[0] = "p0.5keV_27deg.dat"
    %     strs[1] = "0.5"
    %     strs[2] = "27"

    strs = string_matches ("q0.5keV_27deg.dat",
                           "p\([0-9.]+\)keV_\([0-9.]+\)deg\.dat"R);
    % ==> strs = NULL


 NOTES
  The function is not yet UTF-8 aware.  If possible, consider using
  the `pcre' module for better, more sophisticated regular
  expressions.

  The `pos' argument was made optional in version 2.2.3.

 SEE ALSO
  string_match, string_match_nth, strcmp, strncmp

--------------------------------------------------------------

strjoin

 SYNOPSIS
  Concatenate elements of a string array

 USAGE
  String_Type strjoin (Array_Type a [, String_Type delim])

 DESCRIPTION
   The `strjoin' function operates on an array of strings by joining
   successive elements together separated with the optional delimiter
   `delim'.  If `delim' is not specified, then empty string
   `""' will be used resulting in a concatenation of the elements.

 EXAMPLE
   Suppose that

      days = ["Sun","Mon","Tue","Wed","Thu","Fri","Sat","Sun"];

   Then `strjoin (days,"+")' will produce
   `"Sun+Mon+Tue+Wed+Thu+Fri+Sat+Sun"'.  Similarly,
   `strjoin (["","",""], "X")' will produce `"XX"'.

 SEE ALSO
  strchop, strcat

--------------------------------------------------------------

strlen

 SYNOPSIS
  Compute the length of a string

 USAGE
  Int_Type strlen (String_Type a)

 DESCRIPTION
  The `strlen' function may be used to compute the character
  length of a string ignoring the presence of combining characters.
  The `strcharlen' function may be used to count combining
  characters as distinct characters.  For byte-semantics, use the
  `strbytelen' function.

 EXAMPLE
  After execution of

   variable len = strlen ("hello");

  `len' will have a value of `5'.

 NOTES
  This function has been vectorized in the sense that if an array of strings
  is passed to the function, then a corresponding array of integers
  will be returned.

 SEE ALSO
  strbytelen, strcharlen, bstrlen, length, substr

--------------------------------------------------------------

strlow

 SYNOPSIS
  Convert a string to lowercase

 USAGE
  String_Type strlow (String_Type s)

 DESCRIPTION
  The `strlow' function takes a string `s' and returns another
  string identical to `s' except that all upper case characters
  that are contained in `s' are converted converted to lower case.

 EXAMPLE
  The function

    define Strcmp (a, b)
    {
      return strcmp (strlow (a), strlow (b));
    }

  performs a case-insensitive comparison operation of two strings by
  converting them to lower case first.

 NOTES
  This function has been vectorized in the sense that if an array of strings
  is passed to the function, then a corresponding array of strings
  will be returned.

 SEE ALSO
  strup, tolower, strcmp, strtrim, define_case

--------------------------------------------------------------

strnbytecmp

 SYNOPSIS
  Compare the first n bytes of two strings

 USAGE
  Int_Type strnbytecmp (String_Type a, String_Type b, Int_Type n)

 DESCRIPTION
  This function compares the first `n' bytes of the strings
  `a' and `b'.  See the documentation for `strcmp' for
  information about the return value.

 NOTES
  This function has been vectorized in the sense that if an array of strings
  is  passed for either of the string-valued arguments, then a
  corresponding array of integers will be returned.  If two arrays
  are passed then the arrays must have the same length.

 SEE ALSO
  strncmp, strncharcmp, strcmp

--------------------------------------------------------------

strncharcmp

 SYNOPSIS
  Compare the first n characters of two strings

 USAGE
  Int_Type strncharcmp (String_Type a, String_Type b, Int_Type n)

 DESCRIPTION
  This function compares the first `n' characters of the strings
  `a' and `b' counting combining characters as distinct
  characters.  See the documentation for `strcmp' for information
  about the return value.

 NOTES
  This function has been vectorized in the sense that if an array of strings
  is  passed for either of the string-valued arguments, then a
  corresponding array of integers will be returned.  If two arrays
  are passed then the arrays must have the same length.

 SEE ALSO
  strncmp, strnbytecmp, strcmp

--------------------------------------------------------------

strncmp

 SYNOPSIS
  Compare the first few characters of two strings

 USAGE
  Int_Type strncmp (String_Type a, String_Type b, Int_Type n)

 DESCRIPTION
  This function behaves like `strcmp' except that it compares only the
  first `n' characters in the strings `a' and `b'.
  See the documentation for `strcmp' for information about the return
  value.

  In counting characters, combining characters are not counted,
  although they are used in the comparison.  Use the
  `strncharcmp' function if you want combining characters to be
  included in the character count.  The `strnbytecmp' function
  should be used to compare bytes.

 EXAMPLE
  The expression

     strncmp ("apple", "appliance", 3);

  will return zero since the first three characters match.

 NOTES
  This function uses character semantics.

  This function has been vectorized in the sense that if an array of strings
  is  passed for either of the string-valued arguments, then a
  corresponding array of integers will be returned.  If two arrays
  are passed then the arrays must have the same length.

 SEE ALSO
  strcmp, strlen, strncharcmp, strnbytecmp

--------------------------------------------------------------

strreplace

 SYNOPSIS
  Replace one or more substrings

 USAGE
  (new,n) = strreplace(a, b, c, max_n)
  % or
  new = strreplace(a, b, c)

 DESCRIPTION
  The `strreplace' function may be used to replace one or more
  occurrences of `b' in `a' with `c'.  This function
  supports two calling interfaces.

  The first form may be used to replace a specified number of
  substrings.  If `max_n' is positive, then the first
  `max_n' occurrences of `b' in `a' will be replaced.
  Otherwise, if `max_n' is negative, then the last
  `abs(max_n)' occurrences will be replaced. The function returns
  the resulting string and an integer indicating how many replacements
  were made.

  The second calling form may be used to replace all occurrences of
  `b' in `a' with `c'.  In this case, only the
  resulting string will be returned.

 EXAMPLE
  The following function illustrates how `strreplace' may be used
  to remove all occurrences of a specified substring:

     define delete_substrings (a, b)
     {
        return strreplace (a, b, "");
     }


 SEE ALSO
  is_substr, strsub, strtrim, strtrans, str_delete_chars

--------------------------------------------------------------

strskipbytes

 SYNOPSIS
  Skip a range of bytes in a byte string

 USAGE
  Int_Type strskipbytes (str, range [n0 [,nmax]])

   String_Type s;
   String_Type range;
   Int_Type n0, nmax;


 DESCRIPTION
  This function skips over a range of bytes in a string `str'.
  The byte range to be skipped is specified by the `range'
  parameter.  Optional start (`n0') and stop (`nmax')
  (0-based) parameters may be used to specifiy the part of the input
  string to be processed.  The function returns a 0-based offset from
  the beginning of the string where processing stopped.

  See the documentation for the `strtrans' function for the
  format of the range parameter.

 SEE ALSO
  strskipchar, strbskipchar, strtrans

--------------------------------------------------------------

strskipchar

 SYNOPSIS
  Get an index to the next character in a UTF-8 encoded string

 USAGE
  (p1, wch) = strskipchar (str, p0 [,skip_combining])

 DESCRIPTION
  This function decodes the character at the 0-based byte-offset `p0' in
  the string `str'.  It returns the byte-offset (`p1' of the next
  character in the string and the decoded character at byte-offset
  `p0'.

  The optional third argument specifies the handling of
  combining characters.  If it is non-zero, combining characters will
  be ignored, otherwise a combining character will not be treated
  differently from other characters.  The default is to ignore such
  characters.

  If the byte-offset `p0' corresponds to the end of the string,
  then `(p0,0)' will be returned.  Otherwise if the byte-offset
  specifies a value that lies outside the string, an `IndexError'
  exception will be thrown.  Finally, if the byte-offset corresponds
  to an illegally coded character, the character returned will be the
  negative byte-value at the position.

 EXAMPLE
  The following is an example of a function that skips alphanumeric
  characters and returns the new byte-offset.

    private define skip_word_chars (line, p)
    {
       variable p1 = p, ch;
       do
         {
            p = p1;
            (p1, ch) = strskipchar (line, p, 1);
          }
       while (isalnum(ch));
       return p;
    }


 NOTES
  In non-UTF-8 mode (`_slang_utf8_ok=0'), this function is
  equivalent to:

     define strskipchar (s, p)
     {
        if ((p < 0) || (p > strlen(s)))
          throw IndexError;
        if (p == strlen(s))
          return (p, s[p])
        return (p+1, s[p]);
     }

  It is important to understand that the above code relies upon
  byte-semantics, which are invalid for multi-byte characters.

 SEE ALSO
  strbskipchar, strskipbytes

--------------------------------------------------------------

strsub

 SYNOPSIS
  Replace a character with another in a string.

 USAGE
  String_Type strsub (String_Type s, Int_Type pos, Int_Type ch)

 DESCRIPTION
  The `strsub' function may be used to substitute the character
  `ch' for the character at character position `pos' of the string
  `s'.  The resulting string is returned.

 EXAMPLE

    define replace_spaces_with_comma (s)
    {
      variable n;
      while (n = is_substr (s, " "), n) s = strsub (s, n, ',');
      return s;
    }

  For uses such as this, the `strtrans' function is a better choice.

 NOTES
  The first character in the string `s' is specified by `pos'
  equal to 1.  This function uses character semantics, not byte
  semantics.

 SEE ALSO
  is_substr, strreplace, strlen

--------------------------------------------------------------

strtok

 SYNOPSIS
  Extract tokens from a string

 USAGE
  String_Type[] strtok (String_Type str [,String_Type white])

 DESCRIPTION
  `strtok' breaks the string `str' into a series of tokens
  and returns them as an array of strings.  If the second parameter
  `white' is present, then it specifies the set of characters
  that are to be regarded as whitespace when extracting the tokens,
  and may consist of the whitespace characters or a range of such
  characters. If the first character of `white' is `'^'',
  then the whitespace characters consist of all characters except
  those in `white'.  For example, if `white' is `"
  \t\n,;."', then those characters specify the whitespace
  characters.  However, if `white' is given by
  `"^a-zA-Z0-9_"', then any character is a whitespace character
  except those in the ranges `a-z', `A-Z', `0-9', and
  the underscore character.  To specify the hyphen character as a
  whitespace character, then it should be the first character of the
  whitespace string.  In addition to ranges, the whitespace specifier
  may also include character classes:

    \w matches a unicode "word" character, taken to be alphanumeric.
    \a alphabetic character, excluding digits
    \s matches whitespace
    \l matches lowercase
    \u matches uppercase
    \d matches a digit
    \\ matches a backslash
    \^ matches a ^ character


  If the second parameter is not present, then it defaults to
  `"\s"'.

 EXAMPLE
  The following example may be used to count the words in a text file:

    define count_words (file)
    {
       variable fp, line, count;

       fp = fopen (file, "r");
       if (fp == NULL) return -1;

       count = 0;
       while (-1 != fgets (&line, fp))
         {
           line = strtok (line, "^\\a");
           count += length (line);
         }
       () = fclose (fp);
       return count;
    }

  Here a word was assumed to consist only of alphabetic characters.

 SEE ALSO
  strchop, strcompress, strjoin

--------------------------------------------------------------

strtrans

 SYNOPSIS
  Replace characters in a string

 USAGE
  String_Type strtrans (str, old_set, new_set)

   String_Type str, old_set, new_set;


 DESCRIPTION
  The `strtrans' function may be used to replace all the characters
  from the set `old_set' with the corresponding characters from
  `new_set' in the string `str'.  If `new_set' is empty,
  then the characters in `old_set' will be removed from `str'.

  If `new_set' is not empty, then `old_set' and
  `new_set' must be commensurate.  Each set may consist of
  character ranges such as `A-Z' and character classes:

    \, matches a punctuation character
    \7 matches any 7bit ascii character
    \\ matches a backslash
    \^ matches the ^ character
    \a matches an alphabetic character, excluding digits
    \c matches a control character
    \d matches a digit
    \g matches a graphic character
    \l matches lowercase
    \p matches a printable character
    \s matches whitespace
    \u matches uppercase
    \w matches a unicode "word" character, taken to be alphanumeric.
    \x matches hex digit (a-fA-F0-9)

  If the first character of a set is `^' then the set is taken to
  be the complement set.

 EXAMPLE

    str = strtrans (str, "\\u", "\\l");   % lower-case str
    str = strtrans (str, "^0-9", " ");    % Replace anything but 0-9 by space
    str = strtrans (str, "\\^0-9", " ");  % Replace '^' and 0-9 by a space


 NOTES
  This function has been vectorized in the sense that if an array of strings
  is passed as the first argument then a corresponding array of strings
  will be returned.  Array values are not supported for the remaining
  arguments.

 SEE ALSO
  strreplace, strtrim, strup, strlow

--------------------------------------------------------------

strtrim

 SYNOPSIS
  Remove whitespace from the ends of a string

 USAGE
  String_Type strtrim (String_Type s [,String_Type w])

 DESCRIPTION
  The `strtrim' function removes all leading and trailing whitespace
  characters from the string `s' and returns the result.  The
  optional second parameter specifies the set of whitespace
  characters.  If the argument is not present, then the set defaults
  to `"\s"'.  The whitespace specification may consist of
  character ranges such as `A-Z' and character classes:

    \w matches a unicode "word" character, taken to be alphanumeric.
    \a alphabetic character, excluding digits
    \s matches whitespace
    \l matches lowercase
    \u matches uppercase
    \d matches a digit
    \\ matches a backslash
    \^ matches a ^ character

  If the first character of a set is `^' then the set is taken to
  be the complement set.

 NOTES
  This function has been vectorized in the sense that if the first argument
  is an array of strings, then a corresponding array of strings
  will be returned.  An array value for the optional whitespace
  argument is not supported.

 SEE ALSO
  strtrim_beg, strtrim_end, strcompress

--------------------------------------------------------------

strtrim_beg

 SYNOPSIS
  Remove leading whitespace from a string

 USAGE
  String_Type strtrim_beg (String_Type s [,String_Type w])

 DESCRIPTION
  The `strtrim_beg' function removes all leading whitespace
  characters from the string `s' and returns the result.
  The optional second parameter specifies the set of whitespace
  characters.  See the documentation for the `strtrim' function
  form more information about the whitespace parameter.

 NOTES
  This function has been vectorized in the sense that if the first argument
  is an array of strings, then a corresponding array of strings
  will be returned.  An array value for the optional whitespace
  argument is not supported.

 SEE ALSO
  strtrim, strtrim_end, strcompress

--------------------------------------------------------------

strtrim_end

 SYNOPSIS
  Remove trailing whitespace from a string

 USAGE
  String_Type strtrim_end (String_Type s [,String_Type w])

 DESCRIPTION
  The `strtrim_end' function removes all trailing whitespace
  characters from the string `s' and returns the result.  The
  optional second parameter specifies the set of whitespace
  characters.  See the documentation for the `strtrim' function
  form more information about the whitespace parameter.

 NOTES
  This function has been vectorized in the sense that if the first argument
  is an array of strings, then a corresponding array of strings
  will be returned.  An array value for the optional whitespace
  argument is not supported.

 SEE ALSO
  strtrim, strtrim_beg, strcompress

--------------------------------------------------------------

strup

 SYNOPSIS
  Convert a string to uppercase

 USAGE
  String_Type strup (String_Type s)

 DESCRIPTION
  The `strup' function takes a string `s' and returns another
  string identical to `s' except that all lower case characters
  that contained in `s' are converted to upper case.

 EXAMPLE
  The function

    define Strcmp (a, b)
    {
      return strcmp (strup (a), strup (b));
    }

  performs a case-insensitive comparison operation of two strings by
  converting them to upper case first.

 NOTES
  This function has been vectorized in the sense that if an array of strings
  is passed to the function, then a corresponding array of strings
  will be returned.

 SEE ALSO
  strlow, toupper, strcmp, strtrim, define_case, strtrans

--------------------------------------------------------------

str_delete_chars

 SYNOPSIS
  Delete characters from a string

 USAGE
  String_Type str_delete_chars (String_Type str [, String_Type del_set])

 DESCRIPTION
  This function may be used to delete the set of characters specified
  by the optional argument `del_set' from the string `str'.
  If `del_set' is not given, `"\s"' will be used.
  The modified string is returned.

  The set of characters to be deleted may include ranges such as
  `A-Z' and characters classes:

    \w matches a unicode "word" character, taken to be alphanumeric.
    \a alphabetic character, excluding digits
    \s matches whitespace
    \l matches lowercase
    \u matches uppercase
    \d matches a digit
    \\ matches a backslash
    \^ matches a ^ character

  If the first character of `del_set' is `^', then the set
  is taken to be the complement of the remaining string.

 EXAMPLE

    str = str_delete_chars (str, "^A-Za-z");

  will remove all characters except `A-Z' and `a-z' from
  `str'.  Similarly,

    str = str_delete_chars (str, "^\\a");

  will remove all but the alphabetic characters.

 NOTES
  This function has been vectorized in the sense that if an array of strings
  is passed as the first argument then a corresponding array of strings
  will be returned.  Array values are not supported for the remaining
  arguments.

 SEE ALSO
  strtrans, strreplace, strcompress

--------------------------------------------------------------

str_quote_string

 SYNOPSIS
  Escape characters in a string.

 USAGE
  String_Type str_quote_string(String_Type str, String_Type qlis, Int_Type quote)

 DESCRIPTION
  The `str_quote_string' returns a string identical to `str'
  except that all characters contained in the string `qlis' are
  escaped with the `quote' character, including the quote
  character itself.  This function is useful for making a string that
  can be used in a regular expression.

 EXAMPLE
  Execution of the statements

   node = "Is it [the coat] really worth $100?";
   tag = str_quote_string (node, "\\^$[]*.+?", '\\');

  will result in `tag' having the value:

    Is it \[the coat\] really worth \$100\?


 SEE ALSO
  str_uncomment_string, make_printable_string

--------------------------------------------------------------

str_replace

 SYNOPSIS
  Replace a substring of a string (deprecated)

 USAGE
  Int_Type str_replace (String_Type a, String_Type b, String_Type c)

 DESCRIPTION
  The `str_replace' function replaces the first occurrence of `b' in
  `a' with `c' and returns an integer that indicates whether a
  replacement was made.  If `b' does not occur in `a', zero is
  returned.  However, if `b' occurs in `a', a non-zero integer is
  returned as well as the new string resulting from the replacement.

 NOTES
  This function has been superceded by `strreplace'.  It should no
  longer be used.

 SEE ALSO
  strreplace

--------------------------------------------------------------

str_uncomment_string

 SYNOPSIS
  Remove comments from a string

 USAGE
  String_Type str_uncomment_string(String_Type s, String_Type beg, String_Type end)

 DESCRIPTION
  This function may be used to remove simple forms of comments from a
  string `s'. The parameters, `beg' and `end', are strings
  of equal length whose corresponding characters specify the begin and
  end comment characters, respectively.  It returns the uncommented
  string.

 EXAMPLE
  The expression

     str_uncomment_string ("Hello (testing) 'example' World", "'(", "')")

  returns the string `"Hello   World"'.

 NOTES
  This routine does not handle multi-character comment delimiters and it
  assumes that comments are not nested.

 SEE ALSO
  str_quote_string, str_delete_chars, strtrans

--------------------------------------------------------------

substr

 SYNOPSIS
  Extract a substring from a string

 USAGE
  String_Type substr (String_Type s, Int_Type n, Int_Type len)

 DESCRIPTION
  The `substr' function returns a substring with character length
  `len' of the string `s' beginning at the character position
  `n'.  If `len' is `-1', the entire length of the string
  `s' will be used for `len'.  The first character of `s'
  is given by `n' equal to 1.

 EXAMPLE

     substr ("To be or not to be", 7, 5);

  returns `"or no"'

 NOTES
  In many cases it is more convenient to use array indexing rather
  than the `substr' function.  In fact, if UTF-8 mode is not in
  effect, `substr(s,i+1,strlen(s))' is equivalent to
  `s[[i:]]'.  Array indexing uses byte-semantics, not character
  semantics assumed by the `substr' function.

 SEE ALSO
  is_substr, substrbytes, strlen

--------------------------------------------------------------

substrbytes

 SYNOPSIS
  Extract a byte sequence from a string

 USAGE
  String_Type substrbytes (String_Type s, Int_Type n, Int_Type len)

 DESCRIPTION
  The `substrbytes' function returns a substring with byte length
  `len' of the string `s' beginning at the byte position
  `n', counting from 1.  If `len' is `-1', the entire
  byte-length of the string `s' will be used for `len'.  The first
  byte of `s' is given by `n' equal to 1.

 EXAMPLE

     substrbytes ("To be or not to be", 7, 5);

  returns `"or no"'

 NOTES
  In many cases it is more convenient to use array indexing rather
  than the `substr' function.  In fact
  `substrbytes(s,i+1,-1)' is equivalent to
  `s[[i:]]'.

  The function `substr' may be used if character semantics are
  desired.

 SEE ALSO
  substr, strbytelen

--------------------------------------------------------------

__add_binary

 SYNOPSIS
  Extend a binary operation to a user defined type

 USAGE
  __add_binary(op, return_type, binary_funct, lhs_type, rhs_type)

   String_Type op;
   Ref_Type binary_funct;
   DataType_Type return_type, lhs_type, rhs_type;


 DESCRIPTION
  The `__add_binary' function is used to specify a function to be
  called when a binary operation takes place between specified data
  types.  The first parameter indicates the binary operator and must
  be one of the following:

   "+", "-", "*", "/", "==", "!=", ">", ">=", "<", "<=", "^",
   "or", "and", "&", "|", "xor", "shl", "shr", "mod"

  The second parameter (`binary_funct') specifies the function to
  be called when the binary function takes place between the
  types `lhs_type' and `rhs_type'.  The `return_type'
  parameter stipulates the return values of the function and the data
  type of the result of the binary operation.

  The data type for `lhs_type' or `rhs_type' may be left
  unspecified by using Any_Type for either of these values.
  However, at least one of the parameters must correspond to a
  user-defined datatype.

 EXAMPLE
  This example defines a vector data type and extends the "*" operator
  to the new type:

    typedef struct { x, y, z } Vector_Type;
    define vector (x, y, z)
    {
       variable v = @Vector_Type;
       v.x = x;
       v.y = y;
       v.z = z;
       return v;
    }
    static define vector_scalar_mul (v, a)
    {
       return vector (a*v.x, a*v.y, a*v.z);
    }
    static define scalar_vector_mul (a, v)
    {
       return vector_scalar_mul (v, a);
    }
    static define dotprod (v1,v2)
    {
       return v1.x*v2.x + v1.y*v2.y + v1.z*v2.z;
    }
    __add_binary ("*", Vector_Type, &scalar_vector_mul, Any_Type, Vector_Type);
    __add_binary ("*", Vector_Type, &scalar_vector_mul, Any_Type, Vector_Type);
    __add_binary ("*", Double_Type, &dotprod, Vector_Type, Vector_Type);


 SEE ALSO
  __add_unary, __add_string, __add_destroy

--------------------------------------------------------------

__add_string

 SYNOPSIS
  Specify a string representation for a user-defined type

 USAGE
  __add_string (DataType_Type user_type, Ref_Type func)

 DESCRIPTION
  The `__add_string' function specifies a function to be called
  when a string representation is required for the specified
  user-defined datatype.

 EXAMPLE
  Consider the `Vector_Type' object defined in the example
  for the `__add_binary' function.

     static define vector_string (v)
     {
        return sprintf ("[%S,%S,%S]", v.x, v.y, v.z);
     }
     __add_string (Vector_Type, &vector_string);

  Then

     v = vector (3, 4, 5);
     vmessage ("v=%S", v);

  will generate the message:

     v=[3,4,5]


 SEE ALSO
  __add_unary, __add_binary, __add_destroy, __add_typecast

--------------------------------------------------------------

__add_typecast

 SYNOPSIS
  Add a typecast-function for a user-defined type

 USAGE
  __add_typecast (DataType_Type user_type, DataType_Type totype, Ref_Type func)

 DESCRIPTION
  The `__add_typecast' function specifies a function to be called
  to typecast the user-defined type to an object of type
  `totype'.  The function must be defined to take a single
  argument (the user-type to be converted) and must return an object
  of type `totype'.

 SEE ALSO
  __add_unary, __add_binary, __add_destroy, __add_string

--------------------------------------------------------------

__add_unary

 SYNOPSIS
  Extend a unary operator to a user-defined type

 USAGE
  __add_unary (op, return_type, unary_func, user_type)

   String_Type op;
   Ref_Type unary_func;
   DataType_Type return_type, user_type;


 DESCRIPTION
  The `__add_unary' function is used to define the action of an
  unary operation on a user-defined type.  The first parameter
  `op' must be a valid unary operator

   "-", "not", "~"

  or one of the following:

   "++", "--",
   "abs", "sign", "sqr", "mul2", "_ispos", "_isneg", "_isnonneg",

  The third parameter, `unary_func' specifies the function to be
  called to carry out the specified unary operation on the data type
  `user_type'.  The result of the operation is indicated by the
  value of the `return_type' parameter and must also be the
  return type of the unary function.

 EXAMPLE
  The example for the `__add_binary' function defined a
  `Vector_Type' object.  Here, the unary `"-"' and
  `"abs"' operators are
  extended to this type:

   static define vector_chs (v)
   {
      variable v1 = @Vector_Type;
      v1.x = -v.x;
      v1.y = -v.y;
      v1.z = -v.z;
      return v1;
   }
   static define vector_abs (v)
   {
      return sqrt (v.x*v.x + v.y*v.y + v.z*v.z);
   }
   __add_unary ("-", Vector_Type, &vector_chs, Vector_Type);
   __add_unary ("abs", Double_Type, &vector_abs, Vector_Type);


 SEE ALSO
  __add_binary, __add_string, __add_destroy

--------------------------------------------------------------

get_struct_field

 SYNOPSIS
  Get the value associated with a structure field

 USAGE
  x = get_struct_field (Struct_Type s, String field_name)

 DESCRIPTION
   The `get_struct_field' function gets the value of the field
   whose name is specified by `field_name' of the structure `s'.

 SEE ALSO
  set_struct_field, get_struct_field_names, array_info

--------------------------------------------------------------

get_struct_field_names

 SYNOPSIS
  Retrieve the field names associated with a structure

 USAGE
  String_Type[] = get_struct_field_names (Struct_Type s)

 DESCRIPTION
   The `get_struct_field_names' function returns an array of
   strings whose elements specify the names of the fields of the
   struct `s'.

 EXAMPLE
   The following example illustrates how the
   `get_struct_field_names' function may be used in conjunction
   with the `get_struct_field' function to print the
   value of a structure.

      define print_struct (s)
      {
         variable name, value;

         foreach (get_struct_field_names (s))
           {
             name = ();
             value = get_struct_field (s, name);
             vmessage ("s.%s = %s\n", name, string (value));
           }
      }


 SEE ALSO
  _push_struct_field_values, get_struct_field

--------------------------------------------------------------

is_struct_type

 SYNOPSIS
  Determine whether or not an object is a structure

 USAGE
  Integer_Type is_struct_type (X)

 DESCRIPTION
  The `is_struct_type' function returns 1 if the parameter
  refers to a structure or a user-defined type.  If the object is
  neither, 0 will be returned.

 SEE ALSO
  typeof, _typeof, _is_struct_type

--------------------------------------------------------------

_push_struct_field_values

 SYNOPSIS
  Push the values of a structure's fields onto the stack

 USAGE
  Integer_Type num = _push_struct_field_values (Struct_Type s)

 DESCRIPTION
  The `_push_struct_field_values' function pushes the values of
  all the fields of a structure onto the stack, returning the
  number of items pushed.  The fields are pushed such that the last
  field of the structure is pushed first.

 SEE ALSO
  get_struct_field_names, get_struct_field

--------------------------------------------------------------

set_struct_field

 SYNOPSIS
  Set the value associated with a structure field

 USAGE
  set_struct_field (s, field_name, field_value)

   Struct_Type s;
   String_Type field_name;
   Generic_Type field_value;


 DESCRIPTION
   The `set_struct_field' function sets the value of the field
   whose name is specified by `field_name' of the structure
   `s' to `field_value'.

 SEE ALSO
  get_struct_field, get_struct_field_names, set_struct_fields, array_info

--------------------------------------------------------------

set_struct_fields

 SYNOPSIS
  Set the fields of a structure

 USAGE
  set_struct_fields (Struct_Type s, ...)

 DESCRIPTION
  The `set_struct_fields' function may be used to set zero or more
  fields of a structure.  The fields are set in the order in which
  they were created when the structure was defined.

 EXAMPLE

    variable s = struct { name, age, height };
    set_struct_fields (s, "Bill", 13, 64);


 SEE ALSO
  set_struct_field, get_struct_field_names

--------------------------------------------------------------

ctime

 SYNOPSIS
  Convert a calendar time to a string

 USAGE
  String_Type ctime(Long_Type secs)

 DESCRIPTION
  This function returns a string representation of the time as given
  by `secs' seconds since 00:00:00 UTC, Jan 1, 1970.

 SEE ALSO
  time, strftime, _time, localtime, gmtime

--------------------------------------------------------------

gmtime

 SYNOPSIS
  Break down a time in seconds to the GMT timezone

 USAGE
  Struct_Type gmtime (Long_Type secs)

 DESCRIPTION
  The `gmtime' function is exactly like `localtime' except
  that the values in the structure it returns are with respect to GMT
  instead of the local timezone.  See the documentation for
  `localtime' for more information.

 NOTES
  On systems that do not support the `gmtime' C library function,
  this function is the same as `localtime'.

 SEE ALSO
  localtime, _time, mktime

--------------------------------------------------------------

localtime

 SYNOPSIS
  Break down a time in seconds to the local timezone

 USAGE
  Struct_Type localtime (Long_Type secs)

 DESCRIPTION
  The `localtime' function takes a parameter `secs'
  representing the number of seconds since 00:00:00, January 1 1970
  UTC and returns a structure containing information about `secs'
  in the local timezone.  The structure contains the following
  Int_Type fields:

  `tm_sec' The number of seconds after the minute, normally
     in the range 0 to 59, but can be up to 61 to allow for
     leap seconds.

  `tm_min' The number of minutes after the hour, in the
     range 0 to 59.

  `tm_hour' The number of hours past midnight, in the range
     0 to 23.

  `tm_mday' The day of the month, in the range 1 to 31.

  `tm_mon' The number of months since January, in the range
     0 to 11.

  `tm_year' The number of years since 1900.

  `tm_wday' The number of days since Sunday, in the range 0
     to 6.

  `tm_yday' The number of days since January 1, in the
     range 0 to 365.

  `tm_isdst' A flag that indicates whether daylight saving
     time is in effect at the time described.  The value is
     positive if daylight saving time is in effect, zero if it
     is not, and negative if the information is not available.

 SEE ALSO
  gmtime, _time, ctime, mktime

--------------------------------------------------------------

mktime

 SYNOPSIS
  Convert a time-structure to seconds

 USAGE
  secs = mktime (Struct_Type tm)

 DESCRIPTION
  The `mktime' function is essentially the inverse of the
  `localtime' function.  See the documentation for that function
  for more details.

 SEE ALSO
  localtime, gmtime, _time

--------------------------------------------------------------

strftime

 SYNOPSIS
  Format a date and time string

 USAGE
  str = strftime (String_Type format [,Struct_Type tm])

 DESCRIPTION
  The `strftime' creates a date and time string according to a
  specified format.  If called with a single argument, the current
  local time will be used as the reference time.  If called with two
  arguments, the second argument specifies the reference time, and
  must be a structure with the same fields as the structure returned
  by the `localtime' function.

  The format string may be composed of one or more of the following
  format descriptors:

       %A      full weekday name (Monday)
       %a      abbreviated weekday name (Mon)
       %B      full month name (January)
       %b      abbreviated month name (Jan)
       %c      standard date and time representation
       %d      day-of-month (01-31)
       %H      hour (24 hour clock) (00-23)
       %I      hour (12 hour clock) (01-12)
       %j      day-of-year (001-366)
       %M      minute (00-59)
       %m      month (01-12)
       %p      local equivalent of AM or PM
       %S      second (00-59)
       %U      week-of-year, first day Sunday (00-53)
       %W      week-of-year, first day Monday (00-53)
       %w      weekday (0-6, Sunday is 0)
       %X      standard time representation
       %x      standard date representation
       %Y      year with century
       %y      year without century (00-99)
       %Z      timezone name
       %%      percent sign

 as well as any others provided by the C library.  The actual values
 represented by the format descriptors are locale-dependent.

 EXAMPLE

    message (strftime ("Today is %A, day %j of the year"));
    tm = localtime (0);
    message (strftime ("Unix time 0 was on a %A", tm));


 SEE ALSO
  localtime, time

--------------------------------------------------------------

_tic

 SYNOPSIS
  Reset the CPU timer

 USAGE
  _tic ()

 DESCRIPTION
  The `_tic' function resets the internal CPU timer.  The
 `_toc' may be used to read this timer.  See the documentation
 for the `_toc' function for more information.

 SEE ALSO
  _toc, times, tic, toc

--------------------------------------------------------------

tic

 SYNOPSIS
  Reset the interval timer

 USAGE
  void tic ()

 DESCRIPTION
  The `tic' function resets the internal interval timer.  The
 `toc' may be used to read the interval timer.

 EXAMPLE
  The tic/toc functions may be used to measure execution times.  For
 example, at the `slsh' prompt, they may be used to measure the speed
 of a loop:

   slsh> tic; loop (500000); toc;
   0.06558


 NOTES
  On Unix, this timer makes use of the C library `gettimeofday'
  function.

 SEE ALSO
  toc, times

--------------------------------------------------------------

_time

 SYNOPSIS
  Get the current calendar time in seconds

 USAGE
  Long_Type _time ()

 DESCRIPTION
  The `_time' function returns the number of elapsed seconds since
  00:00:00 UTC, January 1, 1970.  A number of functions (`ctime',
  `gmtime', `localtime', etc.) are able to convert such a
  value to other representations.

 SEE ALSO
  ctime, time, localtime, gmtime

--------------------------------------------------------------

time

 SYNOPSIS
  Return the current date and time as a string

 USAGE
  String_Type time ()

 DESCRIPTION
  This function returns the current time as a string of the form:

    Sun Apr 21 13:34:17 1996


 SEE ALSO
  strftime, ctime, message, substr

--------------------------------------------------------------

timegm

 SYNOPSIS
  Convert a time structure for the GMT timezone to seconds

 USAGE
  Long_Type secs = timegm(Struct_Type tm)

 DESCRIPTION
  `timegm' is the inverse of the `gmtime' function.

 SEE ALSO
  gmtime, mktime, localtime

--------------------------------------------------------------

times

 SYNOPSIS
  Get process times

 USAGE
  Struct_Type times ()

 DESCRIPTION
  The `times' function returns a structure containing the
  following fields:

    tms_utime     (user time)
    tms_stime     (system time)
    tms_cutime    (user time of child processes)
    tms_cstime    (system time of child processes)


 NOTES
  Not all systems support this function.

 SEE ALSO
  _tic, _toc, _time

--------------------------------------------------------------

_toc

 SYNOPSIS
  Get the elapsed CPU time for the current process

 USAGE
  Double_Type _toc ()

 DESCRIPTION
  The `_toc' function returns the elapsed CPU time in seconds since
  the last call to `_tic'.  The CPU time is the amount of time the
  CPU spent running the code of the current process.

 NOTES
  This function may not be available on all systems.

  The implementation of this function is based upon the `times'
  system call.  The precision of the clock is system dependent and may
  not be very accurate for small time intervals.  For this reason, the
  tic/toc functions may be more useful for small time-intervals.

 SEE ALSO
  _tic, _tic, _toc, times, _time

--------------------------------------------------------------

toc

 SYNOPSIS
  Read the interval timer

 USAGE
  Double_Type toc ()

 DESCRIPTION
  The `toc' function returns the elapsed time in seconds since
  the last call to `tic'.  See the documentation for the
 `tic' function for more information.

 SEE ALSO
  tic, _tic, _toc, times, _time

--------------------------------------------------------------

atof

 SYNOPSIS
  Convert a string to a double precision number

 USAGE
  Double_Type atof (String_Type s)

 DESCRIPTION
  This function converts a string `s' to a double precision value
  and returns the result.  It performs no error checking on the format
  of the string.  The function `_slang_guess_type' may be used to
  check the syntax of the string.

 EXAMPLE

     define error_checked_atof (s)
     {
        if (__is_datatype_numeric (_slang_guess_type (s)))
          return atof (s);
        throw InvalidParmError, "$s is not a double"$;
    }


 SEE ALSO
  typecast, double, _slang_guess_type

--------------------------------------------------------------

atoi

 SYNOPSIS
  Convert a string to an integer

 USAGE
  Int_Type atoi (String_Type str)

 DESCRIPTION
  The `atoi' function converts a string to an `Int_Type'
  using the standard C library function of the corresponding name.

 NOTES
  This function performs no syntax checking upon its argument.

 SEE ALSO
  integer, atol, atoll, atof, sscanf

--------------------------------------------------------------

atol

 SYNOPSIS
  Convert a string to an long integer

 USAGE
  Long_Type atol (String_Type str)

 DESCRIPTION
  The `atol' function converts a string to a `Long_Type'
  using the standard C library function of the corresponding name.

 NOTES
  This function performs no syntax checking upon its argument.

 SEE ALSO
  integer, atoi, atoll, atof, sscanf

--------------------------------------------------------------

atoll

 SYNOPSIS
  Convert a string to a long long

 USAGE
  LLong_Type atoll (String_Type str)

 DESCRIPTION
  The `atoll' function converts a string to a `LLong_Type'
  using the standard C library function of the corresponding name.

 NOTES
  This function performs no syntax checking upon its argument.  Not
  all platforms provide support for the long long data type.

 SEE ALSO
  integer, atoi, atol, atof, sscanf

--------------------------------------------------------------

char

 SYNOPSIS
  Convert a character code to a string

 USAGE
  String_Type char (Integer_Type c)

 DESCRIPTION
  The `char' function converts an integer character code (ascii)
  value `c' to a string of unit character length such that the
  first character of the string is `c'.  For example,
  `char('a')' returns the string `"a"'.

  If UTF-8 mode is in effect  (`_slang_utf8_ok' is non-zero), the
  resulting single character may be represented by several bytes.

  If the character code `c' is less than 0, then byte-semantics
  will be used with the resulting string consisting of a single byte
  whose value is that of `-c&0xFF'.

 NOTES
  A better name should have been chosen for this function.

 SEE ALSO
  integer, string, typedef, sprintf, pack

--------------------------------------------------------------

define_case

 SYNOPSIS
  Define upper-lower case conversion

 USAGE
  define_case (Integer_Type ch_up, Integer_Type ch_low)

 DESCRIPTION
  This function defines an upper and lowercase relationship between two
  characters specified by the arguments.  This relationship is used by
  routines which perform uppercase and lowercase conversions.
  The first integer `ch_up' is the ascii value of the uppercase character
  and the second parameter `ch_low' is the ascii value of its
  lowercase counterpart.

 NOTES
  This function has no effect in UTF-8 mode.

 SEE ALSO
  strlow, strup

--------------------------------------------------------------

double

 SYNOPSIS
  Convert an object to double precision

 USAGE
  Double_Type double (x)

 DESCRIPTION
  The `double' function typecasts an object `x' to double
  precision.  For example, if `x' is an array of integers, an
  array of double types will be returned.  If an object cannot be
  converted to `Double_Type', a type-mismatch error will result.

 NOTES
  The `double' function is equivalent to the typecast operation

     typecast (x, Double_Type)

  To convert a string to a double precision number, use the `atof'
  function.

 SEE ALSO
  typecast, atof, int

--------------------------------------------------------------

int

 SYNOPSIS
  Typecast an object to an integer

 USAGE
  Int_Type int (s)

 DESCRIPTION
  This function performs a typecast of an object `s' to
  an object of Integer_Type.  If `s' is a string, it returns
  returns the ascii value of the first bytes of the string
  `s'.  If `s' is Double_Type, `int' truncates the
  number to an integer and returns it.

 EXAMPLE
  `int' can be used to convert single byte strings to
  integers.  As an example, the intrinsic function `isdigit' may
  be defined as

    define isdigit (s)
    {
      if ((int (s) >= '0') and (int (s) <= '9')) return 1;
      return 0;
    }


 NOTES
  This function is equivalent to `typecast (s, Integer_Type)';

 SEE ALSO
  typecast, double, integer, char, isdigit, isxdigit

--------------------------------------------------------------

integer

 SYNOPSIS
  Convert a string to an integer

 USAGE
  Integer_Type integer (String_Type s)

 DESCRIPTION
  The `integer' function converts a string representation of an
  integer back to an integer.  If the string does not form a valid
  integer, a SyntaxError will be thrown.

 EXAMPLE
  `integer ("1234")' returns the integer value `1234'.

 NOTES
  This function operates only on strings and is not the same as the
  more general `typecast' operator.

 SEE ALSO
  typecast, _slang_guess_type, string, sprintf, char

--------------------------------------------------------------

isalnum, isalpha, isascii, isblank, iscntrl, isdigit, isgraph, islower, isprint, ispunct, isspace, isupper, isxdigit

 SYNOPSIS
  Character classification functions

 USAGE
  Char_Type isalnum(wch)
  Char_Type isalpha(wch)
  Char_Type isascii(wch)
  Char_Type isblank(wch)
  Char_Type iscntrl(wch)
  Char_Type isdigit(wch)
  Char_Type isgraph(wch)
  Char_Type islower(wch)
  Char_Type isprint(wch)
  Char_Type ispunct(wch)
  Char_Type isspace(wch)
  Char_Type isupper(wch)
  Char_Type isxdigit(wch)

 DESCRIPTION
  These functions return a non-zero value if the character given by
  `wch' is a member of the character class represented by the
  function, according to the table below.  Otherwise, 0 will be
  returned to indicate that the character is not a member of the
  class.  If the parameter `wch' is a string, then the first
  character (not necessarily a byte) of the string will be used.

   isalnum : alphanumeric character, equivalent to isalpha or isdigit
   isalpha : alphabetic character
   isascii : 7-bit unsigned ascii character
   isblank : space or a tab
   iscntrl : control character
   isdigit : digit 0-9
   isgraph : non-space printable character
   islower : lower-case character
   isprint : printable character, including a space
   ispunct : non-alphanumeric graphic character
   isspace : whitespace character (space, newline, tab, etc)
   isupper : uppercase case character
   isxdigit: hexadecimal digit character 0-9, a-f, A-F


 SEE ALSO
  strtrans

--------------------------------------------------------------

_slang_guess_type

 SYNOPSIS
  Guess the data type that a string represents

 USAGE
  DataType_Type _slang_guess_type (String_Type s)

 DESCRIPTION
  This function tries to determine whether its argument `s'
  represents an integer (short, int, long), floating point (float,
  double), or a complex number.  If it appears to be none of these,
  then a string is assumed.  It returns one of the following values
  depending on the format of the string `s':

    Short_Type     :  short integer           (e.g., "2h")
    UShort_Type    :  unsigned short integer  (e.g., "2hu")
    Integer_Type   :  integer                 (e.g., "2")
    UInteger_Type  :  unsigned integer        (e.g., "2")
    Long_Type      :  long integer            (e.g., "2l")
    ULong_Type     :  unsigned long integer   (e.g., "2l")
    Float_Type     :  float                   (e.g., "2.0f")
    Double_Type    :  double                  (e.g., "2.0")
    Complex_Type   :  imaginary               (e.g., "2i")
    String_Type    :  Anything else.          (e.g., "2foo")

  For example, `_slang_guess_type("1e2")' returns
  Double_Type but `_slang_guess_type("e12")' returns
  String_Type.

 SEE ALSO
  integer, string, double, atof, __is_datatype_numeric

--------------------------------------------------------------

string

 SYNOPSIS
  Convert an object to a string representation.

 USAGE
  String_Type string (obj)

 DESCRIPTION
   The `string' function may be used to convert an object
   `obj' of any type to its string representation.
   For example, `string(12.34)' returns `"12.34"'.

 EXAMPLE

     define print_anything (anything)
     {
        message (string (anything));
     }


 NOTES
   This function is _not_ the same as typecasting to a String_Type
   using the `typecast' function.

 SEE ALSO
  typecast, sprintf, integer, char

--------------------------------------------------------------

tolower

 SYNOPSIS
  Convert a character to lowercase.

 USAGE
  Integer_Type lower (Integer_Type ch)

 DESCRIPTION
  This function takes an integer `ch' and returns its lowercase
  equivalent.

 SEE ALSO
  toupper, strup, strlow, int, char, define_case

--------------------------------------------------------------

toupper

 SYNOPSIS
  Convert a character to uppercase.

 USAGE
  Integer_Type toupper (Integer_Type ch)

 DESCRIPTION
  This function takes an integer `ch' and returns its uppercase
  equivalent.

 SEE ALSO
  tolower, strup, strlow, int, char, define_case

--------------------------------------------------------------

typecast

 SYNOPSIS
  Convert an object from one data type to another.

 USAGE
  typecast (x, new_type)

 DESCRIPTION
  The `typecast' function performs a generic typecast operation on
  `x' to convert it to `new_type'.  If `x' represents an
  array, the function will attempt to convert all elements of `x'
  to `new_type'.  Not all objects can be converted and a
  type-mismatch error will result upon failure.

 EXAMPLE

    define to_complex (x)
    {
       return typecast (x, Complex_Type);
    }

  defines a function that converts its argument, `x' to a complex
  number.

 SEE ALSO
  int, double, typeof

--------------------------------------------------------------

_typeof

 SYNOPSIS
  Get the data type of an object

 USAGE
  DataType_Type _typeof (x)

 DESCRIPTION
  This function is similar to the `typeof' function except in the
  case of arrays.  If the object `x' is an array, then the data
  type of the array will be returned. Otherwise `_typeof' returns
  the data type of `x'.

 EXAMPLE

    if (Integer_Type == _typeof (x))
      message ("x is an integer or an integer array");


 SEE ALSO
  typeof, array_info, _slang_guess_type, typecast

--------------------------------------------------------------

typeof

 SYNOPSIS
  Get the data type of an object

 USAGE
  DataType_Type typeof (x)

 DESCRIPTION
  This function returns the data type of `x'.

 EXAMPLE

  if (Integer_Type == typeof (x)) message ("x is an integer");


 SEE ALSO
  _typeof, is_struct_type, array_info, _slang_guess_type, typecast

--------------------------------------------------------------