_reshape
SYNOPSIS
Copy an array to a new shape
USAGE
Array_Type _reshape (Array_Type A, Array_Type I)
DESCRIPTION
The `_reshape' function creates a copy of an array `A',
reshapes it to the form specified by `I' and returns the result.
The elements of `I' specify the new dimensions of the copy of
`A' and must be consistent with the number of elements `A'.
EXAMPLE
If `A' is a `100' element 1-d array, a new array 2-d array of
size `20' by `5' may be created from the elements of `A'
by
A = _reshape (A, [20, 5]);
In this example, the original array was no longer needed. Hence, it
is preferable to make use of the `__tmp' operator to avoid the
creation of a new array, i.e.,
A = _reshape (__tmp(A), [20,5]);
NOTES
The `reshape' function performs a similar function to
`_reshape'. In fact, the `_reshape' function could have been
implemented via:
define _reshape (a, i)
{
a = @a; % Make a new copy
reshape (a, i);
return a;
}
SEE ALSO
reshape, array_info
--------------------------------------------------------------
array_info
SYNOPSIS
Returns information about an array
USAGE
(Array_Type, Integer_Type, DataType_Type) array_info (Array_Type a)
DESCRIPTION
The `array_info' function returns information about the array `a'.
It returns three values: an 1-d integer array array specifying the
size of each dimension of `a', the number of dimensions of
`a', and the data type of `a'.
EXAMPLE
The `array_info' function may be used to find the number of rows
of an array:
define num_rows (a)
{
variable dims, num_dims, data_type;
(dims, num_dims, data_type) = array_info (a);
return dims [0];
}
For 1-d arrays, this information is more easily obtained from the
`length' function.
SEE ALSO
typeof, reshape, length, _reshape
--------------------------------------------------------------
array_map
SYNOPSIS
Apply a function to each element of an array
USAGE
Array_Type array_map (type, func, arg0, ...)
DataType_Type type;
Ref_Type func;
DESCRIPTION
The `array_map' function may be used to apply a function to each
element of an array and returns the result as an array of a
specified type. The `type' parameter indicates what kind of
array should be returned and generally corresponds to the return
type of the function. The `arg0' parameter should be an array
and is used to determine the dimensions of the resulting array. If
any subsequent arguments correspond to an array of the same size,
then those array elements will be passed in parallel with the first
arrays arguments.
EXAMPLE
The first example illustrates how to apply the `strlen' function
to an array of strings:
S = ["", "Train", "Subway", "Car"];
L = array_map (Integer_Type, &strlen, S);
This is equivalent to:
S = ["", "Train", "Subway", "Car"];
L = Integer_Type [length (S)];
for (i = 0; i < length (S); i++) L[i] = strlen (S[i]);
Now consider an example involving the `strcat' function:
files = ["slang", "slstring", "slarray"];
exts = ".c";
cfiles = array_map (String_Type, &strcat, files, exts);
% ==> cfiles = ["slang.c slstring.c slarray.c"];
exts = [".a",".b",".c"];
xfiles = array_map (String_Type, &strcat, files, exts);
% ==> xfiles = ["slang.a", "slstring.b", "slarray.c"];
NOTES
Many mathemetical functions already work transparantly on arrays.
For example, the following two statements produce identical results:
B = sin (A);
B = array_map (Double_Type, &sin, A);
SEE ALSO
array_info, strlen, strcat, sin
--------------------------------------------------------------
array_sort
SYNOPSIS
Sort an array
USAGE
Array_Type array_sort (Array_Type a [, String_Type or Ref_Type f])
DESCRIPTION
`array_sort' sorts the array `a' into ascending order and
returns an integer array that represents the result of the sort. If
the optional second parameter `f' is present, the function
specified by `f' will be used to compare elements of `a';
otherwise, a built-in sorting function will be used.
If `f' is present, then it must be either a string representing
the name of the comparison function, or a reference to the function.
The sort function represented by `f' must be a S-Lang
user-defined function that takes two arguments. The function must
return an integer that is less than zero if the first parameter is
considered to be less than the second, zero if they are equal, and a
value greater than zero if the first is greater than the second.
If the comparision function is not specified, then a built-in comparison
function appropriate for the data type will be used. For example,
if `a' is an array of character strings, then the sort will be
preformed using `strcmp'.
The integer array returned by this function is simply an index that
indicates the order of the sorted array. The input array `a' is
not changed.
EXAMPLE
An array of strings may be sorted using the `strcmp' function
since it fits the specification for the sorting function described
above:
variable A = String_Type [3];
A[0] = "gamma"; A[1] = "alpha"; A[2] = "beta";
variable I = array_sort (A, &strcmp);
Alternatively, one may use
variable I = array_sort (A);
to use the built-in comparison function.
After the `array_sort' has executed, the variable `I' will
have the values `[2, 0, 1]'. This array can be used to
re-shuffle the elements of `A' into the sorted order via the
array index expression `A = A[I]'.
SEE ALSO
strcmp
--------------------------------------------------------------
init_char_array
SYNOPSIS
Initialize an array of characters
USAGE
init_char_array (Array_Type a, String_Type s)
DESCRIPTION
The `init_char_array' function may be used to initialize a
character array `a' by setting the elements of the array
`a' to the corresponding characters of the string `s'.
EXAMPLE
The statements
variable a = Char_Type [10];
init_char_array (a, "HelloWorld");
creates an character array and initializes its elements to the
characters in the string `"HelloWorld"'.
NOTES
The character array must be large enough to hold all the characters
of the initialization string.
SEE ALSO
bstring_to_array, strlen, strcat
--------------------------------------------------------------
length
SYNOPSIS
Get the length of an object
USAGE
Integer_Type length (obj)
DESCRIPTION
The `length' function may be used to get information about the
length of an object. For simple scalar data-types, it returns 1.
For arrays, it returns the total number of elements of the array.
NOTES
If `obj' is a string, `length' returns 1 because a
`String_Type' object is considered to be a scalar. To get the
number of characters in a string, use the `strlen' function.
SEE ALSO
array_info, typeof, strlen
--------------------------------------------------------------
reshape
SYNOPSIS
Reshape an array
USAGE
reshape (Array_Type A, Array_Type I)
DESCRIPTION
The `reshape' function changes the size of `A' to have the size
specified by the 1-d integer array `I'. The elements of `I'
specify the new dimensions of `A' and must be consistent with
the number of elements `A'.
EXAMPLE
If `A' is a `100' element 1-d array, it can be changed to a
2-d `20' by `5' array via
reshape (A, [20, 5]);
However, `reshape(A, [11,5])' will result in an error because
the the `[11,5]' array specifies `55' elements.
NOTES
Since `reshape' modifies the shape of an array, and arrays are
treated as references, then all references to the array will
reference the new shape. If this effect is unwanted, then use the
`_reshape' function instead.
SEE ALSO
_reshape, array_info
--------------------------------------------------------------
transpose
SYNOPSIS
Transpose a 2d array
USAGE
Array_Type transpose (Array_Type a)
DESCRIPTION
The `transpose' function returns the transpose of a specified
array. By definition, the transpose of an array, say one with
elements `a[i,j,...k]' is an array whose elements are
`a[k,...,j,i]'.
SEE ALSO
_reshape, reshape, array_info
--------------------------------------------------------------
where
SYNOPSIS
Get indices where an integer array is non-zero
USAGE
Array_Type where (Array_Type a)
DESCRIPTION
The `where' function examines an integer array `a' and
returns a 2-d integer array whose rows are the indices of `a'
where the corresponding element of `a' is non-zero.
EXAMPLE
Consider the following:
variable X = [0.0:10.0:0.01];
variable A = sin (X);
variable I = where (A < 0.0);
A[I] = cos (X) [I];
Here the variable `X' has been assigned an array of doubles
whose elements range from `0.0' through `10.0' in
increments of `0.01'. The second statement assigns `A' to
an array whose elements are the `sin' of the elements of `X'.
The third statement uses the where function to get the indices of
the elements of `A' that are less than `0.0'. Finally, the
last statement substitutes into `A' the `cos' of the
elements of `X' at the positions of `A' where the
corresponding `sin' is less than `0'. The end result is
that the elements of `A' are a mixture of sines and cosines.
SEE ALSO
array_info, sin, cos
--------------------------------------------------------------
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.
EXAMPLE
The following function computes the number of keys in an associative
array:
define get_num_elements (a)
{
return length (assoc_get_keys (a));
}
SEE ALSO
assoc_get_values, assoc_key_exists, assoc_delete_key, length
--------------------------------------------------------------
assoc_get_values
SYNOPSIS
Return all the values of an Associative Array
USAGE
Array_Type assoc_get_keys (Assoc_Type a)
DESCRIPTION
This function returns all the values in the associative array
`a' as an array of proper type. If the associative array
contains no keys, an empty array will be returned.
EXAMPLE
Suppose that `a' is an associative array of type
`Integer_Type', i.e., it was created via
variable a = Assoc_Type[Integer_Type];
The the following may be used to print the values of the array in
ascending order:
static define int_sort_fun (x, y)
{
return sign (x - y);
}
define sort_and_print_values (a)
{
variable i, v;
v = assoc_get_values (a);
i = array_sort (v, &int_sort_fun);
v = v[i];
foreach (v)
{
variable vi = ();
() = fprintf (stdout, "%d\n", vi);
}
}
SEE ALSO
assoc_get_values, assoc_key_exists, assoc_delete_key, array_sort
--------------------------------------------------------------
assoc_key_exists
SYNOPSIS
Check to see whether a key exists in an Associative Array
USAGE
Integer_Type assoc_key_exists (Assoc_Type a, String_Type k)
DESCRIPTION
The `assoc_key_exists' function may be used to determine whether
or not a specified key `k' exists in an associative array `a'.
It returns 1 if the key exists, or 0 if it does not.
SEE ALSO
assoc_get_keys, assoc_get_values, assoc_delete_key
--------------------------------------------------------------
array_to_bstring
SYNOPSIS
Convert an array to a binary string
USAGE
BString_Type array_to_bstring (Array_Type a)
DESCRIPTION
The `array_to_bstring' function returns the elements of an
array `a' as a binary string.
SEE ALSO
bstring_to_array, init_char_array
--------------------------------------------------------------
bstring_to_array
SYNOPSIS
Convert a binary string to an array of characters
USAGE
UChar_Type[] bstring_to_array (BString_Type b)
DESCRIPTION
The `bstring_to_array' function returns an array of unsigned
characters whose elements correspond to the characters in the
binary string.
SEE ALSO
array_to_bstring, init_char_array
--------------------------------------------------------------
bstrlen
SYNOPSIS
Get the length of a binary string
USAGE
UInt_Type bstrlen (BString_Type s)
DESCRIPTION
The `bstrlen' function may be used to obtain the length of a
binary string. A binary string differs from an ordinary string (a C
string) in that a binary string may include null chracters.
EXAMPLE
variable s = "hello\0";
len = bstrlen (s); % ==> len = 6
len = strlen (s); % ==> len = 5
SEE ALSO
strlen, length
--------------------------------------------------------------
pack
SYNOPSIS
Pack objects into a binary string
USAGE
BString_Type pack (String_Type fmt, ...)
DESCRIPTION
The `pack' function combines zero or more the objects (represented
by the ellipses above) into a binary string acording to the format
string `fmt'.
The format string consists of one or more data-type specification
characters, and each may be followed by an optional decimal length
specifier. Specifically, the data-types are specified according to
the following table:
c char
C unsigned char
h short
H unsigned short
i int
I unsigned int
l long
L unsigned long
j 16 bit int
J 16 unsigned int
k 32 bit int
K 32 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
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' or
`S' specifiers, it indicates the field width to be used. If the
length specifier is not present, the length defaults to one.
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 character are
stripped when unpacking an object given 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"
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 to the format `fmt' such that the data types
specified by the format will be properly aligned for the system.
This is especially important when reading or writing files that
assume the native alignment.
See the S-Lang User's Guide for more information about the use of
this function.
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.
NOTES
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
--------------------------------------------------------------
_clear_error
SYNOPSIS
Clear an error condition
USAGE
_clear_error ()
DESCRIPTION
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
--------------------------------------------------------------
_debug_info
SYNOPSIS
Configure debugging information
USAGE
Integer_Type _debug_info
DESCRIPTION
The `_debug_info' variable controls whether or not extra code
should be generated for additional debugging and traceback
information. Currently, if `_debug_info' is zero, no extra code
will be generated; otherwise extra code will be inserted into the
compiled bytecode for additional debugging data.
The value of this variable is is local to each compilation unit and
setting its value in one unit has no effect upon its value in other
units.
EXAMPLE
_debug_info = 1; % Enable debugging information
NOTES
Setting this variable to a non-zero value may slow down the
interpreter somewhat.
SEE ALSO
_traceback, _slangtrace
--------------------------------------------------------------
_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
--------------------------------------------------------------
_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
--------------------------------------------------------------
_traceback
SYNOPSIS
Generate a traceback upon error
USAGE
Integer_Type _traceback
DESCRIPTION
`_traceback' is an intrinsic integer variable whose value
controls whether or not a traceback of the call stack is to be
generated upon error. If `_traceback' is greater than zero, a
full traceback will be generated, which includes the values of local
variables. If the value is less than zero, a traceback will be
generated without local variable information, and if
`_traceback' is zero the traceback will not be generated.
Local variables are represented in the form `$n' where `n' is an
integer numbered from zero. More explicitly, `$0' represents the
first local variable, `$1' represents the second, and so on.
Please note that function parameters are local variables and that the
first parameter corresponds to `$0'.
SEE ALSO
_slangtrace, error
--------------------------------------------------------------
chdir
SYNOPSIS
Change the current working directory.
USAGE
Integer_Type chdir (String_Type dir)
DESCRIPTION
The `chdir' function may be used to changed the current working
directory to the directory specified by `dir'. Upon sucess it
returns zero; however, upon failure it returns `-1' and sets
`errno' accordingly.
SEE ALSO
mkdir, stat_file
--------------------------------------------------------------
chmod
SYNOPSIS
Change the mode of a file
USAGE
Integer_Type chmod (String_Type file, Integer_Type mode)
DESCRIPTION
The `chmod' function changes the permissions of `file' to those
specified 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
Integer_Type chown (String_Type file, Integer_Type uid, Integer_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
`zero' upon success and `-1' upon failure, with `errno'
set accordingly.
NOTES
On most systems, only the super user can change the ownership of a
file.
Some systems do not support this function.
SEE ALSO
chmod, stat_file
--------------------------------------------------------------
getcwd
SYNOPSIS
Get the current working directory
USAGE
String_Type getcwd ()
DESCRIPTION
The `getcwd' function returns the absolute pathname of the
current working directory. If an error occurs or it cannot
determine the working directory, it returns `NULL' and sets
`errno' accordingly.
NOTES
Under Unix, OS/2, and MSDOS, the pathname returned by this function
includes the trailing slash character. Some versions also include
the drive specifier.
SEE ALSO
mkdir, chdir, errno
--------------------------------------------------------------
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, readlink
--------------------------------------------------------------
mkdir
SYNOPSIS
Create a new directory
USAGE
Integer_Type mkdir (String_Type dir, Integer_Type mode)
DESCRIPTION
The `mkdir' function creates a directory whose name is specified
by the `dir' parameter with permissions specified by `mode'.
Upon success `mkdir' returns zero, or it returns `-1' and
sets `errno' accordingly. In particular, if the directory
already exists, the function will fail and set errno to
`EEXIST'.
EXAMPLE
define my_mkdir (dir)
{
if (0 == mkdir (dir, 0777)) return;
if (errno == EEXIST) return;
verror ("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 and
returns it as a string. Upon failure, NULL is returned and
`errno' set accordingly.
NOTES
Not all systems support this function.
SEE ALSO
lstat_file, stat_file, stat_is
--------------------------------------------------------------
remove
SYNOPSIS
Delete a file
USAGE
Integer_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
Integer_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 do not refer to 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
Integer_Type rmdir (String_Type dir)
DESCRIPTION
The `rmdir' function deletes a 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 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 man page for `stat' for a discussion 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) verror ("Unable to stat %s", file);
return st.st_size;
}
SEE ALSO
lstat_file, stat_is
--------------------------------------------------------------
stat_is
SYNOPSIS
Parse the var{st_mode
USAGE
Char_Type stat_is (String_Type type, Integer_Type st_mode)
DESCRIPTION
The `stat_is' function returns a signed character value about
the type of file specified by `st_mode'. 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
--------------------------------------------------------------
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.
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
--------------------------------------------------------------
byte_compile_file
SYNOPSIS
Compile a file to byte-code for faster loading.
USAGE
byte_compile_file (String_Type file, Integer_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 the function produces a new file named
`site.slc'.
NOTES
The `method' parameter is not used in the current
implementation. Its use is reserved for the future. For now, set
it to `0'.
SEE ALSO
evalfile
--------------------------------------------------------------
eval
SYNOPSIS
Interpret a string as slang code
USAGE
eval (String_Type expression)
DESCRIPTION
The `eval' function parses a string as S-Lang code and executes the
result. This is a useful function in many contexts such as dynamically
generating function definitions where there is no way to generate
them otherwise.
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 slang code.
USAGE
Integer_Type evalfile (String_Type file)
DESCRIPTION
The `evalfile' function loads `file' into the interpreter.
If no errors were encountered, `1' will be returned; otherwise,
a S-Lang error will be generated and the function will return zero.
EXAMPLE
define load_file (file)
{
ERROR_BLOCK { _clear_error (); }
() = evalfile (file);
}
SEE ALSO
eval, 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 accessable
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 seaches 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 global namespace.
This function signals an error 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 accessable
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.
SEE ALSO
import, get_import_module_path
--------------------------------------------------------------
_NARGS
SYNOPSIS
The number of parameters passed to a function
USAGE
Integer_Type _NARGS
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 (__pop_args (_NARGS))
{
arg = ();
vmessage ("Argument value is: %S", arg.value);
}
}
SEE ALSO
__pop_args, __push_args, typeof
--------------------------------------------------------------
__get_defined_symbols
SYNOPSIS
Get the symbols defined by the preprocessor
USAGE
Integer_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
--------------------------------------------------------------
__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
For 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.
NOTES
It is easy to see why a reference to the variable must be passed to
`__is_initialized' and not the variable itself; otherwise, the
value of the variable would be passed and the variable may have no
value if it was not initialized.
SEE ALSO
__get_reference, __uninitialize, is_defined, typeof, eval
--------------------------------------------------------------
_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 representing the
matches.
The second 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 (a)
{
name = ();
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
--------------------------------------------------------------
_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
--------------------------------------------------------------
_slang_doc_dir
SYNOPSIS
Installed documentation directory
USAGE
String_Type _slang_doc_dir;
DESCRIPTION
The `_slang_doc_dir' variable is a read-only whose value
specifies the 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
The `_slang_version' variable is read-only and and whose
value represents the 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
The `_slang_version_string' variable is read-only and whose
value represents the version number of the S-Lang library.
SEE ALSO
_slang_version
--------------------------------------------------------------
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
`get_doc_string_from_file' opens the documentation file `f'
and searches it for topic `t'. It returns the documentation for
`t' upon success, otherwise it returns `NULL' upon error.
It will fail if `f' could not be opened or does not contain
documentation for the topic.
SEE ALSO
stat_file
SEE ALSO
_slang_doc_dir
--------------------------------------------------------------
is_defined
SYNOPSIS
Indicate whether a variable or function defined.
USAGE
Integer_Type is_defined (String_Type obj)
DESCRIPTION
This function is used to determine whether or not a function or
variable whose name is `obj' has been defined. If `obj' is not
defined, the function returns 0. Otherwise, it returns a non-zero
value that defpends on the type of object `obj' represents.
Specifically, it returns one of the following values:
+1 if an intrinsic function
+2 if user defined function
-1 if intrinsic variable
-2 if user defined variable
0 if undefined
EXAMPLE
For 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
--------------------------------------------------------------
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
--------------------------------------------------------------
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
--------------------------------------------------------------
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
--------------------------------------------------------------
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 an number
USAGE
y = acos (x)
DESCRIPTION
The `acos' function computes the arc-cosine of a number and
returns the result as an array. 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 an number
USAGE
y = acosh (x)
DESCRIPTION
The `acosh' function computes the inverse cosh of a number and
returns the result as an array. 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 an number
USAGE
y = asin (x)
DESCRIPTION
The `asin' function computes the arc-sine of a number and
returns the result as an array. 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 an number
USAGE
y = asinh (x)
DESCRIPTION
The `asinh' function computes the inverse-sinh of a number and
returns the result as an array. 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 an number
USAGE
y = atan (x)
DESCRIPTION
The `atan' function computes the arc-tangent of a number and
returns the result as an array. If its argument is an array, the
`atan' function will be applied to each element and the result returned
as an array.
SEE ALSO
cos, atan, acosh, cosh
--------------------------------------------------------------
atanh
SYNOPSIS
Compute the inverse-tanh of an number
USAGE
y = atanh (x)
DESCRIPTION
The `atanh' function computes the inverse-tanh of a number and
returns the result as an array. 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
--------------------------------------------------------------
cos
SYNOPSIS
Compute the cosine of an number
USAGE
y = cos (x)
DESCRIPTION
The `cos' function computes the cosine of a number and
returns the result as an array. If its argument is an array, the
`cos' function will be applied to each element and the result returned
as an array.
SEE ALSO
cos, atan, acosh, cosh
--------------------------------------------------------------
cosh
SYNOPSIS
Compute the hyperbolic cosine of an number
USAGE
y = cosh (x)
DESCRIPTION
The `cosh' function computes the hyperbolic cosine of a number and
returns the result as an array. 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
--------------------------------------------------------------
exp
SYNOPSIS
Compute the exponential of an number
USAGE
y = exp (x)
DESCRIPTION
The `exp' function computes the exponential of a number and
returns the result as an array. If its argument is an array, the
`exp' function will be applied to each element and the result returned
as an array.
SEE ALSO
cos, atan, acosh, cosh
--------------------------------------------------------------
log
SYNOPSIS
Compute the logarithm of an number
USAGE
y = log (x)
DESCRIPTION
The `log' function computes the logarithm of a number and
returns the result as an array. 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
--------------------------------------------------------------
log10
SYNOPSIS
Compute the base-10 logarithm of an number
USAGE
y = log10 (x)
DESCRIPTION
The `log10' function computes the base-10 logarithm of a number and
returns the result as an array. 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
--------------------------------------------------------------
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
--------------------------------------------------------------
polynom
SYNOPSIS
Evaluate a polynomial
USAGE
Double_Type polynom(Double_Type a, b, ...c, Integer_Type n, Double_Type x)
DESCRIPTION
The `polynom' function returns the value of the polynomial expression:
ax^n + bx^(n - 1) + ... c
NOTES
The `polynom' function should be extended to work with complex
and array data types. The current implementation is limited to
`Double_Type' quantities.
SEE ALSO
exp
--------------------------------------------------------------
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. The default value is `"%f"'
EXAMPLE
s = string (PI); % --> s = "3.14159"
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
string, sprintf, 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'), it returns
the sign of 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 an number
USAGE
y = sin (x)
DESCRIPTION
The `sin' function computes the sine of a number and
returns the result as an array. If its argument is an array, the
`sin' function will be applied to each element and the result returned
as an array.
SEE ALSO
cos, atan, acosh, cosh
--------------------------------------------------------------
sinh
SYNOPSIS
Compute the hyperbolic sine of an number
USAGE
y = sinh (x)
DESCRIPTION
The `sinh' function computes the hyperbolic sine of a number and
returns the result as an array. 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.
SEE ALSO
abs, mul2
--------------------------------------------------------------
sqrt
SYNOPSIS
Compute the square root of an number
USAGE
y = sqrt (x)
DESCRIPTION
The `sqrt' function computes the square root of a number and
returns the result as an array. 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 an number
USAGE
y = tan (x)
DESCRIPTION
The `tan' function computes the tangent of a number and
returns the result as an array. 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 an number
USAGE
y = tanh (x)
DESCRIPTION
The `tanh' function computes the hyperbolic tangent of a number and
returns the result as an array. 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
--------------------------------------------------------------
error
SYNOPSIS
Generate an error condition
USAGE
error (String_Type msg
DESCRIPTION
The `error' function generates a S-Lang error condition causing
the interpreter to start unwinding to top-level. It takes a single
string parameter which is displayed on the stderr output device.
The error condition may be cleared via an `ERROR_BLOCK' with the
`_clear_error' function. Consult \user-manual for more
information.
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, _clear_error, message
--------------------------------------------------------------
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 correspond to the
line at the bottom of the display window. The default message
device is the standard output device.
SEE ALSO
vmessage, sprintf, error
--------------------------------------------------------------
usage
SYNOPSIS
Generate a usage error
USAGE
usage (String_Type msg)
DESCRIPTION
The `usage' function generates a usage exception and displays
`msg' to the message device.
EXAMPLE
Suppose that some function `plot' plots an array of `x' and
`y' values. The such a function could be written to issue a
usage message if the wrong number of arguments were 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
USAGE
verror (String_Type fmt, ...)
DESCRIPTION
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, strictly speaking, the `verror'
function is not an intrinsic function. Rather it is a predefined
S-Lang function using a combination of `Sprintf' and
`error'.
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, strictly speaking, 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, verror
--------------------------------------------------------------
__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
For 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 mode, the hook could be called to setup keybindings
for the mode.
SEE ALSO
is_defined, typeof, eval, autoload, __is_initialized, __uninitialize
--------------------------------------------------------------
__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
--------------------------------------------------------------
_auto_declare
SYNOPSIS
Set automatic variable declaration mode
USAGE
Integer_Type _auto_declare
DESCRIPTION
The `_auto_declare' may be used to have all undefined variables
implicitely declared as `static'. If set to zero, any variable
must be declared witha `variable' declaration before it can be
used. If set to one, then any undeclared variabled will be declared
as a `static' global variable.
The `_auto_declare' variable is 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.
--------------------------------------------------------------
getenv
SYNOPSIS
Get the value of an environment variable
USAGE
String_Type getenv(String_Type var)
DESCRIPTION
The `getenv' function returns a string that represents the
value of an environment variable `var'. It will return
`NULL' if there is no environment variable whose name is given
by `var'.
EXAMPLE
if (NULL != getenv ("USE_COLOR"))
{
set_color ("normal", "white", "blue");
set_color ("status", "black", "gray");
USE_ANSI_COLORS = 1;
}
SEE ALSO
putenv, strlen, is_defined
--------------------------------------------------------------
implements
SYNOPSIS
Name a private namespace
USAGE
implements (String_Type name);
DESCRIPTION
The `implements' function may be used to name the private
namespace associated with the current compilation unit. Doing so
will enable access to the members of the namespace from outside the
unit. The name of the global namespace is `Global'.
EXAMPLE
Suppose that some file `t.sl' contains:
implements ("Ts_Private");
static define message (x)
{
Global->vmessage ("Ts_Private message: %s", x);
}
message ("hello");
will produce `"Ts_Private message: hello"'. This `message'
function may be accessed from outside via:
Ts_Private->message ("hi");
NOTES
Since `message' is an intrinsic function, it is global and may
not be redefined in the global namespace.
SEE ALSO
use_namespace, current_namespace, import
--------------------------------------------------------------
putenv
SYNOPSIS
Add or change an environment variable
USAGE
putenv (String_Type s)
DESCRIPTION
This functions adds string `s' to the environment. Typically,
`s' should of the form `"name=value"'. The function
signals a S-Lang error upon failure.
NOTES
This function is not available on all systems.
SEE ALSO
getenv, sprintf
--------------------------------------------------------------
use_namespace
SYNOPSIS
Change to another namespace
USAGE
use_namespace (String_Type name)
DESCRIPTION
The `use_namespace' function changes the current namespace to
the one specified by the parameter. If the specified namespace
does not exist, an error will be generated.
SEE ALSO
implements, current_namespace, import
--------------------------------------------------------------
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
current namespace. If the current namespace is anonymous, that is,
has not been given a name via the `implements' function, the
empty string `""' will be returned.
SEE ALSO
implements, use_namespace, import
--------------------------------------------------------------
path_basename
SYNOPSIS
Get the basename part of a pathname
USAGE
String_Type path_basename (String_Type path)
DESCRIPTION
The `path_basename' function returns the basename associated
with the `path' 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_concat
SYNOPSIS
Combine elements of a pathname
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 pathname. For example, on unix is
`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 pathname
USAGE
String_Type path_dirname (String_Type path)
DESCRIPTION
The `path_dirname' function returns the directory name
associated with a specified pathname.
NOTES
On systems that include a drive specifier as part of the pathname,
the value returned by this function will include the driver
specifier.
SEE ALSO
path_basename, path_extname, path_concat, path_is_absolute
--------------------------------------------------------------
path_extname
SYNOPSIS
Return the extension part of a pathname
USAGE
String_Type path_extname (String_Type path)
DESCRIPTION
The `path_extname' function returns the extension portion of a
specified pathname. If an extension is present, this function will
also include the dot as part of the extension, i.e., if `path'
is `file.c', then this function returns `".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_is_absolute
SYNOPSIS
Determine whether or not a pathname is absolute
USAGE
Int_Type path_is_absolute (String_Type path)
DESCRIPTION
The `path_is_absolute' function will return non-zero is
`path' refers to an absolute pathname, otherwise it returns zero.
SEE ALSO
path_dirname, path_basename, path_extname, path_concat
--------------------------------------------------------------
path_sans_extname
SYNOPSIS
Strip the extension from a pathname
USAGE
String_Type path_sans_extname (String_Type path)
DESCRIPTION
The `path_sans_extname' function removes the file name extension
(including the dot) from the path and returns the result.
SEE ALSO
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 open file descriptor of type
`FD_Type'. Upon success 0 is returned, otherwise the function
returns -1 and sets `errno' accordingly.
SEE ALSO
open, fclose, read, write
--------------------------------------------------------------
dup_fd
SYNOPSIS
Duplicate a file descriptor
USAGE
FD_Type dup_fd (FD_Type fd)
DESCRIPTION
The `dup_fd' function duplicates and file descriptor and returns
its duplicate. If the function fails, NULL will be returned and
`errno' set accordingly.
NOTES
This function is essentually a wrapper around the POSIX `dup'
function.
SEE ALSO
open, close
--------------------------------------------------------------
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 `File_Type' file pointer. Upon failure,
NULL is returned.
SEE ALSO
fopen, open, fclose, close, dup_fd
--------------------------------------------------------------
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 an `FD_Type' object.
SEE ALSO
fopen, fclose, fileno
--------------------------------------------------------------
lseek
SYNOPSIS
Reposition a file descriptor's file pointer
USAGE
Long_Type lseek (FD_Type fd, Long_Type ofs, int mode)
SEEK_SET Set the offset to ofs
SEEK_CUR Add ofs to the current offset
SEEK_END Add ofs to the current file size
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 file if it does not exists)
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)
If `O_CREAT' is used for the `flags' parameterm 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.
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
and sets `errno' upon failure. The number of bytes read may be
less than `num', and will be zero if an attempt is made to read
past the end of the file.
NOTES
`read' is a low-level function and may return -1 for a variety
of reasons. For example, if non-blocking I/O has been specified for
the open file descriptor and no data is available for reading then
the function will return -1 and set `errno' to `EAGAIN'.
SEE ALSO
fread, open, close, write
--------------------------------------------------------------
write
SYNOPSIS
Write to an open file descriptor
USAGE
UInt_Type write (FD_Type fd, BString_Type buf
DESCRIPTION
The `write' function attempts to write the bytes specified by
the `buf' parameter to the open file descriptor `fd'. It
returns the number of bytes successfully written, or -1 and sets
`errno' upon failure. The number of bytes written may be less
than `length(buf)'.
SEE ALSO
read, fwrite, open, close
--------------------------------------------------------------
errno
SYNOPSIS
Error code set by system functions.
USAGE
Integer_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:
EPERM "Not owner"
ENOENT "No such file or directory"
ESRCH "No such process"
ENXIO "No such device or address"
ENOEXEC "Exec format error"
EBADF "Bad file number"
ECHILD "No children"
ENOMEM "Not enough core"
EACCES "Permission denied"
EFAULT "Bad address"
ENOTBLK "Block device required"
EBUSY "Mount device busy"
EEXIST "File exists"
EXDEV "Cross-device link"
ENODEV "No such device"
ENOTDIR "Not a directory"
EISDIR "Is a directory"
EINVAL "Invalid argument"
ENFILE "File table overflow"
EMFILE "Too many open files"
ENOTTY "Not a typewriter"
ETXTBSY "Text file busy"
EFBIG "File too large"
ENOSPC "No space left on device"
ESPIPE "Illegal seek"
EROFS "Read-only file system"
EMLINK "Too many links"
EPIPE "Broken pipe"
ELOOP "Too many levels of symbolic links"
ENAMETOOLONG "File name too long"
EXAMPLE
The `mkdir' function will attempt to create a directory. If
that directory already exists, the function will fail and set
`errno' to `EEXIST'.
define create_dir (dir)
{
if (0 == mkdir (dir)) return;
if (errno != EEXIST)
error ("mkdir %s failied: %s", dir, errno_string);
}
SEE ALSO
errno_string, error, mkdir
--------------------------------------------------------------
errno_string
SYNOPSIS
Return a string describing an errno.
USAGE
String_Type errno_string (Integer_Type err)
DESCRIPTION
The `errno_string' function returns a string describing the
integer error code `err'. The variable `err' usually
corresponds to the `errno' intrinsic function. 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);
if (st == NULL)
verror ("%s: %s", file, errno_string (errno);
return st.st_size;
}
SEE ALSO
errno, stat, verror
--------------------------------------------------------------
getegid
SYNOPSIS
Get the effective group id
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
USAGE
Integer_Type getgid ()
DESCRIPTION
The `getgid' function returns the real group id of the current
process.
NOTES
This function is not supported by all systems.
SEE ALSO
getpid, getppid
--------------------------------------------------------------
getpid
SYNOPSIS
Get the current process id
USAGE
Integer_Type getpid ()
DESCRIPTION
The `getpid' function returns the current process identification
number.
SEE ALSO
getppid, getgid
--------------------------------------------------------------
getppid
SYNOPSIS
Get the parent process id
USAGE
Integer_Type getppid ()
DESCRIPTION
The `getpid' function returns the process identification
number of the parent process.
NOTES
This function is not supported by all systems.
SEE ALSO
getpid, getgid
--------------------------------------------------------------
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
sucess and `-1' upon failure setting errno accordingly.
EXAMPLE
The `kill' function may be used to determine whether or not
a specific process exists:
define process_exists (pid)
{
if (-1 == kill (pid, 0))
return 0; % Process does not exist
return 1;
}
NOTES
This function is not supported by all systems.
SEE ALSO
getpid
--------------------------------------------------------------
mkfifo
SYNOPSIS
Create a named pipe
USAGE
Int_Type mkfifo (String_Type name, Int_Type mode)
DESCRIPTION
The `mkfifo' attempts to create a named pipe with the specified
name and mode (modified by the process's umask). The function
returns 0 upon success, or -1 and sets `errno' upon failure.
NOTES
Not all systems support the `mkfifo' function and even on
systems that do implement the `mkfifo' system call, the
underlying file system may not support the concept of a named pipe,
e.g, an NFS filesystem.
SEE ALSO
stat_file
--------------------------------------------------------------
setgid
SYNOPSIS
Set the group-id of the current process
USAGE
Int_Type setgid (Int_Type gid)
DESCRIPTION
The `setgid' function sets the effective group-id of the current
process. It returns zero upon success, or -1 upon error and sets
`errno' appropriately.
NOTES
This function is not supported by all systems.
SEE ALSO
getgid, setuid
--------------------------------------------------------------
setpgid
SYNOPSIS
Set the process group-id
USAGE
Int_Type setpgid (Int_Type pid, Int_Type gid)
DESCRIPTION
The `setpgid' function sets the group-id `gid' of the
process whose process-id is `pid'. If `pid' is 0, then the
current process-id will be used. If `pgid' is 0, then the pid
of the affected process will be used.
If successful zero 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
--------------------------------------------------------------
setuid
SYNOPSIS
Set the user-id of the current process
USAGE
Int_Type setuid (Int_Type id)
DESCRIPTION
The `setuid' function sets the effective user-id of the current
process. It returns zero upon success, or -1 upon error and sets
`errno' appropriately.
NOTES
This function is not supported by all systems.
SEE ALSO
setgid, setpgid, getuid, geteuid
--------------------------------------------------------------
sleep
SYNOPSIS
Pause for a specified number of seconds
USAGE
sleep (Double_Type n)
DESCRIPTION
The `sleep' function delays the current process for the
specified number of seconds. If it is interrupted by a signal, it
will return prematurely.
NOTES
Not all system support sleeping for a fractional part of a second.
--------------------------------------------------------------
system
SYNOPSIS
Execute a shell command
USAGE
Integer_Type system (String_Type cmd)
DESCRIPTION
The `system' function may be used to execute the string
expression `cmd' in an inferior shell. This function is an
interface to the C `system' function which returns an
implementation-defined result. On Linux, it returns 127 if the
inferior shell could not be invoked, -1 if there was some other
error, otherwise it returns the return code for `cmd'.
EXAMPLE
define dir ()
{
() = system ("DIR");
}
displays a directory listing of the current directory under MSDOS or
VMS.
SEE ALSO
popen, listdir
--------------------------------------------------------------
umask
SYNOPSIS
Set the file creation mask
USAGE
Int_Type umask (Int_Type m)
DESCRIPTION
The `umask' function sets the file creation mask to `m' and
returns the previous mask.
SEE ALSO
stat_file
--------------------------------------------------------------
uname
SYNOPSIS
Get the system name
USAGE
Struct_Tye 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, pack, unpack
--------------------------------------------------------------
__pop_args
SYNOPSIS
Remove n function arguments from the stack
USAGE
variable args = __pop_args(Integer_Type n);
DESCRIPTION
This function together with the companion function `__push_args'
is useful for passing the arguments of a function to another function.
`__pop_args' returns an array of `n' structures with a
single structure field called `value', which represents the value
of the argument.
EXAMPLE
Consider the following `print' function. It prints all its
arguments to `stdout' separated by spaces:
define print ()
{
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 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 on the arguments passed to
the `ones' function onto the stack to be used when dereferencing
`Array_Type'.
SEE ALSO
__push_args, typeof, _pop_n
--------------------------------------------------------------
__push_args
SYNOPSIS
Remove 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 passing the arguments of one function to another.
See the desription of `__pop_args' for more information.
SEE ALSO
__pop_args, typeof, _pop_n
--------------------------------------------------------------
_pop_n
SYNOPSIS
Remove objects from the stack
USAGE
_pop_n (Integer_Type n);
DESCRIPTION
The `_pop_n' function pops `n' objects from the top of the
stack.
EXAMPLE
define add3 ()
{
variable x, y, z;
if (_NARGS != 3)
{
_pop_n (_NARGS);
error ("add3: Expecting 3 arguments");
}
(x, y, z) = ();
return x + y + z;
}
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. It does not
alter the stack and it is usually used for debugging purposes.
SEE ALSO
_stkdepth, string
--------------------------------------------------------------
_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 for `abs(n) > 1'.
SEE ALSO
_stkdepth, _stk_reverse, _pop_n, _print_stack
--------------------------------------------------------------
_stkdepth
USAGE
Get the number of objects currently on the stack.
SYNOPSIS
Integer_Type _stkdepth ()
DESCRIPTION
The `_stkdepth' function returns number of items on stack prior
to the call of `_stkdepth'.
SEE ALSO
_print_stack, _stk_reverse, _stk_roll
--------------------------------------------------------------
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 array. 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
--------------------------------------------------------------
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 S-Lang function. The simplest way to
handle the return value from `fclose' is to use it as:
() = 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
The `fclose' function does not close the `File_Type' object
returned from this function. The underlying file object must be
closed by the `close' function.
SEE ALSO
fileno, fopen, open, close, fclose
--------------------------------------------------------------
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 `0'
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 `0'
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 _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 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);
NOTES
Many C programmers disregard the return value from the `fflush'
function. The above example illustrates how to properly do this in
the S-Lang langauge.
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)
error("fopen %s failed." file);
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
fopen, fclose, fputs, fread, error
--------------------------------------------------------------
fgetslines
SYNOPSIS
Read all the lines from an open file
USAGE
String_Type[] fgetslines (File_Type fp)
DESCRIPTION
The `fgetslines' function returns all the remaining lines as an
array of strings in the file specified by the open file pointer
`fp'. If the file is empty, an empty string array will be
returned. The function returns `NULL' upon error.
EXAMPLE
The following function returns the number of lines in a file:
define count_lines_in_file (file)
{
variable fp, lines;
fp = fopen (file, "r");
if (fp == NULL)
return -1;
lines = fgetslines (fp);
if (lines == NULL)
return -1;
return length (lines);
}
Note that the file was implicitly closed by the function.
NOTES
This function should not be used if the file contains many lines
since that would require that all the lines be read into memory.
SEE ALSO
fgets, fread, fopen
--------------------------------------------------------------
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' a `File_Type' object which is meant to
be used in other operations that require an open file. 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 (file, str)
{
variable fp = fopen (file, "a");
if (fp == NULL) verror ("%s could not be opened", file);
() = fputs (string, fp);
() = fclose (fp);
}
Note that the return values from `fputs' and `fclose' are
ignored.
NOTES
There is no need to explicitly close a file opened with `fopen'.
If the returned `File_Type' object goes out of scope, S-Lang
will automatically close the file. However, explicitly closing a
file after use 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 characters 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) verror ("Unable to open %s", file);
if ((-1 == fputs (s, fp))
or (-1 == fclose (fp)))
verror ("Error writing to %s", file);
}
NOTES
One must not disregard the return value from the `fputs'
function, as many C programmers do. 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
--------------------------------------------------------------
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 the variable specified by `b'. Upon error or end of
file, it returns `-1'. If more than one object is read from the
file, those objects will be placed in an array of the appropriate
size. The exception to this is when reading `Char_Type' or
`UChar_Type' objects from a file, in which case the data will be
returned as a BString_Type binary string.
EXAMPLE
The following example illustrates how to read 50 bytes from a file:
define read_50_bytes_from_file (file)
{
variable fp, n, buf;
fp = fopen (file, "rb");
if (fp == NULL) error ("Open failed");
n = fread (&buf, Char_Type, 50, fp);
if (n == -1)
error ("fread failed");
() = fclose (fp);
return buf;
}
NOTES
Use the `pack' and `unpack' functions to read data with a
specific byte-ordering.
SEE ALSO
fwrite, fgets, fopen, pack, unpack
--------------------------------------------------------------
fseek
SYNOPSIS
Reposition a stream
USAGE
Integer_Type fseek (File_Type fp, Integer_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 return zero 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));
}
NOTES
The current implementation uses an integer to specify the offset.
One some systems, a long integer may be required making this
function fail for very large files, i.e., files that are longer than
the maximum value of an integer.
SEE ALSO
ftell, fopen
--------------------------------------------------------------
ftell
SYNOPSIS
Obtain the current position in an open stream
USAGE
Integer_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'.
SEE ALSO
fseek, fopen
--------------------------------------------------------------
fwrite
SYNOPSIS
Write binary data to a file
USAGE
UInt_Type fwrite (b, File_Type fp)
DESCRIPTION
The `fwrite' 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 objects 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))
error ("fwrite failed");
Here is how to write the array one element at a time:
variable a = [1:50];
foreach (a)
{
variable ai = ();
if (1 != fwrite(ai, fp))
error ("fwrite failed");
}
NOTES
Not all data types may support the `fwrite' operation. However,
it is supported by all vector, scalar, and string objects.
SEE ALSO
fread, fputs, fopen, pack, unpack
--------------------------------------------------------------
pclose
SYNOPSIS
Close an object opened with popen
USAGE
Integer_Type pclose (File_Type fp)
DESCRIPTION
The `pclose' function waits for the process associated with
`fp' to exit and the returns the exit status of the command.
SEE ALSO
pclose, fclose
--------------------------------------------------------------
popen
SYNOPSIS
Open a 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 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.
SEE ALSO
pclose, fopen
--------------------------------------------------------------
printf
SYNOPSIS
Create and write a formatted string to stdout
USAGE
Int_Type printf (String_Type fmt, ...)
DESCRIPTION
`fprintf' 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 characters written to the file,
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, printf, fwrite, message
--------------------------------------------------------------
Sprintf
SYNOPSIS
Format objects into a string
USAGE
String_Type Sprintf (String_Type format, ..., Integer_Type n)
DESCRIPTION
`Sprintf' formats a string from `n' objects according to
`format'. Unlike `sprintf', the `Sprintf' function
requires the number of items to format.
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 a conversion specification
introduced by the `%' character. The `%' character must be
followed by at least one other character to specify the conversion:
s value is a string
f value is a floating point number
e print float in exponential form, e.g., 2.345e08
g print float as e or g, depending upon its value
c value is an ascii character
% print the percent character
d print a signed decimal integer
u print an unsigned decimal integer
o print an integer as octal
X print an integer as hexadecimal
S convert value to a string and format as string
Note that `%S' is a S-Lang extension which will cause the value
to be formatted as string. In fact, `sprintf("%S",x)' is
equivalent to `sprintf("%s",string(x))'.
s = Sprintf("%f is greater than %f but %s is better than %s\n",
PI, E, "Cake" "Pie", 4);
The final argument to `Sprintf' is the number of items to format; in
this case, there are 4 items.
SEE ALSO
sprintf, string, sscanf
--------------------------------------------------------------
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
Integer_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
One use for this function is to construct path names, e.g.,
create_delimited_string ("/", "user", "local", "bin", 3);
will produce `"usr/local/bin"'.
NOTES
The expression `strcat(a,b)' is equivalent to
`create_delimited_string("", a, b, 2)'.
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, Integer_Type nth, Integer_Type delim);
DESCRIPTION
The `extract_element' function may be used to extract the
`nth' element of the `delim' delimited list of strings
`list'. The function will return the `nth' element of the
list, unless `nth' specifies more elements than the list
contains, in which case `NULL' will be returned.
Elements in the list 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));
}
SEE ALSO
is_list_element, is_substr, strtok, strchop, create_delimited_string
--------------------------------------------------------------
is_list_element
SYNOPSIS
Test whether a delimited string contains a specific element
USAGE
Integer_Type is_list_element (String_Type list, String_Type elem, Integer_Type delim)
DESCRIPTION
The `is_list_element' function may be used to determine whether
or not a delimited list of strings, `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
Integer_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 occurance of `b' in `a'.
NOTES
It is important to remember that the first character of a string
corresponds to a position value of `1'.
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, and double quote characters are expanded.
SEE ALSO
eval, str_quote_string
--------------------------------------------------------------
sprintf
SYNOPSIS
Format objects into a string
USAGE
String sprintf (String format, ...);
DESCRIPTION
This function performs a similar task as the C function with the same
name. It differs from the S-Lang function `Sprintf' in that it
does not require the number of items to format.
See the documentation for `Sprintf' for more information.
SEE ALSO
Sprintf, string, sscanf, vmessage
--------------------------------------------------------------
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 `-1' 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 `%' 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 by 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 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
precession floating point number for floating point conversions.
The format specifier is a character that specifies the conversion:
% Matches a literal percent character. No assigment 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 hexidecimal integer, decimal integer, or
octal integer.
I Equivalent to `li'.
x Matches a hexidecimal integer.
X Matches a long hexidecimal 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_match
--------------------------------------------------------------
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 `del_set' from the string `str'. The result is returned.
EXAMPLE
str = str_delete_chars (str, "^A-Za-z");
will remove all characters except `A-Z' and `a-z' from
`str'.
--------------------------------------------------------------
str_quote_string
SYNOPSIS
Escape characters in a string.
USAGE
String_Type str_quote_string(String_Type str, String_Type qlis, Integer_Type quote)
DESCRIPTION
The `str_quote_string' returns a string identical to `str'
except that all characters in the set specified by 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
USAGE
Integer_Type str_replace (String_Type a, String_Type b, String_Type c)
DESCRIPTION
The `str_replace' function replaces the first occurance of `b' in
`a' with `c' and returns an integer that indicates whether a
replacement was made or not. If `b' does not occur in `a', zero is
returned. However, if `b' occurs in `a', a non-zero integer is
returned as well as the new string resulting from the replacement.
NOTES
This function has been superceded by `strreplace'.
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 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 multicharacter comment delimiters and it
assumes that comments are not nested.
SEE ALSO
str_quote_string
--------------------------------------------------------------
strcat
SYNOPSIS
Concatenate strings
USAGE
String_Type strcat (String_Type a_1, ..., String_Type a_N)
DESCRIPTION
The `strcat' function concatenates its N `String_Type'
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 string.
SEE ALSO
sprintf, create_delimited_string
--------------------------------------------------------------
strchop
SYNOPSIS
Chop or split a string into substrings.
USAGE
String_Type[] strchop (String_Type str, Integer_Type delim, Integer_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, &strcmp);
b = b[i]; % rearrange
% Convert array back into comma separated form
return strjoin (b, ",");
}
NOTES
The semantics of this `strchop' and `strchopr' have been
changed since version 1.2.x of the interpreter. Old versions of
these functions returned the values on the stack, which meant that
one could not chop up arbitrarily long strings that consist of
many substrings.
The function `strchopr' should be used if it is desired to have
the string chopped-up in the reverse order.
SEE ALSO
strchopr, extract_element, 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, extract_element, strtok, strjoin
--------------------------------------------------------------
strcmp
SYNOPSIS
Compare two strings
USAGE
Interpret strcmp (String_Type a, String_Type b)
DESCRIPTION
The `strcmp' function may be used to perform a case-sensitive
string comparison, in the lexicongraphic 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'.
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"'.
SEE ALSO
strtrim, strtrans
--------------------------------------------------------------
string_match
SYNOPSIS
Match a string against a regular expression
USAGE
Integer_Type string_match(String_Type str, String_Type pat, Integer_Type pos)
DESCRIPTION
The `string_match' function returns zero if `str' does not
match regular expression specified by `pat'. This function
performs the match starting at position `pos' (numbered from 1) in
`str'. This function returns the position of the start of the
match. To find the exact substring actually matched, use
`string_match_nth'.
SEE ALSO
string_match_nth, strcmp, strncmp
--------------------------------------------------------------
string_match_nth
SYNOPSIS
Get the result of the last call to string_match
USAGE
(Integer_Type, Integer_Type) = string_match_nth(Integer_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 offset into the string and the length of characters matches by
the `nth' submatch.
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]+\\)", 1);
if (matched) (pos, len) = string_match_nth(2);
This will set `matched' to 1 since a match will be found at the
first position, `pos' to 6 since `w' is offset 6 characters
from the beginning of the string, and `len' to 5 since
`"world"' is 5 characters 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.
Note also that `string_match_nth' returns the _offset_ from
the beginning of the string and not the position of the match.
SEE ALSO
string_match
--------------------------------------------------------------
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 a delimiter `delim'.
If `delim' is the empty string `""', then the result will
simply be the 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
create_delimited_string, strchop, strcat
--------------------------------------------------------------
strlen
SYNOPSIS
Compute the length of a string
USAGE
Integer_Type strlen (String_Type a)
DESCRIPTION
The `strlen' function may be used to compute the length of a string.
EXAMPLE
After execution of
variable len = strlen ("hello");
`len' will have a value of `5'.
SEE ALSO
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 comprise `s' will be 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.
SEE ALSO
strup, tolower, strcmp, strtrim, define_case
--------------------------------------------------------------
strncmp
SYNOPSIS
Compare the first few characters of two strings
USAGE
Integer_Type strncmp (String_Type a, String_Type b, Integer_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.
EXAMPLE
The expression
strcmp ("apple", "appliance", 3);
will return zero since the first three characters match.
SEE ALSO
strcmp, strlen
--------------------------------------------------------------
strreplace
SYNOPSIS
Replace one or more substrings
USAGE
(new, n) = strreplace (a, b, c, max_n)
String_Type a, b, c, rep;
Int_Type n, max_n;
DESCRIPTION
The `strreplace' function may be used to replace one or more
occurances of `b' in `a' with `c'. If the integer
`max_n' is positive, then the first `max_n' occurances of
`b' in `a' will be replaced. Otherwise, if `max_n' is
negative, then the last `abs(max_n)' occurances will be replaced.
The function returns the resulting string and an integer indicating
how many replacements were made.
EXAMPLE
The following function illustrates how `strreplace' may be used
to remove all occurances of a specified substring
define delete_substrings (a, b)
{
(a, ) = strreplace (a, b, "", strlen (a));
return a;
}
SEE ALSO
is_substr, strsub, strtrim, strtrans, str_delete_chars
--------------------------------------------------------------
strsub
SYNOPSIS
Replace a character with another in a string.
USAGE
String_Type strsub (String_Type s, Integer_Type pos, Integer_Type ch)
DESCRIPTION
The `strsub' character may be used to substitute the character
`ch' for the character at 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.
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 specifiy 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.
If the second parameter is not present, then it defaults to
`" \t\r\n\f"'.
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-zA-Z");
count += length (line);
}
() = fclose (fp);
return count;
}
SEE ALSO
strchop, strcompress, extract_element, 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 `new_set' will be removed from `str'.
This function returns the result.
EXAMPLE
str = strtrans (str, "A-Z", "a-z"); % lower-case str
str = strtrans (str, "^0-9", " "); % Replace anything but 0-9 by space
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 `" \t\r\n"'.
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. If the argument is not present, then the set defaults
to `" \t\r\n"'.
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. If the argument is not present, then the set defaults
to `" \t\r\n"'.
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 comprise `s' will be 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.
SEE ALSO
strlow, toupper, strcmp, strtrim, define_case, strtrans
--------------------------------------------------------------
substr
SYNOPSIS
Extract a substring from a string
USAGE
String_Type substr (String_Type s, Integer_Type n, Integer_Type len)
DESCRIPTION
The `substr' function returns a substring with length `len'
of the string `s' beginning at position `n'. If `len' is
`-1', the entire length of the string `s' will be used for
`len'. The first character of `s' is given by `n' equal
to 1.
EXAMPLE
substr ("To be or not to be", 7, 5);
returns `"or no"'
NOTES
In many cases it is more convenient to use array indexing rather
than the `substr' function. In fact, `substr(s,i+1,strlen(s))' is
equivalent to `s[[i:]]'.
SEE ALSO
is_substr, strlen
--------------------------------------------------------------
_push_struct_field_values
SYNOPSIS
Push the values of a structure's fields onto the stack
USAGE
Integer_Type num = _push_struct_field_values (Struct_Type s)
DESCRIPTION
The `_push_struct_field_values' function pushes the values of
all the fields of a structure onto the stack, returning the
number of items pushed. The fields are pushed such that the last
field of the structure is pushed first.
SEE ALSO
get_struct_field_names, get_struct_field
--------------------------------------------------------------
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'.
EXAMPLE
The following example illustrates how this function may be used to
to print the value of a structure.
define print_struct (s)
{
variable name;
foreach (get_struct_field_names (s))
{
name = ();
value = get_struct_field (s, name);
vmessage ("s.%s = %s\n", name, string(value));
}
}
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 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 (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 the parameter
refers to a structure or a user-defined type. If the object is
neither, 0 will be returned.
SEE ALSO
typeof, _typeof
--------------------------------------------------------------
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
--------------------------------------------------------------
_time
SYNOPSIS
Get the current time in seconds
USAGE
ULong_Type _time ()
DESCRIPTION
The `_time' function returns the number of elapsed seconds since
00:00:00 GMT, January 1, 1970. The `ctime' function may be used
to convert this into a string representation.
SEE ALSO
ctime, time, localtime, gmtime
--------------------------------------------------------------
ctime
SYNOPSIS
Convert a calendar time to a string
USAGE
String_Type ctime(ULong_Type secs)
DESCRIPTION
This function returns a string representation of the time as given
by `secs' seconds since 1970.
SEE ALSO
time, _time, localtime, gmtime
--------------------------------------------------------------
gmtime
SYNOPSIS
Break down a time in seconds to 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
--------------------------------------------------------------
localtime
SYNOPSIS
Break down a time in seconds to 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
--------------------------------------------------------------
tic
SYNOPSIS
Start timing
USAGE
void tic ()
DESCRIPTION
The `tic' function restarts the internal clock used for timing
the execution of commands. To get the elapsed time of the clock,
use the `toc' function.
SEE ALSO
toc, times
--------------------------------------------------------------
time
SYNOPSIS
Return the current data 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
ctime, message, substr
--------------------------------------------------------------
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, _times
--------------------------------------------------------------
toc
SYNOPSIS
Get elapsed CPU time
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.
EXAMPLE
The `tic' and `toc' functions are ideal for timing the
execution of the interpreter:
variable a = "hello", b = "world", c, n = 100000, t;
tic (); loop (n) c = a + b; t = toc ();
vmessage ("a+b took %f seconds\n", t);
tic (); loop (n) c = strcat(a,b); t = toc ();
vmessage ("strcat took %f seconds\n", t);
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.
SEE ALSO
tic, times, _time
--------------------------------------------------------------
_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 or a floating point number. If it appears to be neither,
then a string is assumed. It returns one of three values depending on
the format of the string `s':
Integer_Type : If it appears to be an integer
Double_Type : If it appears to be a double
String_Type : Anything else.
For example, `_slang_guess_type("1e2")' returns
`Double_Type' but `_slang_guess_type("e12")' returns
`String_Type'.
SEE ALSO
integer, string, double
--------------------------------------------------------------
_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
--------------------------------------------------------------
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)
{
switch (_slang_guess_type (s))
{
case Double_Type:
return atof (s);
}
{
case Integer_Type:
return double (integer (s));
}
verror ("%s is is not a double", s);
}
SEE ALSO
typecast, double, _slang_guess_type
--------------------------------------------------------------
char
SYNOPSIS
Convert an ascii value into a string
USAGE
String_Type char (Integer_Type c)
DESCRIPTION
The `char' function converts an integer ascii value `c' to a string
of unit length such that the first character of the string is `c'.
For example, `char('a')' returns the string `"a"'.
SEE ALSO
integer, string, typedef
--------------------------------------------------------------
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.
SEE ALSO
strlow, strup
--------------------------------------------------------------
double
SYNOPSIS
Convert an object to double precision
USAGE
result = 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 `atoi'
function.
SEE ALSO
typecast, atoi, int
--------------------------------------------------------------
int
SYNOPSIS
Typecast an object to an integer
USAGE
int (s)
DESCRIPTION
This function performs a typecast of `s' from its data type to
an object of `Integer_Type'. If `s' is a string, it returns
returns the ascii value value of the first character 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 character 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 equalent to `typecast (s, Integer_Type)';
SEE ALSO
typecast, double, integer, char, isdigit
--------------------------------------------------------------
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 type-mismatch error will be generated.
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
--------------------------------------------------------------
isdigit
SYNOPSIS
Tests for a decimal digit character
USAGE
Integer_Type isdigit (String_Type s)
DESCRIPTION
This function returns a non-zero value if the first character in the
string `s' is a digit; otherwise, it returns zero.
EXAMPLE
A simple, user defined implementation of `isdigit' is
define isdigit (s)
{
return ((s[0] <= '9') and (s[0] >= '0'));
}
However, the intrinsic function `isdigit' executes many times faster
than the equivalent representation defined above.
NOTES
Unlike the C function with the same name, the S-Lang function takes
a string argument.
SEE ALSO
int, integer
--------------------------------------------------------------
string
SYNOPSIS
Convert an object to a string representation.
USAGE
Integer_Type string (obj)
DESCRIPTION
The `string' function may be used to convert an object
`obj' of any type to a string representation.
For example, `string(12.34)' returns `"12.34"'.
EXAMPLE
define print_anything (anything)
{
message (string (anything));
}
NOTES
This function is _not_ the same as typecasting to a `String_Type'
using the `typecast' function.
SEE ALSO
typecast, sprintf, integer, char
--------------------------------------------------------------
tolower
SYNOPSIS
Convert a character to lowercase.
USAGE
Integer_Type lower (Integer_Type ch)
DESCRIPTION
This function takes an integer `ch' and returns its lowercase
equivalent.
SEE ALSO
toupper, strup, strlow, int, char, define_case
--------------------------------------------------------------
toupper
SYNOPSIS
Convert a character to uppercase.
USAGE
Integer_Type toupper (Integer_Type ch)
DESCRIPTION
This function takes an integer `ch' and returns its uppercase
equivalent.
SEE ALSO
tolower, strup, strlow, int, char, define_case
--------------------------------------------------------------
typecast
SYNOPSIS
Convert an object from one data type to another.
USAGE
typecast (x, new_type)
DESCRIPTION
The `typecast' function performs a generic typecast operation on
`x' to convert it to `new_type'. If `x' represents an
array, the function will attempt to convert all elements of `x'
to `new_type'. Not all objects can be converted and a
type-mismatch error will result upon failure.
EXAMPLE
define to_complex (x)
{
return typecast (x, Complex_Type);
}
defines a function that converts its argument, `x' to a complex
number.
SEE ALSO
int, double, typeof
--------------------------------------------------------------
typeof
SYNOPSIS
Get the data type of an object.
USAGE
DataType_Type typeof (x)
DESCRIPTION
This function 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
--------------------------------------------------------------
