diff options
Diffstat (limited to 'libslang/doc/text/slangfun.txt')
| -rw-r--r-- | libslang/doc/text/slangfun.txt | 5943 |
1 files changed, 5943 insertions, 0 deletions
diff --git a/libslang/doc/text/slangfun.txt b/libslang/doc/text/slangfun.txt new file mode 100644 index 0000000..3f35b89 --- /dev/null +++ b/libslang/doc/text/slangfun.txt @@ -0,0 +1,5943 @@ +_isnull + + SYNOPSIS + Check array for NULL elements + + USAGE + Char_Type[] = _isnull (a[]) + + DESCRIPTION + This function may be used to test for the presence of NULL elements + of an array. Specifically, it returns a `Char_Type' array of + with the same number of elements and dimensionality of the input + array. If an element of the input array is NULL, then the + corresponding element of the output array will be set to 1, + otherwise it will be set to 0. + + EXAMPLE + Set all NULL elements of a string array `A' to the empty + string `""': + + A[where(_isnull(A))] = ""; + + + NOTES + It is important to understand the difference between `A==NULL' + and `_isnull(A)'. The latter tests all elements of `A' + against NULL, whereas the former only tests `A' itself. + + SEE ALSO + where, array_map +-------------------------------------------------------------- + +_reshape + + SYNOPSIS + Copy an array to a new shape + + USAGE + Array_Type _reshape (Array_Type A, Array_Type I) + + DESCRIPTION + The `_reshape' function creates a copy of an array `A', + reshapes it to the form specified by `I' and returns the result. + The elements of `I' specify the new dimensions of the copy of + `A' and must be consistent with the number of elements `A'. + + EXAMPLE + If `A' is a `100' element 1-d array, a new array 2-d array of + size `20' by `5' may be created from the elements of `A' + by + + A = _reshape (A, [20, 5]); + + In this example, the original array was no longer needed. Hence, it + is preferable to make use of the `__tmp' operator to avoid the + creation of a new array, i.e., + + A = _reshape (__tmp(A), [20,5]); + + + NOTES + The `reshape' function performs a similar function to + `_reshape'. In fact, the `_reshape' function could have been + implemented via: + + define _reshape (a, i) + { + a = @a; % Make a new copy + reshape (a, i); + return a; + } + + + SEE ALSO + reshape, array_info +-------------------------------------------------------------- + +array_info + + SYNOPSIS + Returns information about an array + + USAGE + (Array_Type, Integer_Type, DataType_Type) array_info (Array_Type a) + + DESCRIPTION + The `array_info' function returns information about the array `a'. + It returns three values: an 1-d integer array specifying the + size of each dimension of `a', the number of dimensions of + `a', and the data type of `a'. + + EXAMPLE + The `array_info' function may be used to find the number of rows + of an array: + + define num_rows (a) + { + variable dims, num_dims, data_type; + + (dims, num_dims, data_type) = array_info (a); + return dims [0]; + } + + For 1-d arrays, this information is more easily obtained from the + `length' function. + + SEE ALSO + typeof, reshape, length, _reshape +-------------------------------------------------------------- + +array_map + + SYNOPSIS + Apply a function to each element of an array + + USAGE + Array_Type array_map (type, func, arg0, ...) + + DataType_Type type; + Ref_Type func; + + + DESCRIPTION + The `array_map' function may be used to apply a function to each + element of an array and returns the result as an array of a + specified type. The `type' parameter indicates what kind of + array should be returned and generally corresponds to the return + type of the function. The `arg0' parameter should be an array + and is used to determine the dimensions of the resulting array. If + any subsequent arguments correspond to an array of the same size, + then those array elements will be passed in parallel with the first + arrays arguments. + + EXAMPLE + The first example illustrates how to apply the `strlen' function + to an array of strings: + + S = ["", "Train", "Subway", "Car"]; + L = array_map (Integer_Type, &strlen, S); + + This is equivalent to: + + S = ["", "Train", "Subway", "Car"]; + L = Integer_Type [length (S)]; + for (i = 0; i < length (S); i++) L[i] = strlen (S[i]); + + + Now consider an example involving the `strcat' function: + + files = ["slang", "slstring", "slarray"]; + + exts = ".c"; + cfiles = array_map (String_Type, &strcat, files, exts); + % ==> cfiles = ["slang.c slstring.c slarray.c"]; + + exts = [".a",".b",".c"]; + xfiles = array_map (String_Type, &strcat, files, exts); + % ==> xfiles = ["slang.a", "slstring.b", "slarray.c"]; + + + NOTES + Many mathemetical functions already work transparantly on arrays. + For example, the following two statements produce identical results: + + B = sin (A); + B = array_map (Double_Type, &sin, A); + + + SEE ALSO + array_info, strlen, strcat, sin +-------------------------------------------------------------- + +array_sort + + SYNOPSIS + Sort an array + + USAGE + Array_Type array_sort (Array_Type a [, String_Type or Ref_Type f]) + + DESCRIPTION + `array_sort' sorts the array `a' into ascending order and + returns an integer array that represents the result of the sort. If + the optional second parameter `f' is present, the function + specified by `f' will be used to compare elements of `a'; + otherwise, a built-in sorting function will be used. + + If `f' is present, then it must be either a string representing + the name of the comparison function, or a reference to the function. + The sort function represented by `f' must be a S-Lang + user-defined function that takes two arguments. The function must + return an integer that is less than zero if the first parameter is + considered to be less than the second, zero if they are equal, and a + value greater than zero if the first is greater than the second. + + If the comparision function is not specified, then a built-in comparison + function appropriate for the data type will be used. For example, + if `a' is an array of character strings, then the sort will be + preformed using `strcmp'. + + The integer array returned by this function is simply an index that + indicates the order of the sorted array. The input array `a' is + not changed. + + EXAMPLE + An array of strings may be sorted using the `strcmp' function + since it fits the specification for the sorting function described + above: + + variable A = String_Type [3]; + A[0] = "gamma"; A[1] = "alpha"; A[2] = "beta"; + + variable I = array_sort (A, &strcmp); + + Alternatively, one may use + + variable I = array_sort (A); + + to use the built-in comparison function. + + After the `array_sort' has executed, the variable `I' will + have the values `[2, 0, 1]'. This array can be used to + re-shuffle the elements of `A' into the sorted order via the + array index expression `A = A[I]'. + + SEE ALSO + strcmp +-------------------------------------------------------------- + +cumsum + + SYNOPSIS + Compute the cumulative sum of an array + + USAGE + result = cumsum (Array_Type a [, Int_Type dim]) + + DESCRIPTION + The `cumsum' function performs a cumulative sum over the + elements of a numeric array and returns the resulting. If a second + argument is given, then it specifies the dimension of the array to + be summed over. For example, the cumulative sum of + `[1,2,3,4]', is the array `[1,1+2,1+2+3,1+2+3+4]', i.e., + `[1,3,6,10]'. + + SEE ALSO + sum +-------------------------------------------------------------- + +init_char_array + + SYNOPSIS + Initialize an array of characters + + USAGE + init_char_array (Array_Type a, String_Type s) + + DESCRIPTION + The `init_char_array' function may be used to initialize a + character array `a' by setting the elements of the array + `a' to the corresponding characters of the string `s'. + + EXAMPLE + The statements + + variable a = Char_Type [10]; + init_char_array (a, "HelloWorld"); + + creates an character array and initializes its elements to the + characters in the string `"HelloWorld"'. + + NOTES + The character array must be large enough to hold all the characters + of the initialization string. + + SEE ALSO + bstring_to_array, strlen, strcat +-------------------------------------------------------------- + +length + + SYNOPSIS + Get the length of an object + + USAGE + Integer_Type length (obj) + + DESCRIPTION + The `length' function may be used to get information about the + length of an object. For simple scalar data-types, it returns 1. + For arrays, it returns the total number of elements of the array. + + NOTES + If `obj' is a string, `length' returns 1 because a + `String_Type' object is considered to be a scalar. To get the + number of characters in a string, use the `strlen' function. + + SEE ALSO + array_info, typeof, strlen +-------------------------------------------------------------- + +max + + SYNOPSIS + Get the maximum value of an array + + USAGE + result = max (Array_Type a [,Int_Type dim]) + + DESCRIPTION + The `max' function examines the elements of a numeric array and + returns the value of the largest element. If a second argument is + given, then it specifies the dimension of the array to be searched. + In this case, an array of dimension one less than that of the input array + will be returned with the corresponding elements in the specified + dimension replaced by the minimum value in that dimension. + + EXAMPLE + Consider the 2-d array + + 1 2 3 4 5 + 6 7 8 9 10 + + generated by + + a = _reshape ([1:10], [2, 5]); + + Then `max(a)' will return `10', and `max(a,0)' will return + a 1-d array with elements + + 6 7 8 9 10 + + + SEE ALSO + max, sum, reshape +-------------------------------------------------------------- + +min + + SYNOPSIS + Get the minimum value of an array + + USAGE + result = min (Array_Type a [,Int_Type dim]) + + DESCRIPTION + The `min' function examines the elements of a numeric array and + returns the value of the smallest element. If a second argument is + given, then it specifies the dimension of the array to be searched. + In this case, an array of dimension one less than that of the input array + will be returned with the corresponding elements in the specified + dimension replaced by the minimum value in that dimension. + + EXAMPLE + Consider the 2-d array + + 1 2 3 4 5 + 6 7 8 9 10 + + generated by + + a = _reshape ([1:10], [2, 5]); + + Then `min(a)' will return `1', and `min(a,0)' will return + a 1-d array with elements + + 1 2 3 4 5 + + + SEE ALSO + max, sum, reshape +-------------------------------------------------------------- + +reshape + + SYNOPSIS + Reshape an array + + USAGE + reshape (Array_Type A, Array_Type I) + + DESCRIPTION + The `reshape' function changes the size of `A' to have the size + specified by the 1-d integer array `I'. The elements of `I' + specify the new dimensions of `A' and must be consistent with + the number of elements `A'. + + EXAMPLE + If `A' is a `100' element 1-d array, it can be changed to a + 2-d `20' by `5' array via + + reshape (A, [20, 5]); + + However, `reshape(A, [11,5])' will result in an error because + the `[11,5]' array specifies `55' elements. + + NOTES + Since `reshape' modifies the shape of an array, and arrays are + treated as references, then all references to the array will + reference the new shape. If this effect is unwanted, then use the + `_reshape' function instead. + + SEE ALSO + _reshape, array_info +-------------------------------------------------------------- + +sum + + SYNOPSIS + Sum over the elements of an array + + USAGE + result = sum (Array_Type a [, Int_Type dim]) + + DESCRIPTION + The `sum' function sums over the elements of a numeric array and + returns its result. If a second argument is given, then it + specifies the dimension of the array to be summed over. In this + case, an array of dimension one less than that of the input array + will be returned. + + If the input array is an integer type, then the resulting value will + be a `Double_Type'. If the input array is a `Float_Type', + then the result will be a `Float_Type'. + + EXAMPLE + The mean of an array `a' of numbers is + + sum(a)/length(a) + + + SEE ALSO + cumsum, transpose, reshape +-------------------------------------------------------------- + +transpose + + SYNOPSIS + Transpose an array + + USAGE + Array_Type transpose (Array_Type a) + + DESCRIPTION + The `transpose' function returns the transpose of a specified + array. By definition, the transpose of an array, say one with + elements `a[i,j,...k]' is an array whose elements are + `a[k,...,j,i]'. + + SEE ALSO + _reshape, reshape, sum, array_info +-------------------------------------------------------------- + +where + + SYNOPSIS + Get indices where an integer array is non-zero + + USAGE + Array_Type where (Array_Type a) + + DESCRIPTION + The `where' function examines an numeric array `a' and + returns an integer array giving the indices of `a' + where the corresponding element of `a' is non-zero. + + Although this function may appear to be simple or even trivial, it + is arguably one of the most important and powerful functions for + manipulating arrays. + + EXAMPLE + Consider the following: + + variable X = [0.0:10.0:0.01]; + variable A = sin (X); + variable I = where (A < 0.0); + A[I] = cos (X) [I]; + + Here the variable `X' has been assigned an array of doubles + whose elements range from `0.0' through `10.0' in + increments of `0.01'. The second statement assigns `A' to + an array whose elements are the `sin' of the elements of `X'. + The third statement uses the where function to get the indices of + the elements of `A' that are less than `0.0'. Finally, the + last statement substitutes into `A' the `cos' of the + elements of `X' at the positions of `A' where the + corresponding `sin' is less than `0'. The end result is + that the elements of `A' are a mixture of sines and cosines. + + SEE ALSO + array_info, sin, cos +-------------------------------------------------------------- + +assoc_delete_key + + SYNOPSIS + Delete a key from an Associative Array + + USAGE + assoc_delete_key (Assoc_Type a, String_Type k) + + DESCRIPTION + 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 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 success 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, [,String_Type namespace]) + + DESCRIPTION + The `eval' function parses a string as S-Lang code and executes the + result. If called with the optional namespace argument, then the + string will be evaluated in the specified namespace. + + 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, [,String_Type namespace]) + + DESCRIPTION + The `evalfile' function loads `file' into the interpreter + and executes it. If called with the optional namespace argument, + the file will be loaded into the specified namespace, which will be + created if necessary. If 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); + } + + + NOTES + For historical reasons, the return value of this function is not + really useful. + + The file is searched along an application-defined load-path. The + `get_slang_load_path' and `set_slang_load_path' functions + may be used to set and query the path. + + SEE ALSO + eval, autoload, set_slang_load_path, get_slang_load_path +-------------------------------------------------------------- + +get_slang_load_path + + SYNOPSIS + Get the value of the interpreter's load-path + + USAGE + String_Type get_slang_load_path () + + DESCRIPTION + This function retrieves the value of the delimiter-separated search + path used for loading files. + + NOTES + Some applications may not support the built-in load-path searching + facility provided by the underlying library. + + SEE ALSO + +-------------------------------------------------------------- + +set_slang_load_path + + SYNOPSIS + Set the value of the interpreter's load-path + + USAGE + set_slang_load_path (String_Type path) + + DESCRIPTION + This function may be used to set the value of the + delimiter-separated search path used by the `evalfile' and + `autoload' functions for locating files. + + EXAMPLE + + public define prepend_to_slang_load_path (p) + { + variable s = stat_file (p); + if (s == NULL) return; + if (0 == stat_is ("dir", s.st_mode)) + return; + + variable d = path_get_delimiter (); + set_slang_load_path (strcat (p, d, get_slang_load_path ())); + } + + + NOTES + Some applications may not support the built-in load-path searching + facility provided by the underlying library. + + SEE ALSO + get_slang_load_path, path_get_delimiter, evalfile, autoload +-------------------------------------------------------------- + +get_import_module_path + + SYNOPSIS + Get the search path for dynamically loadable objects + + USAGE + String_Type get_import_module_path () + + DESCRIPTION + The `get_import_module_path' may be used to get the search path + for dynamically shared objects. Such objects may be made 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, _get_namespaces +-------------------------------------------------------------- + +__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, _get_namespaces +-------------------------------------------------------------- + +_function_name + + SYNOPSIS + Returns the name of the currently executing function + + USAGE + String_Type _function_name () + + DESCRIPTION + This function returns the name of the currently executing function. + If called from top-level, it returns the empty string. + + SEE ALSO + _trace_function, is_defined +-------------------------------------------------------------- + +_get_namespaces + + SYNOPSIS + Returns a list of namespace names + + USAGE + String_Type[] _get_namespaces () + + DESCRIPTION + This function returns a string array containing the names of the + currently defined namespaces. + + SEE ALSO + _apropos, use_namespace, implements, __get_defined_symbols +-------------------------------------------------------------- + +_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 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 +-------------------------------------------------------------- + +__class_id + + SYNOPSIS + Return the class-id of a specified type + + USAGE + Int_Type __class_id (DataType_Type type)) + + DESCRIPTION + This function returns the internal class-id of a specified data type. + + SEE ALSO + typeof, _typeof, __class_type +-------------------------------------------------------------- + +__class_type + + SYNOPSIS + Return the class-type of a specified type + + USAGE + Int_Type __class_type (DataType_Type type)) + + DESCRIPTION + Internally S-Lang objects are classified according to four types: + scalar, vector, pointer, and memory managed types. For example, an + integer is implemented as a scalar, a complex number as a vector, + and a string is represented as a pointer. The `__class_type' + function returns an integer representing the class-type associated + with the specified data type. Specifically, it returns: + + 0 memory-managed + 1 scalar + 2 vector + 3 pointer + + + SEE ALSO + typeof, _typeof, __class_id +-------------------------------------------------------------- + +__eqs + + SYNOPSIS + Test for equality between two objects + + USAGE + Int_Type __eqs (a, b) + + DESCRIPTION + This function tests its two arguments for equalit and returns 1 + if they are equal, and 0 otherwise. To be equal, the data type of + the arguments must match and the values of the objects must + reference the same underlying object. + + EXAMPLE + __eqs (1, 1) ===> 1 + __eqs (1, 1.0) ===> 0 + __eqs ("a", 1) ===> 0 + __eqs ([1,2], [1,2]) ===> 0 + + SEE ALSO + typeof, __get_reference + + NOTES + This function should be thought of as a test for "sameness". +-------------------------------------------------------------- + +__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 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. +-------------------------------------------------------------- + +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 +-------------------------------------------------------------- + +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 +-------------------------------------------------------------- + +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_get_delimiter + + SYNOPSIS + Get the value of a search-path delimiter + + USAGE + Char_Type path_get_delimiter () + + DESCRIPTION + This function returns the value of the character used to delimit + fields of a search-path. + + SEE ALSO + set_slang_load_path, get_slang_load_path +-------------------------------------------------------------- + +path_is_absolute + + SYNOPSIS + Determine whether or not a 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 exist) + O_EXCL (fail if the file already exists) + O_NOCTTY (do not make the device the controlling terminal) + O_TRUNC (truncate the file if it exists) + O_APPEND (open the file in append mode) + O_NONBLOCK (open the file in non-blocking mode) + + Some of these flags only make sense when combined with other flags. + For example, if O_EXCL is used, then O_CREAT must also be + specified, otherwise unpredictable behavior may result. + + If `O_CREAT' is used for the `flags' parameter then the + `mode' parameter must be present. `mode' specifies the + permissions to use if a new file is created. The actual file + permissions will be affected by the process's `umask' via + `mode&~umask'. The `mode' parameter's value is + constructed via bitwise-or of the following values: + + S_IRWXU (Owner has read/write/execute permission) + S_IRUSR (Owner has read permission) + S_IWUSR (Owner has write permission) + S_IXUSR (Owner has execute permission) + S_IRWXG (Group has read/write/execute permission) + S_IRGRP (Group has read permission) + S_IWGRP (Group has write permission) + S_IXGRP (Group has execute permission) + S_IRWXO (Others have read/write/execute permission) + S_IROTH (Others have read permission) + S_IWOTH (Others have write permission) + S_IXOTH (Others have execute permission) + + Upon success `open' returns a file descriptor object + (`FD_Type'), otherwise `NULL' is returned and `errno' + is set. + + NOTES + If you are not familiar with the `open' system call, then it + is recommended that you use `fopen' instead. + + 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 + success 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 an `n' character BString_Type binary string, but + only if `n'>1. + + 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 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 `old_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 (s, name); + vmessage ("s.%s = %s\n", name, string (value)); + } + } + + + SEE ALSO + _push_struct_field_values, get_struct_field +-------------------------------------------------------------- + +is_struct_type + + SYNOPSIS + Determine whether or not an object is a structure + + USAGE + Integer_Type is_struct_type (X) + + DESCRIPTION + The `is_struct_type' function returns 1 if the parameter + refers to a structure or a user-defined type. If the object is + neither, 0 will be returned. + + SEE ALSO + typeof, _typeof +-------------------------------------------------------------- + +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 (short, int, long), floating point (float, + double), or a complex number. If it appears to be none of these, + then a string is assumed. It returns one of the following values + depending on the format of the string `s': + + Short_Type : short integer (e.g., "2h") + UShort_Type : unsigned short integer (e.g., "2hu") + Integer_Type : integer (e.g., "2") + UInteger_Type : unsigned integer (e.g., "2") + Long_Type : long integer (e.g., "2l") + ULong_Type : unsigned long integer (e.g., "2l") + Float_Type : float (e.g., "2.0f") + Double_Type : double (e.g., "2.0") + Complex_Type : imaginary (e.g., "2i") + String_Type : Anything else. (e.g., "2foo") + + For example, `_slang_guess_type("1e2")' returns + `Double_Type' but `_slang_guess_type("e12")' returns + `String_Type'. + + SEE ALSO + integer, string, double, atof +-------------------------------------------------------------- + +_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 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 the `atof' + function. + + SEE ALSO + typecast, atof, 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 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 +-------------------------------------------------------------- + |