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, wherediff
--------------------------------------------------------------
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
all, where, wherediff
--------------------------------------------------------------
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, args...)
% or
(Array_Type, ...) array_map (type, ..., func, args...)
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. If the function returns multiple
values, then the type of each return value must be given. The first
array-valued argument is used to determine the dimensions of the
resulting array(s). If any subsequent arguments correspond to an array
of the same size, then those array elements will be passed in
parallel with the elements of the first array argument.
To use `array_map' with functions that return no value, either
omit the `type' argument, or explicitly indicate that it
returns no value using the Void_Type type.
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"];
Here is an example of its application to a function that returns 3
values. Suppose `A' is an array of arrays whose types and
sizes are arbitrary, and we wish to find the indices of `A'
that contain arrays of type `String_Type'. For this purpose, the
`array_info' function will be used:
(dims, ndims, types)
= array_map (Array_Type, Int_Type, DataType_Type, &array_info, A);
i = where (types == String_Type);
The `message' function prints a string and returns no value.
This example shows how it may be used to print an array of strings:
a = ["Line 1", "Line 2", "Line 3"];
array_map (&message, a); % Form 1
array_map (Void_Type, &message, a); % Form 2
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);
NOTES
A number of the string functions have been vectorized, including the
`strlen' function. This means that there is no need to use the
`array_map' function with the `strlen' function.
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 themselves as
tie-breakers. As a result, the following two statements 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
Char_Type array `a' by setting the elements of the array
`a' to the corresponding bytes 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
bytes in the string `"HelloWorld"'.
NOTES
The character array must be large enough to hold all the characters
of the initialization string. This function uses byte-semantics.
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
--------------------------------------------------------------
prod
SYNOPSIS
Compute the product of the elements of an array
USAGE
result = prod (Array_Type a [, Int_Type dim])
DESCRIPTION
The `prod' function computes the product of the elements of a
numeric array and returns the result. If a second argument is
given, then it specifies the dimension of the array over which the
product is to be taken. 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
Complex_Type, then the result will be a Complex_Type.
SEE ALSO
sum, sumsq
--------------------------------------------------------------
_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.
The `where' function can also be used with relational operators
and with the boolean binary `or' and `and' operators, e.g.,
a = where (array == "a string");
a = where (array <= 5);
a = where (2 <= array <= 10);
a = where ((array == "a string") or (array == "another string"));
Using in the last example the short-circuiting `||' and
`&&' operators, will result in a `TypeMismatchError' exception.
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, wherediff, array_info, array_shape, _isnull
--------------------------------------------------------------
wherediff
SYNOPSIS
Get the indices where adjacent elements differ
USAGE
Array_Type wherediff (Array_Type A [, Ref_Type jp])
DESCRIPTION
This function returns an array of the indices where adjacent
elements of the array `A' differ. If the optional second
argument is given, it must be a reference to a variable whose value
will be set to the complement indices (those where adjacient
elements are the same).
The returned array of indices will consist of those elements
`i' where `A[i] != A[i-1]'. Since no element preceeds the
0th element, `A[0]' differs from its non-existing
preceeding element; hence the index `0' will a member of the
returned array.
EXAMPLE
Suppose that `A = [1, 1, 3, 0, 0, 4, 7, 7]'. Then,
i = wherediff (A, &j);
will result in `i = [0, 2, 3, 5, 6]' and `j = [1, 4, 7]'.
NOTES
Higher dimensional arrays are treated as a 1-d array of contiguous
elements.
SEE ALSO
where, wherenot
--------------------------------------------------------------
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, wherefirstmin, wherefirstmax, wherefirst_eq
--------------------------------------------------------------
wherefirst_eq, wherefirst_ne, wherefirst_ge, wherefirst_gt, wherefirst_le, wherefirst_lt, wherelast_eq, wherelast_ne, wherelast_ge, wherelast_gt, wherelast_le, wherelast_lt
SYNOPSIS
Get the first or last matching element of an array
USAGE
Int_Type wherefirst_eq (A, b [,istart])
Int_Type wherefirst_ne (A, b [,istart])
Int_Type wherefirst_ge (A, b [,istart])
Int_Type wherefirst_gt (A, b [,istart])
Int_Type wherefirst_le (A, b [,istart])
Int_Type wherefirst_lt (A, b [,istart])
Int_Type wherelast_eq (A, b [,istart])
Int_Type wherelast_ne (A, b [,istart])
Int_Type wherelast_ge (A, b [,istart])
Int_Type wherelast_gt (A, b [,istart])
Int_Type wherelast_le (A, b [,istart])
Int_Type wherelast_lt (A, b [,istart])
DESCRIPTION
These functions perform the indicated binary operation between the
elements of numeric array `A' and a number `b'. The
`wherefirst_*' functions return the index of the first element for which the
comparison is true. The `wherelast_*' functions return the last
index where the binary operation is true. If no matching elements are
found, the functions return NULL.
If the optional third parameter, `istart', is given, then it
indicates the index into the array where the search is to start.
These functions have the following equivalent forms:
wherefirst_eq (A, b, istart) <==> wherefirst (A == b, istart)
wherefirst_ne (A, b, istart) <==> wherefirst (A != b, istart)
wherefirst_ge (A, b, istart) <==> wherefirst (A >= b, istart)
wherefirst_gt (A, b, istart) <==> wherefirst (A > b, istart)
wherefirst_le (A, b, istart) <==> wherefirst (A <= b, istart)
wherefirst_lt (A, b, istart) <==> wherefirst (A < b, istart)
wherelast_eq (A, b, istart) <==> wherelast (A == b, istart)
wherelast_ne (A, b, istart) <==> wherelast (A != b, istart)
wherelast_ge (A, b, istart) <==> wherelast (A >= b, istart)
wherelast_gt (A, b, istart) <==> wherelast (A > b, istart)
wherelast_le (A, b, istart) <==> wherelast (A <= b, istart)
wherelast_lt (A, b, istart) <==> wherelast (A < b, istart)
However, the `wherefirst_*' and `wherelast_*' function can
execute several orders of magnitude faster, depending upon the context.
NOTES
The current implementation of these functions is limited to numeric
types.
SEE ALSO
wherefirst, wherelast
wherefirstmax
SYNOPSIS
Get the index of the first maximum array value
USAGE
Int_Type wherefirstmax (Array_Type a)
DESCRIPTION
This function is equivalent to
index = wherefirst (a == max(a));
It executes about 3 times faster, and does not require the creation of
temporary arrays.
SEE ALSO
wherefirst, wherefirstmax, wherelastmin, min, max
--------------------------------------------------------------
wherefirstmin
SYNOPSIS
Get the index of the first minimum array value
USAGE
Int_Type wherefirstmin (Array_Type a)
DESCRIPTION
This function is equivalent to
index = wherefirst (a == min(a));
It executes about 3 times faster, and does not require the creation of
temporary arrays.
SEE ALSO
wherefirst, wherelastmin, wherefirstmax, min, max
--------------------------------------------------------------
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 wherelast (a)
{
variable i = where (a);
if (length(i))
return i[-1];
else
return NULL;
}
SEE ALSO
where, wherefirst, wherelastmin, wherelastmax, wherefirst_eq
--------------------------------------------------------------
wherelastmax
SYNOPSIS
Get the index of the last maximum array value
USAGE
Int_Type wherelastmax (Array_Type a)
DESCRIPTION
This function is equivalent to
index = wherelast (a == max(a));
It executes about 3 times faster, and does not require the creation of
temporary arrays.
SEE ALSO
wherelast, wherefirstmin, wherelastmin, min, max
--------------------------------------------------------------
wherelastmin
SYNOPSIS
Get the index of the last minimum array value
USAGE
Int_Type wherelastmin (Array_Type a)
DESCRIPTION
This function is equivalent to
index = wherelast (a == min(a));
It executes about 3 times faster, and does not require the creation of
temporary arrays.
SEE ALSO
wherelast, wherefirstmin, wherelastmax, min, max
--------------------------------------------------------------
wherenot
SYNOPSIS
Get indices where a numeric array is 0
USAGE
Array_Type wherenot (Array_Type a)
DESCRIPTION
This function is equivalent to `where(not a)'. See the
documentation for `where' for more information.
SEE ALSO
where, wherediff, wherefirst, wherelast
--------------------------------------------------------------
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_values (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];
Then 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_keys, 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 bytes
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
--------------------------------------------------------------
bstrcat
SYNOPSIS
Concatenate binary strings
USAGE
String_Type bstrcat (BString_Type a_1, ..., BString_Type a_N)
DESCRIPTION
The `bstrcat' function concatenates its N binary string
arguments `a_1', ... `a_N' together and returns the result.
NOTES
This function will produce a result that is identical to that of
`strcat' if the input strings do not contain null characters.
SEE ALSO
strcat, bstrjoin
--------------------------------------------------------------
bstrjoin
SYNOPSIS
Concatenate elements of an array of BString_Type objects
USAGE
String_Type bstrjoin (Array_Type a [, BString_Type delim])
DESCRIPTION
The `bstrjoin' function operates on an array of binary 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.
SEE ALSO
bstrcat, strjoin
--------------------------------------------------------------
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
--------------------------------------------------------------
is_substrbytes
SYNOPSIS
test if a binary string contains a series of bytes
USAGE
Int_Type is_substrbytes (a, b [,ofs])
DESCRIPTION
This function may be used to see if the binary string `a'
contains the byte-sequence given by the binary string `b'. If
`b' is contained in `a', then a ones-based offset of the
first occurance of `b' in `a' is returned. Otherwise, the
function will return 0 to indicate that `a' does not contain
`b'.
An optional 1-based parameter `ofs' may be passed to the function
to indicate where in `a' the search is to start. The returned
value is still a 1-based offset from the beginning of `a' where
`b' is located.
NOTES
Support for the optional argument was added in version 2.3.0.
SEE ALSO
is_substr, count_byte_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
--------------------------------------------------------------
Array_Type
SYNOPSIS
An array type
DESCRIPTION
Arrays up to 7 dimensions are supported. The `{i,j,...,k}` element
of an array `A' may be indexed using `A[i,j,..k]'.
The `length' function may be used to obtain the total number of
elements in the array. The shape, type, and other properties of an
array may obtained using the `array_shape' and
`array_info' functions.
The `foreach' construct may be used with arrays via the
following construct:
foreach v (A) {...}
In all the above forms, the loop is over all elements `v' of the array.
SEE ALSO
List_Type, Struct_Type, Assoc_Type
--------------------------------------------------------------
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
--------------------------------------------------------------
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
--------------------------------------------------------------
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
--------------------------------------------------------------
_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
--------------------------------------------------------------
_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
--------------------------------------------------------------
_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 two parameters, the function name and the
filename and must return nothing.
EXAMPLE
private define bof_handler (fun, file)
{
() = fputs ("About to execute function $fun from file $file"$, stdout);
}
_set_bof_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
--------------------------------------------------------------
_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 depends 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
lchown, 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
--------------------------------------------------------------
lchown
SYNOPSIS
Change the owner of a file
USAGE
Int_Type lchown (String_Type file, Int_Type uid, Int_Type gid)
DESCRIPTION
The `lchown' function is like `chown', except that it does
not dereference a symbolic link. Hence, it may be used to change
the ownership of a symbolic link itself, and not to what it
references. See the documentation for the `chown' function for
more details.
SEE ALSO
chown, chmod, stat_file
--------------------------------------------------------------
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
Int_Type 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
successful, 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
--------------------------------------------------------------
__FILE__
SYNOPSIS
Path of the compilation unit
USAGE
String_Type __FILE__
DESCRIPTION
Every private namespace has `__FILE__' variable associated with
it. If the namespace is associated with a file, then the value of
this variable will be equal to the pathname of the file. If the
namespace is associated with a string, such as one passed to the
`eval' function, then the value of this variable will be
`"***string***"';
NOTES
In the case of a file, the pathname may be an absolute path or a
relative one. If it is a relative one, then it will be relative to
the directory from where the file was loaded, i.e., the value
returned by the `getcwd' function.
--------------------------------------------------------------
_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
--------------------------------------------------------------
_Inf
SYNOPSIS
IEEE Infinity
USAGE
Double_Type _Inf
DESCRIPTION
The value of this variable is an IEEE double precision positive infinity.
SEE ALSO
isinf, isnan, finite, _NaN
_NaN
SYNOPSIS
IEEE Not-a-Number
USAGE
Double_Type _NaN
DESCRIPTION
The value of this variable is a non-signalling IEEE double precision
NaN.
NOTES
An IEEE NaN has some peculiar properties that limits how it should be
used. For example, an IEEE NaN is not equal to itself and expressions
such as `x == _NaN' will always be false. To test if a number is
a NaN, use the `isnan' function.
SEE ALSO
isinf, isnan, finite, _Inf
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
sin, atan, acosh, cosh, sincos
--------------------------------------------------------------
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 fgteqs (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 flteqs (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 fneqs (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
--------------------------------------------------------------
frexp
SYNOPSIS
Obtain the integral and fractional parts of a floating point number
USAGE
(b,e) = frexp(x)
DESCRIPTION
This function breaks a floating point number `x' into two values
`b' and `e' such that `x=b*2^x', where
0.5 <= abs(b) < 1 for x != 0,
b = 0, e = 0 for x = 0
b = _NaN for x = _NaN
b = +/-_Inf for x = +/-Inf
For the latter two cases, the value is `e' is implementation
dependent.
If `x' is an array, the `frexp' function will be applied
to each element and corresponding arrays will be returned.
SEE ALSO
ldexp, pow, log
--------------------------------------------------------------
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
--------------------------------------------------------------
_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 than 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, _ispos
--------------------------------------------------------------
_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
--------------------------------------------------------------
ldexp
SYNOPSIS
Multiply a number by a power of 2
USAGE
x = ldexp(b, e)
DESCRIPTION
This function computes the value of `b*2^e' and returns the
result. If either `b' or `e' is an array, a corresponding
array of values will be returned.
NOTES
This function is the inverse of `frexp'.
SEE ALSO
frexp
--------------------------------------------------------------
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 arguments 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 arguments 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, sincos
--------------------------------------------------------------
sincos
SYNOPSIS
Compute the sine and cosine of a number
USAGE
(s, c) = sincos (x)
DESCRIPTION
The `sincos' function computes the sine and cosine of a
number and returns the result. If its argument is an array,
the `sincos' function will be applied to each element
and the result returned as an array.
SEE ALSO
sin, cos
--------------------------------------------------------------
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
--------------------------------------------------------------
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
NOTES
For testing sameness, use `__is_same'.
SEE ALSO
typeof, __is_same, __get_reference, __is_callable
--------------------------------------------------------------
get_environ
SYNOPSIS
Get all environment variables
USAGE
String_Type[] = get_environ()
DESCRIPTION
The `get_environ' function returns an array of strings
representing the environment variables defined for the current
process. Each element of the array will be of the form
`NAME=VALUE'.
This function will return NULL if the system does not support this
feature.
SEE ALSO
getenv, putenv, is_defined
--------------------------------------------------------------
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
get_environ, 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_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_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_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
NOTES
For testing equality, use `_eqs'.
SEE ALSO
typeof, _eqs, __get_reference, __is_callable
--------------------------------------------------------------
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 have 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
--------------------------------------------------------------
__set_argc_argv
SYNOPSIS
Set the argument list
USAGE
__set_argc_argv (Array_Type a)
DESCRIPTION
This function sets the `__argc' and `__argv' intrinsic variables.
--------------------------------------------------------------
_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
--------------------------------------------------------------
__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
--------------------------------------------------------------
__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
--------------------------------------------------------------
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 if
`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 an 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, _close, fclose, read, write
--------------------------------------------------------------
_close
SYNOPSIS
Close an open file descriptor
USAGE
Int_Type _close (Int_Type fd)
DESCRIPTION
The `_close' function is used to close the underlying integer
open file descriptor. Upon success 0 is returned, otherwise the
function returns -1 and sets `errno' accordingly.
SEE ALSO
open, _fileno, close, 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
--------------------------------------------------------------
dup2_fd
SYNOPSIS
Duplicate a file descriptor
USAGE
Int_Type dup2_fd (FD_Type fd, int newfd)
DESCRIPTION
The `dup2_fd' function makes `newfd' a copy of the
specified file descriptor `fd'. Upon success returns `newfd',
otherwise it returns -1 and sets `errno' accordingly.
SEE ALSO
dup, open, close, _close, _fileno, read
--------------------------------------------------------------
_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, ttyname
--------------------------------------------------------------
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
--------------------------------------------------------------
ttyname
SYNOPSIS
Get the pathname of the terminal
USAGE
String_Type ttyname (FD_Type fd)
DESCRIPTION
This function returns the pathname of the terminal associated with
the file descriptor `fd' or NULL if `fd' does not refer
to a terminal.
NOTES
This function is not available in all systems.
SEE ALSO
isatty
--------------------------------------------------------------
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
--------------------------------------------------------------
flock
SYNOPSIS
control an advisory lock on a file
USAGE
Int_Type flock (File_Type|FD_Type fd, Int_Type op)
DESCRIPTION
This function may be used to apply or remove an advisory lock to the
open file represented by the file descriptor `fd'. The
`op' argument controls the use of the lock via one of
the following values:
LOCK_SH : Add a shared lock. Such locks may be shared by multiple
processes
LOCK_EX : Add an exclusive lock. This type of lock is not shared
with other processes
LOCK_UN : Remove the lock added by the current process
If another process currently has the file locked in an incompatible
way, the call to `flock' will block until that process has
removed the lock. To preveent such blocking, the `LOCK_NB'
flag may be ``ored'' with the locking operation, e.g.,
`LOCK_EX|LOCK_NB'.
The advisory locks are inherited through any operation that
duplicates or inherits the file descriptor, e.g., the `dup2' or
`fork' functions.
The functions returns 0 upon sucess and -1 upon error. Check the
value of the `errno' variable for the reason for failure. Note
that if the `LOCK_NB' flag is used and the file is already
locked in an incompatible way, then the function will fail and set
`errno' to `EWOULDBLOCK'.
NOTES
See the system documentation for additional semantics associated
with this function.
SEE ALSO
open, fopen, fdopen
--------------------------------------------------------------
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
--------------------------------------------------------------
getpgid
SYNOPSIS
Get the process group id
USAGE
Int_Type getpgid (Int_Type pid)
DESCRIPTION
The `getpgid' function returns the process group id of the
process whose process is `pid'. If `pid' is 0, then the
current process will be used.
NOTES
This function is not supported by all systems.
SEE ALSO
getpgrp, getpid, getppid
--------------------------------------------------------------
getpgrp
SYNOPSIS
Get the process group id of the calling process
USAGE
Int_Type getpgrp ()
DESCRIPTION
The `getpgrp' function returns the process group id of the
current process.
NOTES
This function is not supported by all systems.
SEE ALSO
getpgid, 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
--------------------------------------------------------------
getrusage
SYNOPSIS
Get process resource usage
USAGE
Struct_Type getrusage ([Int_Type who])
DESCRIPTION
This function returns a structure whose fields contain information
about the resource usage of calling process, summed over all threads
of the process. The optional integer argument `who' may be
used to obtain resource usage of child processes, or of the calling
thread itself. Specifically, the optional integer argument
`who' may take on one of the following values:
RUSAGE_SELF (default)
RUSAGE_CHILDREN
If `RUSAGE_CHILDREN' is specified, then the process information
will be the sum of all descendents of the calling process that have
terminated and have been waited for (via, e.g., `waitpid'). It
will not contain any information about child processes that have not
terminated.
The structure that is returned will contain the following fields:
ru_utimesecs user CPU time used (Double_Type secs)
ru_stimesecs system CPU time used (Double_Type secs)
ru_maxrss maximum resident_set_size
ru_minflt page reclaims (soft page faults)
ru_majflt page faults (hard page faults)
ru_inblock block input operations
ru_oublock block output operations
ru_nvcsw voluntary context switches
ru_nivcsw involuntary context switches
ru_ixrss integral shared memory size
ru_idrss integral unshared data size
ru_isrss integral unshared stack size
ru_nswap swaps
ru_msgsnd IPC messages sent
ru_msgrcv IPC messages received
ru_nsignals signals received
Some of the fields may not be supported for a particular OS or
kernel version. For example, on Linux the 2.6.32 kernel supports
only the following fields:
ru_utimesecs
ru_stimesecs
ru_maxrss (since Linux 2.6.32)
ru_minflt
ru_majflt
ru_inblock (since Linux 2.6.22)
ru_oublock (since Linux 2.6.22)
ru_nvcsw (since Linux 2.6)
ru_nivcsw (since Linux 2.6)
NOTES
The underlying system call returns the CPU user and system times
as C `struct timeval' objects. For convenience, the interpreter
interface represents these objects as double precision floating point
values.
SEE ALSO
times
--------------------------------------------------------------
getsid
SYNOPSIS
get the session id of a process
USAGE
Int_Type getsid ([Int_Type pid])
DESCRIPTION
The `getsid' function returns the session id of the current
process. If the optional integer `pid' argument is given, then
the function returns the session id of the specified process id.
SEE ALSO
setsid, getpid, getpid
--------------------------------------------------------------
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
killpg, getpid
--------------------------------------------------------------
killpg
SYNOPSIS
Send a signal to a process group
USAGE
Integer_Type killpg (Integer_Type pgrppid, Integer_Type sig)
DESCRIPTION
This function may be used to send a signal given by the integer `sig'
to the process group specified by `pgrppid'. The function returns zero upon
success or `-1' upon failure setting `errno' accordingly.
NOTES
This function is not supported by all systems.
SEE ALSO
kill, 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
--------------------------------------------------------------
setsid
SYNOPSIS
Create a new session for the current process
USAGE
Int_Type setsid ()
DESCRIPTION
If the current process is not a session leader, the `setsid'
function will create a new session and make the process the session
leader for the new session. It returns the the process group id of
the new session.
Upon failure, -1 will be returned and `errno' set accordingly.
SEE ALSO
getsid, setpgid
--------------------------------------------------------------
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.
--------------------------------------------------------------
statvfs
SYNOPSIS
Get file system statistics
USAGE
Struct_Type statvfs (fsobj)
DESCRIPTION
This function is a wrapper around the corresponding POSIX function.
It returns a structure whose fields provide information about the
filesystem object `fsobj'. This object can be either a path
name within the file system, or an open file descriptor represented
by an integer, File_Type, or FD_Type object.
The fields of the structure are defined as follows:
f_bsize : file system block size
f_frsize : fragment size
f_blocks : size of fs in f_frsize units
f_bfree : number of free blocks
f_bavail : number of free blocks for unprivileged users
f_files : number of inodes
f_ffree : number of free inodes
f_favail : number of free inodes for unprivileged users
f_fsid : file system ID
f_flag : mount flags
f_namemax: maximum filename length
The value of the `f_flag' field is a bitmapped integer composed
of the following bits:
ST_RDONLY : Read-only file system.
ST_NOSUID : Set-user-ID/set-group-ID bits are ignored by the exec
functions.
Upon error, the function returns NULL and sets `errno'
accordingly.
NOTES
This function is not supported by all systems.
SEE ALSO
stat_file
--------------------------------------------------------------
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_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_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_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_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_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_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_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
--------------------------------------------------------------
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_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_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_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
--------------------------------------------------------------
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 demonstrates how the `alarm' function may be
used to read from `stdin' within a specified amount of time:
define sigalrm_handler (sig)
{
throw ReadError, "Read timed out";
}
define read_or_timeout (secs)
{
variable line, err;
signal (SIGALRM, &sigalrm_handler);
() = fputs ("Enter some text> ", stdout); () = fflush (stdout);
alarm (secs);
try (err)
{
if (-1 == fgets (&line, stdin))
throw ReadError, "Failed to read from stdin";
}
catch IOError:
{
message (err.message);
return 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, setitimer, getitimer
--------------------------------------------------------------
getitimer
SYNOPSIS
Get the value of an interval timer
USAGE
(secs, period) = getitimer (Int_Type timer)
DESCRIPTION
This function returns the value of the specified interval timer as a
pair of double precision values: `period' and `secs'.
The value of `secs' indicates the number of seconds
remaining before the timer expires. A value of 0 for
`secs' indicates that the timer is inactive.
The value of `period' indicates the periodicity of the timer.
That is, when the timer goes off, it will automatically be reset to
go off again after `period' seconds.
There are 3 interval timers available: ITIMER_REAL,
ITIMER_VIRTUAL, and ITIMER_PROF.
The ITIMER_REAL timer operates in real time and when the time
elapses, a SIGALRM will be sent to the process.
The ITIMER_VIRTUAL timer operates in the virtual time of the
process; that is, when process is actively running. When it
elapses, SIGVTALRM will be sent to the process.
The ITIMER_PROF operates when the process is actively
running, or when the kernel is performing a task on behalf of the
process. It sends a SIGPROF signal to the process.
NOTES
The interaction between these timers and the `sleep' and
`alarm' functions is OS dependent.
The resolution of a timer is system dependent; typical values are on
the order of milliseconds.
SEE ALSO
setitimer, alarm, signal
--------------------------------------------------------------
setitimer
SYNOPSIS
Set the value of an interval timer
USAGE
setitimer (Int_Type timer, secs [, period] [,&old_secs, &old_period])
DESCRIPTION
This function sets the value of a specified interval timer, and
optionally returns the previous value. The value of the
`timer' argument must be one of the 3 interval timers
ITIMER_REAL, ITIMER_VIRTUAL, or ITIMER_PROF.
See the documentation for the `getitimer' function for
information about the semantics of these timers.
The value of the `secs' parameter specifies the expiration time
for the timer. If this value is 0, the timer will be disabled.
Unless a non-zero value for the optional `period' parameter is
given, the timer will be disabled after it expires. Otherwise,
the timer will reset to go off with a period of `period' seconds.
The final two optional arguments are references to variables that
will be set to the previous values associated with the timer.
SEE ALSO
getitimer, alarm, signal
--------------------------------------------------------------
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 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.
QUALIFIERS
The `trim' qualifier may be used remove leading or trailing
whitespace from the returned lines. If `trim' is 1, trailing
whitespace will be removed. If its value is 2, then leading
whitespace will be removed. If `trim' is 3, then both leading
and trailing whitespace will be removed.
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 (str, fp))
|| (-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 then returns the exit status of the command.
SEE ALSO
popen, 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
--------------------------------------------------------------
setvbuf
SYNOPSIS
USAGE
Int_Type setvbuf (File_Type fp, Int_Type mode, Int_Type size)
DESCRIPTION
The `setvbuf' function may be used to control how the stdio
stream specified by the open File_Type object is buffered.
The `mode' argument must be one of the following values:
_IONBF : unbuffered
_IOFBF : fully buffered
_IOLBF : line buffered
The `size' argument controls the size of the buffer. If
`size' is 0, then the function will not change the size of the
buffer, only the mode. Otherwise, `size' is expected to be
larger than 0 and a buffer of the requested size will be allocated
for the stream.
are buffered.
NOTES
This function must be used only after the stream has been opened and
before any other operations have been performed on the stream.
SEE ALSO
fopen, fclose, fflush
--------------------------------------------------------------
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
+ Precede 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, set_float_format
--------------------------------------------------------------
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'.
o Matches an unsigned octal integer.
O Matches an unsigned long octal integer.
x Matches an unsigned hexadecimal integer.
X Matches a long unsigned 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 the 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
offset (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 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 specify 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 superseded 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
This function assumes character semantics and not byte semantics.
Use the `substrbytes' function to extract bytes from a string.
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 `substrbytes' 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
--------------------------------------------------------------
wchars_to_string,string_to_wchars
SYNOPSIS
Convert a UTF-8 encoded string to and from character codes
USAGE
Int_Type[] string_to_wchars(String_Type str)
String_Type wchars_to_string(Int_Type[] array)
DESCRIPTION
The `string_to_wchars' function decodes a UTF-8 encoded string
and returns the Unicode characters as an array of integer values. The
`wchars_to_string' performs the opposite conversion to produce a
UTF-8 encoded string from an array of Unicode characters.
NOTES
A malformed UTF-8 encoded string will result in negative byte-values in the
output array at the positions corresponding to the malformed sequence.
For example, the following function will substitute a '?' character
for each byte in the malformed sequence to produce a valid string:
define handle_malformed_bytes (str)
{
variable codes = string_to_wchars (str);
variable is_bad = (codes < 0);
if (any(is_bad))
{
codes[where(is_bad)] = '?';
str = wchars_to_string (codes);
}
return str;
}
SEE ALSO
char, substr, array_to_bstring, bstring_to_array
--------------------------------------------------------------
__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_destroy
SYNOPSIS
Add a destroy callback function to a user-defined type
USAGE
__add_destroy(DataType_Type user_type, Ref_Type callback_func)
DESCRIPTION
The `__add_destroy' function adds a callback function to a
user-defined type such that it will get called prior to deleting an
instance of the user-defined type. Just prior to deleting the
object, the object will be passed to the callback function. The
callback function should return nothing.
SEE ALSO
__add_unary, __add_binary
--------------------------------------------------------------
__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'. If the specified name is not a field of the structure, the
function will throw an `InvalidParmError' exception.
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, or to an array of
structures or user-defined types. If the object is neither, 0 will
be returned.
SEE ALSO
typeof, _typeof, is_struct_type
--------------------------------------------------------------
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)
% or
(v1,v2,...,vN) = _push_struct_field_values (Struct_Type s, Array_Type names)
DESCRIPTION
The `_push_struct_field_values' function may be used to obtain
the values of one of more fields of a structure. This function has
two usage forms.
The first form 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.
The second form has an additional array argument that specifies the
names of the fields to process. It returns the values in the order
specified by the array. Unlike the first form, it does not return
the number of items pushed.
EXAMPLE
s = struct {foo=1, bar="seven", z = "zz"};
% Form 1
n = _push_struct_field_values (s); % ==> n = 3
list = __pop_list (n); % ==> list = {"zz", "seven", 1};
% Form 2
list = {_push_struct_field_values (s, ["foo", "bar", "z"])};
% ==> list = {1, "seven", "zz"};
% Form 2
list = {_push_struct_field_values (s, ["z", "foo"])};
% ==> list = {"zz", 1};
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, _toc, _tic, 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.
NOTES
This function is a wrapper around the C library `time'
function, and as such, probably does not account for leap seconds.
SEE ALSO
_ftime, ctime, time, localtime, gmtime
--------------------------------------------------------------
_ftime
SYNOPSIS
Get the current calendar time in seconds
USAGE
Double_Type _ftime ( [Double_Type opt_epoch] )
DESCRIPTION
The `_ftime' function returns the number seconds since the Unix
epoch, 00:00:00 UTC, January 1, 1970 as a double precision number.
If the optional argument `opt_epoch' is passed, the function
will return a value relative to that epoch, which is defined as the
number of seconds since the Unix epoch.
SEE ALSO
_time, 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
--------------------------------------------------------------
_array_byteswap
SYNOPSIS
Convert an array from one endianness to another
USAGE
b = _array_byteswap (Array_Type a, Int_Type from, Int_Type to)
DESCRIPTION
The `_array_byteswap' function converts the elements of an array
from one endianess to another via a byte-swapping operation. The
parameters `from' and `to' indicate the endianesss of the
input and output arrays, respectively. The values for `from' and
`to' parameters must be one of the following:
'B', 'b', '>' : Big Endian (network order)
'L', 'l', '<' : Little Endian
'N', 'n', '=' : Native (host order)
The function returns an array of the corresponding byte-swapped
elements.
NOTES
If the parameter `a' is a scalar, a corresponding byte-swapped
scalar will be returned.
If the object represented by the parameter `a' cannot be
byteswapped, an exception will be thrown. For example, an error will
be thrown if `a' is a String_Type object.
SEE ALSO
pack, unpack, typecast
--------------------------------------------------------------
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, 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, _array_byteswap
--------------------------------------------------------------
_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
--------------------------------------------------------------
Generated by dwww version 1.15 on Mon Jun 24 14:09:29 CEST 2024.