_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
--------------------------------------------------------------
_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
--------------------------------------------------------------
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
--------------------------------------------------------------
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
--------------------------------------------------------------
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
--------------------------------------------------------------
_apropos
SYNOPSIS
Generate a list of functions and variable
USAGE
Integer_Type _apropos (String_Type s, Integer_Type flags)
DESCRIPTION
The `_apropos' function may be used to get a list of all defined
objects whose name consists of the substring `s' and whose type
matches those specified by `flags'. It returns the number of
matches. If the number returned is non-zero, that number of strings
which represent the names of the matched objects will also be
present on the stack.
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;
n = _apropos (s, 0xF);
if (n) vmessage ("Found %d matches:", n);
else message ("No matches.");
loop (n)
{
name = ();
message (name);
}
}
prints a list of all matches.
NOTES
Since the function returns the matches to the stack, it is possible
that a stack overfow error could result if there are two many
matches. If this happens, the interpreter should be recompiled to
use a larger stack size.
SEE ALSO
is_defined, sprintf
--------------------------------------------------------------
_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
--------------------------------------------------------------
_function_name
SYNOPSIS
Returns the name of the currently executing function
USAGE
String _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
--------------------------------------------------------------
_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
--------------------------------------------------------------
_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
--------------------------------------------------------------
_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
--------------------------------------------------------------
_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
--------------------------------------------------------------
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];
}
SEE ALSO
typeof, reshape
--------------------------------------------------------------
array_sort
SYNOPSIS
Sort an array
USAGE
Array_Type array_sort (Array_Type a, String_Type f)
DESCRIPTION
`array_sort' sorts the array `a' into ascending order
according to the function specified by the name `f' and returns
an integer array that represents the result of the sort.
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.
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");
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]'.
NOTES
The current sorting algorithm is a heap-sort.
SEE ALSO
strcmp
--------------------------------------------------------------
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
--------------------------------------------------------------
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
--------------------------------------------------------------
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
--------------------------------------------------------------
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
--------------------------------------------------------------
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
is_list_element, extract_element, strchop, strcat
--------------------------------------------------------------
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
--------------------------------------------------------------
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
--------------------------------------------------------------
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
--------------------------------------------------------------
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
--------------------------------------------------------------
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
--------------------------------------------------------------
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
--------------------------------------------------------------
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;
}
SEE ALSO
is_list_element, is_substr, strchop, create_delimited_string
--------------------------------------------------------------
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, errno
--------------------------------------------------------------
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, error
--------------------------------------------------------------
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
--------------------------------------------------------------
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.
SEE ALSO
fclose, fopen, fgets
--------------------------------------------------------------
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
--------------------------------------------------------------
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
--------------------------------------------------------------
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
--------------------------------------------------------------
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 settting 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
strlen, strcat
--------------------------------------------------------------
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
--------------------------------------------------------------
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
--------------------------------------------------------------
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
--------------------------------------------------------------
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, str_replace
--------------------------------------------------------------
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
--------------------------------------------------------------
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
--------------------------------------------------------------
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
--------------------------------------------------------------
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
--------------------------------------------------------------
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
--------------------------------------------------------------
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
--------------------------------------------------------------
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
--------------------------------------------------------------
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.
SEE ALSO
array_info
--------------------------------------------------------------
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
--------------------------------------------------------------
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.
EXAMPLE
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
--------------------------------------------------------------
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, vmessage
--------------------------------------------------------------
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
Integer_Type stat_is (String_Type type, Integer_Type st_mode
DESCRIPTION
The `stat_is' function returns an integer 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
--------------------------------------------------------------
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.
EXAMPLE
define str_replace_all (orig, match, replacement)
{
while (str_replace (orig, match, replacement))
orig = ();
return orig;
}
is a function that replaces all occurances in a string.
SEE ALSO
is_substr, strsub, strtrim
--------------------------------------------------------------
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 two strings
USAGE
String_Type strcat (String_Type a, String_Type b)
DESCRIPTION
The `strcat' function takes two string valued quantities, `a' and
`b', concatenates them together and returns the result.
EXAMPLE
strcat ("Hello ", "World");
produces the string `"Hello World"'.
NOTES
This function is equivalent to the binary operation `a+b'.
SEE ALSO
sprintf, create_delimited_string
--------------------------------------------------------------
strchopr
SYNOPSIS
Chop or split a string into substrings.
USAGE
Integer_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
--------------------------------------------------------------
strchop
SYNOPSIS
Chop or split a string into substrings.
USAGE
Integer_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 to the stack a variable number
of objects. The top stack object represents the number of
substrings that are on the stack. For example,
strchop ("apples,oranges,pears", ',', 0);
will return the integer `3' to the top of the stack followed
by the three strings: `"apples"', `"oranges"', and
`"pears"'.
EXAMPLE
define list_to_array (list)
{
variable n, i, s, a;
n = strchop (list, ',', '\\');
a = String_Type [n];
for (i = 0; i < n; i++)
a[i] = (); % substring is on stack
return a;
}
This defines a function that converts a comma-separated list of
strings to string array containing the substrings.
NOTES
Since this function returns a variable number of values to the
stack, it cannot 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, create_delimited_string
--------------------------------------------------------------
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 strtrim (String_Type s, String_Type white)
DESCRIPTION
The `strcompress' function compresses the string `s' by
removing all repeated characters specified by by the characters of
`white' from the interior of `s'. 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
--------------------------------------------------------------
string_match_nth
SYNOPSIS
Get the result of the last call to var{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
--------------------------------------------------------------
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
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
--------------------------------------------------------------
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
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
--------------------------------------------------------------
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;
}
NOTES
The first character in the string `s' is specified by `pos'
equal to 1.
SEE ALSO
is_substr, str_replace, strlen
--------------------------------------------------------------
strtrim
SYNOPSIS
Remove whitespace from the ends of a string
USAGE
String_Type strtrim (String_Type s)
DESCRIPTION
The `strtrim' function removes all leading and trailing whitespace
characters from the string `s' and returns the result. Whitespace is
defined to be any combination of spaces, tabs, and newline characters.
SEE ALSO
int, strlow, strup, 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
--------------------------------------------------------------
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
The expression `substr(s, n, 1)' is equivalent to the array
index expression `s[n-1]'.
SEE ALSO
is_substr, strlen
--------------------------------------------------------------
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.
--------------------------------------------------------------
time
SYNOPSIS
Return the current data and time as a string
USAGE
String time ();
DESCRIPTION
This function returns the current time as a string of the form:
Sun Apr 21 13:34:17 1996
SEE ALSO
message, substr
--------------------------------------------------------------
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)) print ("x is an integer");
SEE ALSO
array_info, _slang_guess_type, typecast
--------------------------------------------------------------
unix_ctime
SYNOPSIS
Convert a calendar time to a string
USAGE
String_Type unix_ctime(Integer_Type secs)
DESCRIPTION
This function returns a string representation of the time as given
by `secs' seconds since 1970.
SEE ALSO
time
--------------------------------------------------------------
unix_kill
SYNOPSIS
Send a signal to a process
USAGE
Integer_Type unix_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 `unix_kill' function may be used to determine whether or not
a specific process exists:
define process_exists (pid)
{
if (-1 == unix_kill (pid, 0))
return 0; % Process does not exist
return 1;
}
NOTES
The `unix_kill' function is not available on all systems.
SEE ALSO
getpid
--------------------------------------------------------------
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
--------------------------------------------------------------
