_reshape SYNOPSIS Copy an array to a new shape USAGE Array_Type _reshape (Array_Type A, Array_Type I) DESCRIPTION The `_reshape' function creates a copy of an array `A', reshapes it to the form specified by `I' and returns the result. The elements of `I' specify the new dimensions of the copy of `A' and must be consistent with the number of elements `A'. EXAMPLE If `A' is a `100' element 1-d array, a new array 2-d array of size `20' by `5' may be created from the elements of `A' by A = _reshape (A, [20, 5]); In this example, the original array was no longer needed. Hence, it is preferable to make use of the `__tmp' operator to avoid the creation of a new array, i.e., A = _reshape (__tmp(A), [20,5]); NOTES The `reshape' function performs a similar function to `_reshape'. In fact, the `_reshape' function could have been implemented via: define _reshape (a, i) { a = @a; % Make a new copy reshape (a, i); return a; } SEE ALSO reshape, array_info -------------------------------------------------------------- array_info SYNOPSIS Returns information about an array USAGE (Array_Type, Integer_Type, DataType_Type) array_info (Array_Type a) DESCRIPTION The `array_info' function returns information about the array `a'. It returns three values: an 1-d integer array array specifying the size of each dimension of `a', the number of dimensions of `a', and the data type of `a'. EXAMPLE The `array_info' function may be used to find the number of rows of an array: define num_rows (a) { variable dims, num_dims, data_type; (dims, num_dims, data_type) = array_info (a); return dims [0]; } For 1-d arrays, this information is more easily obtained from the `length' function. SEE ALSO typeof, reshape, length, _reshape -------------------------------------------------------------- array_map SYNOPSIS Apply a function to each element of an array USAGE Array_Type array_map (type, func, arg0, ...) DataType_Type type; Ref_Type func; DESCRIPTION The `array_map' function may be used to apply a function to each element of an array and returns the result as an array of a specified type. The `type' parameter indicates what kind of array should be returned and generally corresponds to the return type of the function. The `arg0' parameter should be an array and is used to determine the dimensions of the resulting array. If any subsequent arguments correspond to an array of the same size, then those array elements will be passed in parallel with the first arrays arguments. EXAMPLE The first example illustrates how to apply the `strlen' function to an array of strings: S = ["", "Train", "Subway", "Car"]; L = array_map (Integer_Type, &strlen, S); This is equivalent to: S = ["", "Train", "Subway", "Car"]; L = Integer_Type [length (S)]; for (i = 0; i < length (S); i++) L[i] = strlen (S[i]); Now consider an example involving the `strcat' function: files = ["slang", "slstring", "slarray"]; exts = ".c"; cfiles = array_map (String_Type, &strcat, files, exts); % ==> cfiles = ["slang.c slstring.c slarray.c"]; exts = [".a",".b",".c"]; xfiles = array_map (String_Type, &strcat, files, exts); % ==> xfiles = ["slang.a", "slstring.b", "slarray.c"]; NOTES Many mathemetical functions already work transparantly on arrays. For example, the following two statements produce identical results: B = sin (A); B = array_map (Double_Type, &sin, A); SEE ALSO array_info, strlen, strcat, sin -------------------------------------------------------------- array_sort SYNOPSIS Sort an array USAGE Array_Type array_sort (Array_Type a [, String_Type or Ref_Type f]) DESCRIPTION `array_sort' sorts the array `a' into ascending order and returns an integer array that represents the result of the sort. If the optional second parameter `f' is present, the function specified by `f' will be used to compare elements of `a'; otherwise, a built-in sorting function will be used. If `f' is present, then it must be either a string representing the name of the comparison function, or a reference to the function. The sort function represented by `f' must be a S-Lang user-defined function that takes two arguments. The function must return an integer that is less than zero if the first parameter is considered to be less than the second, zero if they are equal, and a value greater than zero if the first is greater than the second. If the comparision function is not specified, then a built-in comparison function appropriate for the data type will be used. For example, if `a' is an array of character strings, then the sort will be preformed using `strcmp'. The integer array returned by this function is simply an index that indicates the order of the sorted array. The input array `a' is not changed. EXAMPLE An array of strings may be sorted using the `strcmp' function since it fits the specification for the sorting function described above: variable A = String_Type [3]; A[0] = "gamma"; A[1] = "alpha"; A[2] = "beta"; variable I = array_sort (A, &strcmp); Alternatively, one may use variable I = array_sort (A); to use the built-in comparison function. After the `array_sort' has executed, the variable `I' will have the values `[2, 0, 1]'. This array can be used to re-shuffle the elements of `A' into the sorted order via the array index expression `A = A[I]'. SEE ALSO strcmp -------------------------------------------------------------- init_char_array SYNOPSIS Initialize an array of characters USAGE init_char_array (Array_Type a, String_Type s) DESCRIPTION The `init_char_array' function may be used to initialize a character array `a' by setting the elements of the array `a' to the corresponding characters of the string `s'. EXAMPLE The statements variable a = Char_Type [10]; init_char_array (a, "HelloWorld"); creates an character array and initializes its elements to the characters in the string `"HelloWorld"'. NOTES The character array must be large enough to hold all the characters of the initialization string. SEE ALSO bstring_to_array, strlen, strcat -------------------------------------------------------------- length SYNOPSIS Get the length of an object USAGE Integer_Type length (obj) DESCRIPTION The `length' function may be used to get information about the length of an object. For simple scalar data-types, it returns 1. For arrays, it returns the total number of elements of the array. NOTES If `obj' is a string, `length' returns 1 because a `String_Type' object is considered to be a scalar. To get the number of characters in a string, use the `strlen' function. SEE ALSO array_info, typeof, strlen -------------------------------------------------------------- reshape SYNOPSIS Reshape an array USAGE reshape (Array_Type A, Array_Type I) DESCRIPTION The `reshape' function changes the size of `A' to have the size specified by the 1-d integer array `I'. The elements of `I' specify the new dimensions of `A' and must be consistent with the number of elements `A'. EXAMPLE If `A' is a `100' element 1-d array, it can be changed to a 2-d `20' by `5' array via reshape (A, [20, 5]); However, `reshape(A, [11,5])' will result in an error because the the `[11,5]' array specifies `55' elements. NOTES Since `reshape' modifies the shape of an array, and arrays are treated as references, then all references to the array will reference the new shape. If this effect is unwanted, then use the `_reshape' function instead. SEE ALSO _reshape, array_info -------------------------------------------------------------- transpose SYNOPSIS Transpose a 2d array USAGE Array_Type transpose (Array_Type a) DESCRIPTION The `transpose' function returns the transpose of a specified array. By definition, the transpose of an array, say one with elements `a[i,j,...k]' is an array whose elements are `a[k,...,j,i]'. SEE ALSO _reshape, reshape, array_info -------------------------------------------------------------- where SYNOPSIS Get indices where an integer array is non-zero USAGE Array_Type where (Array_Type a) DESCRIPTION The `where' function examines an integer array `a' and returns a 2-d integer array whose rows are the indices of `a' where the corresponding element of `a' is non-zero. EXAMPLE Consider the following: variable X = [0.0:10.0:0.01]; variable A = sin (X); variable I = where (A < 0.0); A[I] = cos (X) [I]; Here the variable `X' has been assigned an array of doubles whose elements range from `0.0' through `10.0' in increments of `0.01'. The second statement assigns `A' to an array whose elements are the `sin' of the elements of `X'. The third statement uses the where function to get the indices of the elements of `A' that are less than `0.0'. Finally, the last statement substitutes into `A' the `cos' of the elements of `X' at the positions of `A' where the corresponding `sin' is less than `0'. The end result is that the elements of `A' are a mixture of sines and cosines. SEE ALSO array_info, sin, cos -------------------------------------------------------------- assoc_delete_key SYNOPSIS Delete a key from an Associative Array USAGE assoc_delete_key (Assoc_Type a, String_Type k) DESCRIPTION The `assoc_delete_key' function deletes a key given by `k' from the associative array `a'. If the specified key does not exist in `a', then this function has no effect. SEE ALSO assoc_key_exists, assoc_get_keys -------------------------------------------------------------- assoc_get_keys SYNOPSIS Return all the key names of an Associative Array USAGE String_Type[] assoc_get_keys (Assoc_Type a) DESCRIPTION This function returns all the key names of an associative array `a' as an ordinary one dimensional array of strings. If the associative array contains no keys, an empty array will be returned. EXAMPLE The following function computes the number of keys in an associative array: define get_num_elements (a) { return length (assoc_get_keys (a)); } SEE ALSO assoc_get_values, assoc_key_exists, assoc_delete_key, length -------------------------------------------------------------- assoc_get_values SYNOPSIS Return all the values of an Associative Array USAGE Array_Type assoc_get_keys (Assoc_Type a) DESCRIPTION This function returns all the values in the associative array `a' as an array of proper type. If the associative array contains no keys, an empty array will be returned. EXAMPLE Suppose that `a' is an associative array of type `Integer_Type', i.e., it was created via variable a = Assoc_Type[Integer_Type]; The the following may be used to print the values of the array in ascending order: static define int_sort_fun (x, y) { return sign (x - y); } define sort_and_print_values (a) { variable i, v; v = assoc_get_values (a); i = array_sort (v, &int_sort_fun); v = v[i]; foreach (v) { variable vi = (); () = fprintf (stdout, "%d\n", vi); } } SEE ALSO assoc_get_values, assoc_key_exists, assoc_delete_key, array_sort -------------------------------------------------------------- assoc_key_exists SYNOPSIS Check to see whether a key exists in an Associative Array USAGE Integer_Type assoc_key_exists (Assoc_Type a, String_Type k) DESCRIPTION The `assoc_key_exists' function may be used to determine whether or not a specified key `k' exists in an associative array `a'. It returns 1 if the key exists, or 0 if it does not. SEE ALSO assoc_get_keys, assoc_get_values, assoc_delete_key -------------------------------------------------------------- array_to_bstring SYNOPSIS Convert an array to a binary string USAGE BString_Type array_to_bstring (Array_Type a) DESCRIPTION The `array_to_bstring' function returns the elements of an array `a' as a binary string. SEE ALSO bstring_to_array, init_char_array -------------------------------------------------------------- bstring_to_array SYNOPSIS Convert a binary string to an array of characters USAGE UChar_Type[] bstring_to_array (BString_Type b) DESCRIPTION The `bstring_to_array' function returns an array of unsigned characters whose elements correspond to the characters in the binary string. SEE ALSO array_to_bstring, init_char_array -------------------------------------------------------------- bstrlen SYNOPSIS Get the length of a binary string USAGE UInt_Type bstrlen (BString_Type s) DESCRIPTION The `bstrlen' function may be used to obtain the length of a binary string. A binary string differs from an ordinary string (a C string) in that a binary string may include null chracters. EXAMPLE variable s = "hello\0"; len = bstrlen (s); % ==> len = 6 len = strlen (s); % ==> len = 5 SEE ALSO strlen, length -------------------------------------------------------------- pack SYNOPSIS Pack objects into a binary string USAGE BString_Type pack (String_Type fmt, ...) DESCRIPTION The `pack' function combines zero or more the objects (represented by the ellipses above) into a binary string acording to the format string `fmt'. The format string consists of one or more data-type specification characters, and each may be followed by an optional decimal length specifier. Specifically, the data-types are specified according to the following table: c char C unsigned char h short H unsigned short i int I unsigned int l long L unsigned long j 16 bit int J 16 unsigned int k 32 bit int K 32 bit unsigned int f float d double F 32 bit float D 64 bit float s character string, null padded S character string, space padded x a null pad character A decimal length specifier may follow the data-type specifier. With the exception of the `s' and `S' specifiers, the length specifier indicates how many objects of that data type are to be packed or unpacked from the string. When used with the `s' or `S' specifiers, it indicates the field width to be used. If the length specifier is not present, the length defaults to one. With the exception of `c', `C', `s', `S', and `x', each of these may be prefixed by a character that indicates the byte-order of the object: > big-endian order (network order) < little-endian order = native byte-order The default is to use native byte order. When unpacking via the `unpack' function, if the length specifier is greater than one, then an array of that length will be returned. In addition, trailing whitespace and null character are stripped when unpacking an object given by the `S' specifier. EXAMPLE a = pack ("cc", 'A', 'B'); % ==> a = "AB"; a = pack ("c2", 'A', 'B'); % ==> a = "AB"; a = pack ("xxcxxc", 'A', 'B'); % ==> a = "\0\0A\0\0B"; a = pack ("h2", 'A', 'B'); % ==> a = "\0A\0B" or "\0B\0A" a = pack (">h2", 'A', 'B'); % ==> a = "\0\xA\0\xB" a = pack (" 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 x = 0xCDABuh x = unpack ("xxs4", "a b c\0d e f"); % ==> x = "b c\0" x = unpack ("xxS4", "a b c\0d e f"); % ==> x = "b c" SEE ALSO pack, sizeof_pack, pad_pack_format -------------------------------------------------------------- _clear_error SYNOPSIS Clear an error condition USAGE _clear_error () DESCRIPTION This function may be used in error-blocks to clear the error that triggered execution of the error block. Execution resumes following the statement, in the scope of the error-block, that triggered the error. EXAMPLE Consider the following wrapper around the `putenv' function: define try_putenv (name, value) { variable status; ERROR_BLOCK { _clear_error (); status = -1; } status = 0; putenv (sprintf ("%s=%s", name, value); return status; } If `putenv' fails, it generates an error condition, which the `try_putenv' function catches and clears. Thus `try_putenv' is a function that returns `-1' upon failure and `0' upon success. SEE ALSO _trace_function, _slangtrace, _traceback -------------------------------------------------------------- _debug_info SYNOPSIS Configure debugging information USAGE Integer_Type _debug_info DESCRIPTION The `_debug_info' variable controls whether or not extra code should be generated for additional debugging and traceback information. Currently, if `_debug_info' is zero, no extra code will be generated; otherwise extra code will be inserted into the compiled bytecode for additional debugging data. The value of this variable is is local to each compilation unit and setting its value in one unit has no effect upon its value in other units. EXAMPLE _debug_info = 1; % Enable debugging information NOTES Setting this variable to a non-zero value may slow down the interpreter somewhat. SEE ALSO _traceback, _slangtrace -------------------------------------------------------------- _slangtrace SYNOPSIS Turn function tracing on or off. USAGE Integer_Type _slangtrace DESCRIPTION The `_slangtrace' variable is a debugging aid that when set to a non-zero value enables tracing when function declared by `_trace_function' is entered. If the value is greater than zero, both intrinsic and user defined functions will get traced. However, if set to a value less than zero, intrinsic functions will not get traced. SEE ALSO _trace_function, _traceback, _print_stack -------------------------------------------------------------- _trace_function SYNOPSIS Set the function to trace USAGE _trace_function (String_Type f) DESCRIPTION `_trace_function' declares that the S-Lang function with name `f' is to be traced when it is called. Calling `_trace_function' does not in itself turn tracing on. Tracing is turned on only when the variable `_slangtrace' is non-zero. SEE ALSO _slangtrace, _traceback -------------------------------------------------------------- _traceback SYNOPSIS Generate a traceback upon error USAGE Integer_Type _traceback DESCRIPTION `_traceback' is an intrinsic integer variable whose value controls whether or not a traceback of the call stack is to be generated upon error. If `_traceback' is greater than zero, a full traceback will be generated, which includes the values of local variables. If the value is less than zero, a traceback will be generated without local variable information, and if `_traceback' is zero the traceback will not be generated. Local variables are represented in the form `$n' where `n' is an integer numbered from zero. More explicitly, `$0' represents the first local variable, `$1' represents the second, and so on. Please note that function parameters are local variables and that the first parameter corresponds to `$0'. SEE ALSO _slangtrace, error -------------------------------------------------------------- chdir SYNOPSIS Change the current working directory. USAGE Integer_Type chdir (String_Type dir) DESCRIPTION The `chdir' function may be used to changed the current working directory to the directory specified by `dir'. Upon sucess it returns zero; however, upon failure it returns `-1' and sets `errno' accordingly. SEE ALSO mkdir, stat_file -------------------------------------------------------------- chmod SYNOPSIS Change the mode of a file USAGE Integer_Type chmod (String_Type file, Integer_Type mode) DESCRIPTION The `chmod' function changes the permissions of `file' to those specified by `mode'. It returns `0' upon success, or `-1' upon failure setting `errno' accordingly. See the system specific documentation for the C library function `chmod' for a discussion of the `mode' parameter. SEE ALSO chown, stat_file -------------------------------------------------------------- chown SYNOPSIS Change the owner of a file USAGE Integer_Type chown (String_Type file, Integer_Type uid, Integer_Type gid) DESCRIPTION The `chown' function is used to change the user-id and group-id of `file' to `uid' and `gid', respectively. It returns `zero' upon success and `-1' upon failure, with `errno' set accordingly. NOTES On most systems, only the super user can change the ownership of a file. Some systems do not support this function. SEE ALSO chmod, stat_file -------------------------------------------------------------- getcwd SYNOPSIS Get the current working directory USAGE String_Type getcwd () DESCRIPTION The `getcwd' function returns the absolute pathname of the current working directory. If an error occurs or it cannot determine the working directory, it returns `NULL' and sets `errno' accordingly. NOTES Under Unix, OS/2, and MSDOS, the pathname returned by this function includes the trailing slash character. Some versions also include the drive specifier. SEE ALSO mkdir, chdir, errno -------------------------------------------------------------- listdir SYNOPSIS Get a list of the files in a directory USAGE String_Type[] listdir (String_Type dir) DESCRIPTION The `listdir' function returns the directory listing of all the files in the specified directory `dir' as an array of strings. It does not return the special files `".."' and `"."' as part of the list. SEE ALSO stat_file, stat_is, length -------------------------------------------------------------- lstat_file SYNOPSIS Get information about a symbolic link USAGE Struct_Type lstat_file (String_Type file) DESCRIPTION The `lstat_file' function behaves identically to `stat_file' but if `file' is a symbolic link, `lstat_file' returns information about the link itself, and not the file that it references. See the documentation for `stat_file' for more information. NOTES On systems that do not support symbolic links, there is no difference between this function and the `stat_file' function. SEE ALSO stat_file, readlink -------------------------------------------------------------- mkdir SYNOPSIS Create a new directory USAGE Integer_Type mkdir (String_Type dir, Integer_Type mode) DESCRIPTION The `mkdir' function creates a directory whose name is specified by the `dir' parameter with permissions specified by `mode'. Upon success `mkdir' returns zero, or it returns `-1' and sets `errno' accordingly. In particular, if the directory already exists, the function will fail and set errno to `EEXIST'. EXAMPLE define my_mkdir (dir) { if (0 == mkdir (dir, 0777)) return; if (errno == EEXIST) return; verror ("mkdir %s failed: %s", dir, errno_string (errno)); } NOTES The `mode' parameter may not be meaningful on all systems. On systems where it is meaningful, the actual permissions on the newly created directory are modified by the process's umask. SEE ALSO rmdir, getcwd, chdir, fopen, errno -------------------------------------------------------------- readlink SYNOPSIS String_Type readlink (String_Type path) USAGE Get the value of a symbolic link DESCRIPTION The `readlink' function returns the value of a symbolic link and returns it as a string. Upon failure, NULL is returned and `errno' set accordingly. NOTES Not all systems support this function. SEE ALSO lstat_file, stat_file, stat_is -------------------------------------------------------------- remove SYNOPSIS Delete a file USAGE Integer_Type remove (String_Type file) DESCRIPTION The `remove' function deletes a file. It returns 0 upon success, or -1 upon error and sets `errno' accordingly. SEE ALSO rename, rmdir -------------------------------------------------------------- rename SYNOPSIS Rename a file USAGE Integer_Type rename (String_Type old, String_Type new) DESCRIPTION The `rename' function renames a file from `old' to `new' moving it between directories if necessary. This function may fail if the directories do not refer to the same file system. It returns 0 upon success, or -1 upon error and sets `errno' accordingly. SEE ALSO remove, errno -------------------------------------------------------------- rmdir SYNOPSIS Remove a directory USAGE Integer_Type rmdir (String_Type dir) DESCRIPTION The `rmdir' function deletes a specified directory. It returns 0 upon success or -1 upon error and sets `errno' accordingly. NOTES The directory must be empty before it can be removed. SEE ALSO rename, remove, mkdir -------------------------------------------------------------- stat_file SYNOPSIS Get information about a file USAGE Struct_Type stat_file (String_Type file) DESCRIPTION The `stat_file' function returns information about `file' through the use of the system `stat' call. If the stat call fails, the function returns `NULL' and sets errno accordingly. If it is successful, it returns a stat structure with the following integer fields: st_dev st_ino st_mode st_nlink st_uid st_gid st_rdev st_size st_atime st_mtime st_ctime See the man page for `stat' for a discussion of these fields. EXAMPLE The following example shows how the `stat_file' function may be used to get the size of a file: define file_size (file) { variable st; st = stat_file(file); if (st == NULL) verror ("Unable to stat %s", file); return st.st_size; } SEE ALSO lstat_file, stat_is -------------------------------------------------------------- stat_is SYNOPSIS Parse the var{st_mode USAGE Char_Type stat_is (String_Type type, Integer_Type st_mode) DESCRIPTION The `stat_is' function returns a signed character value about the type of file specified by `st_mode'. Specifically, `type' must be one of the strings: "sock" (socket) "fifo" (fifo) "blk" (block device) "chr" (character device) "reg" (regular file) "lnk" (link) "dir" (dir) It returns a non-zero value if `st_mode' corresponds to `type'. EXAMPLE The following example illustrates how to use the `stat_is' function to determine whether or not a file is a directory: define is_directory (file) { variable st; st = stat_file (file); if (st == NULL) return 0; return stat_is ("dir", st.st_mode); } SEE ALSO stat_file, lstat_file -------------------------------------------------------------- autoload SYNOPSIS Load a function from a file USAGE autoload (String_Type funct, String_Type file) DESCRIPTION The `autoload' function is used to declare `funct' to the interpreter and indicate that it should be loaded from `file' when it is actually used. EXAMPLE Suppose `bessel_j0' is a function defined in the file `bessel.sl'. Then the statement autoload ("bessel_j0", "bessel.sl"); will cause `bessel.sl' to be loaded prior to the execution of `bessel_j0' SEE ALSO evalfile -------------------------------------------------------------- byte_compile_file SYNOPSIS Compile a file to byte-code for faster loading. USAGE byte_compile_file (String_Type file, Integer_Type method) DESCRIPTION The `byte_compile_file' function byte-compiles `file' producing a new file with the same name except a `'c'' is added to the output file name. For example, `file' is `"site.sl"', then the function produces a new file named `site.slc'. NOTES The `method' parameter is not used in the current implementation. Its use is reserved for the future. For now, set it to `0'. SEE ALSO evalfile -------------------------------------------------------------- eval SYNOPSIS Interpret a string as slang code USAGE eval (String_Type expression) DESCRIPTION The `eval' function parses a string as S-Lang code and executes the result. This is a useful function in many contexts such as dynamically generating function definitions where there is no way to generate them otherwise. EXAMPLE if (0 == is_defined ("my_function")) eval ("define my_function () { message (\"my_function\"); }"); SEE ALSO is_defined, autoload, evalfile -------------------------------------------------------------- evalfile SYNOPSIS Interpret a file containing slang code. USAGE Integer_Type evalfile (String_Type file) DESCRIPTION The `evalfile' function loads `file' into the interpreter. If no errors were encountered, `1' will be returned; otherwise, a S-Lang error will be generated and the function will return zero. EXAMPLE define load_file (file) { ERROR_BLOCK { _clear_error (); } () = evalfile (file); } SEE ALSO eval, autoload -------------------------------------------------------------- get_import_module_path SYNOPSIS Get the search path for dynamically loadable objects USAGE String_Type get_import_module_path () DESCRIPTION The `get_import_module_path' may be used to get the search path for dynamically shared objects. Such objects may be made accessable to the application via the `import' function. SEE ALSO import, set_import_module_path -------------------------------------------------------------- import SYNOPSIS Dynamically link to a specified module USAGE import (String_Type module [, String_Type namespace]) DESCRIPTION The `import' function causes the run-time linker to dynamically link to the shared object specified by the `module' parameter. It seaches for the shared object as follows: First a search is performed along all module paths specified by the application. Then a search is made along the paths defined via the `set_import_module_path' function. If not found, a search is performed along the paths given by the `SLANG_MODULE_PATH' environment variable. Finally, a system dependent search is performed (e.g., using the `LD_LIBRARY_PATH' environment variable). The optional second parameter may be used to specify a namespace for the intrinsic functions and variables of the module. If this parameter is not present, the intrinsic objects will be placed into the global namespace. This function signals an error if the specified module is not found. NOTES The `import' function is not available on all systems. SEE ALSO set_import_module_path, use_namespace, current_namespace, getenv, evalfile -------------------------------------------------------------- set_import_module_path SYNOPSIS Set the search path for dynamically loadable objects USAGE set_import_module_path (String_Type path_list) DESCRIPTION The `set_import_module_path' may be used to set the search path for dynamically shared objects. Such objects may be made accessable to the application via the `import' function. The actual syntax for the specification of the set of paths will vary according to the operating system. Under Unix, a colon character is used to separate paths in `path_list'. For win32 systems a semi-colon is used. SEE ALSO import, get_import_module_path -------------------------------------------------------------- _NARGS SYNOPSIS The number of parameters passed to a function USAGE Integer_Type _NARGS EXAMPLE This example uses the `_NARGS' variable to print the list of values passed to the function: define print_values () { variable arg; if (_NARGS == 0) { message ("Nothing to print"); return; } foreach (__pop_args (_NARGS)) { arg = (); vmessage ("Argument value is: %S", arg.value); } } SEE ALSO __pop_args, __push_args, typeof -------------------------------------------------------------- __get_defined_symbols SYNOPSIS Get the symbols defined by the preprocessor USAGE Integer_Type __get_defined_symbols () DESCRIPTION The `__get_defined_symbols' functions is used to get the list of all the symbols defined by the S-Lang preprocessor. It pushes each of the symbols on the stack followed by the number of items pushed. SEE ALSO is_defined, _apropos -------------------------------------------------------------- __is_initialized SYNOPSIS Determine whether or not a variable has a value USAGE Integer_Type __is_initialized (Ref_Type r) DESCRIPTION This function returns non-zero of the object referenced by `r' is initialized, i.e., whether it has a value. It returns 0 if the referenced object has not been initialized. EXAMPLE For example, the function: define zero () { variable f; return __is_initialized (&f); } will always return zero, but define one () { variable f = 0; return __is_initialized (&f); } will return one. NOTES It is easy to see why a reference to the variable must be passed to `__is_initialized' and not the variable itself; otherwise, the value of the variable would be passed and the variable may have no value if it was not initialized. SEE ALSO __get_reference, __uninitialize, is_defined, typeof, eval -------------------------------------------------------------- _apropos SYNOPSIS Generate a list of functions and variables USAGE Array_Type _apropos (String_Type ns, String_Type s, Integer_Type flags) DESCRIPTION The `_apropos' function may be used to get a list of all defined objects in the namespace `ns' whose name matches the regular expression `s' and whose type matches those specified by `flags'. It returns an array of strings representing the matches. The second parameter `flags' is a bit mapped value whose bits are defined according to the following table 1 Intrinsic Function 2 User-defined Function 4 Intrinsic Variable 8 User-defined Variable EXAMPLE define apropos (s) { variable n, name, a; a = _apropos ("Global", s, 0xF); vmessage ("Found %d matches:", length (a)); foreach (a) { name = (); message (name); } } prints a list of all matches. NOTES If the namespace specifier `ns' is the empty string `""', then the namespace will default to the static namespace of the current compilation unit. SEE ALSO is_defined, sprintf -------------------------------------------------------------- _function_name SYNOPSIS Returns the name of the currently executing function USAGE String_Type _function_name (); DESCRIPTION This function returns the name of the currently executing function. If called from top-level, it returns the empty string. SEE ALSO _trace_function, is_defined -------------------------------------------------------------- _slang_doc_dir SYNOPSIS Installed documentation directory USAGE String_Type _slang_doc_dir; DESCRIPTION The `_slang_doc_dir' variable is a read-only whose value specifies the installation location of the S-Lang documentation. SEE ALSO get_doc_string_from_file -------------------------------------------------------------- _slang_version SYNOPSIS The S-Lang library version number USAGE Integer_Type _slang_version DESCRIPTION The `_slang_version' variable is read-only and and whose value represents the number of the S-Lang library. SEE ALSO _slang_version_string -------------------------------------------------------------- _slang_version_string SYNOPSIS The S-Lang library version number as a string USAGE String_Type _slang_version_string DESCRIPTION The `_slang_version_string' variable is read-only and whose value represents the version number of the S-Lang library. SEE ALSO _slang_version -------------------------------------------------------------- get_doc_string_from_file SYNOPSIS Read documentation from a file USAGE String_Type get_doc_string_from_file (String_Type f, String_Type t) DESCRIPTION `get_doc_string_from_file' opens the documentation file `f' and searches it for topic `t'. It returns the documentation for `t' upon success, otherwise it returns `NULL' upon error. It will fail if `f' could not be opened or does not contain documentation for the topic. SEE ALSO stat_file SEE ALSO _slang_doc_dir -------------------------------------------------------------- is_defined SYNOPSIS Indicate whether a variable or function defined. USAGE Integer_Type is_defined (String_Type obj) DESCRIPTION This function is used to determine whether or not a function or variable whose name is `obj' has been defined. If `obj' is not defined, the function returns 0. Otherwise, it returns a non-zero value that defpends on the type of object `obj' represents. Specifically, it returns one of the following values: +1 if an intrinsic function +2 if user defined function -1 if intrinsic variable -2 if user defined variable 0 if undefined EXAMPLE For example, consider the function: define runhooks (hook) { if (2 == is_defined(hook)) eval(hook); } This function could be called from another S-Lang function to allow customization of that function, e.g., if the function represents a mode, the hook could be called to setup keybindings for the mode. SEE ALSO typeof, eval, autoload, __get_reference, __is_initialized -------------------------------------------------------------- Conj SYNOPSIS Compute the complex conjugate of a number USAGE z1 = Conj (z) DESCRIPTION The `Conj' function returns the complex conjugate of a number. If its argument is an array, the `Conj' function will be applied to each element and the result returned as an array. SEE ALSO Real, Imag, abs -------------------------------------------------------------- Imag SYNOPSIS Compute the imaginary part of a number USAGE i = Imag (z) DESCRIPTION The `Imag' function returns the imaginary part of a number. If its argument is an array, the `Imag' function will be applied to each element and the result returned as an array. SEE ALSO Real, Conj, abs -------------------------------------------------------------- Real SYNOPSIS Compute the real part of a number USAGE r = Real (z) DESCRIPTION The `Real' function returns the real part of a number. If its argument is an array, the `Real' function will be applied to each element and the result returned as an array. SEE ALSO Imag, Conj, abs -------------------------------------------------------------- abs SYNOPSIS Compute the absolute value of a number USAGE y = abs(x) DESCRIPTION The `abs' function returns the absolute value of an arithmetic type. If its argument is a complex number (`Complex_Type'), then it returns the modulus. If the argument is an array, a new array will be created whose elements are obtained from the original array by using the `abs' function. SEE ALSO sign, sqr -------------------------------------------------------------- acos SYNOPSIS Compute the arc-cosine of an number USAGE y = acos (x) DESCRIPTION The `acos' function computes the arc-cosine of a number and returns the result as an array. If its argument is an array, the `acos' function will be applied to each element and the result returned as an array. SEE ALSO cos, atan, acosh, cosh -------------------------------------------------------------- acosh SYNOPSIS Compute the inverse cosh of an number USAGE y = acosh (x) DESCRIPTION The `acosh' function computes the inverse cosh of a number and returns the result as an array. If its argument is an array, the `acosh' function will be applied to each element and the result returned as an array. SEE ALSO cos, atan, acosh, cosh -------------------------------------------------------------- asin SYNOPSIS Compute the arc-sine of an number USAGE y = asin (x) DESCRIPTION The `asin' function computes the arc-sine of a number and returns the result as an array. If its argument is an array, the `asin' function will be applied to each element and the result returned as an array. SEE ALSO cos, atan, acosh, cosh -------------------------------------------------------------- asinh SYNOPSIS Compute the inverse-sinh of an number USAGE y = asinh (x) DESCRIPTION The `asinh' function computes the inverse-sinh of a number and returns the result as an array. If its argument is an array, the `asinh' function will be applied to each element and the result returned as an array. SEE ALSO cos, atan, acosh, cosh -------------------------------------------------------------- atan SYNOPSIS Compute the arc-tangent of an number USAGE y = atan (x) DESCRIPTION The `atan' function computes the arc-tangent of a number and returns the result as an array. If its argument is an array, the `atan' function will be applied to each element and the result returned as an array. SEE ALSO cos, atan, acosh, cosh -------------------------------------------------------------- atanh SYNOPSIS Compute the inverse-tanh of an number USAGE y = atanh (x) DESCRIPTION The `atanh' function computes the inverse-tanh of a number and returns the result as an array. If its argument is an array, the `atanh' function will be applied to each element and the result returned as an array. SEE ALSO cos, atan, acosh, cosh -------------------------------------------------------------- cos SYNOPSIS Compute the cosine of an number USAGE y = cos (x) DESCRIPTION The `cos' function computes the cosine of a number and returns the result as an array. If its argument is an array, the `cos' function will be applied to each element and the result returned as an array. SEE ALSO cos, atan, acosh, cosh -------------------------------------------------------------- cosh SYNOPSIS Compute the hyperbolic cosine of an number USAGE y = cosh (x) DESCRIPTION The `cosh' function computes the hyperbolic cosine of a number and returns the result as an array. If its argument is an array, the `cosh' function will be applied to each element and the result returned as an array. SEE ALSO cos, atan, acosh, cosh -------------------------------------------------------------- exp SYNOPSIS Compute the exponential of an number USAGE y = exp (x) DESCRIPTION The `exp' function computes the exponential of a number and returns the result as an array. If its argument is an array, the `exp' function will be applied to each element and the result returned as an array. SEE ALSO cos, atan, acosh, cosh -------------------------------------------------------------- log SYNOPSIS Compute the logarithm of an number USAGE y = log (x) DESCRIPTION The `log' function computes the logarithm of a number and returns the result as an array. If its argument is an array, the `log' function will be applied to each element and the result returned as an array. SEE ALSO cos, atan, acosh, cosh -------------------------------------------------------------- log10 SYNOPSIS Compute the base-10 logarithm of an number USAGE y = log10 (x) DESCRIPTION The `log10' function computes the base-10 logarithm of a number and returns the result as an array. If its argument is an array, the `log10' function will be applied to each element and the result returned as an array. SEE ALSO cos, atan, acosh, cosh -------------------------------------------------------------- mul2 SYNOPSIS Multiply a number by 2 USAGE y = mul2(x) DESCRIPTION The `mul2' function multiplies an arithmetic type by two and returns the result. If its argument is an array, a new array will be created whose elements are obtained from the original array by using the `mul2' function. SEE ALSO sqr, abs -------------------------------------------------------------- polynom SYNOPSIS Evaluate a polynomial USAGE Double_Type polynom(Double_Type a, b, ...c, Integer_Type n, Double_Type x) DESCRIPTION The `polynom' function returns the value of the polynomial expression: ax^n + bx^(n - 1) + ... c NOTES The `polynom' function should be extended to work with complex and array data types. The current implementation is limited to `Double_Type' quantities. SEE ALSO exp -------------------------------------------------------------- set_float_format SYNOPSIS Set the format for printing floating point values. USAGE set_float_format (String_Type fmt) DESCRIPTION The `set_float_format' function is used to set the floating point format to be used when floating point numbers are printed. The routines that use this are the traceback routines and the `string' function. The default value is `"%f"' EXAMPLE s = string (PI); % --> s = "3.14159" set_float_format ("%16.10f"); s = string (PI); % --> s = "3.1415926536" set_float_format ("%10.6e"); s = string (PI); % --> s = "3.141593e+00" SEE ALSO string, sprintf, double -------------------------------------------------------------- sign SYNOPSIS Compute the sign of a number USAGE y = sign(x) DESCRIPTION The `sign' function returns the sign of an arithmetic type. If its argument is a complex number (`Complex_Type'), it returns the sign of the imaginary part of the number. If the argument is an array, a new array will be created whose elements are obtained from the original array by using the `sign' function. When applied to a real number or an integer, the `sign' function returns -1, 0, or `+1' according to whether the number is less than zero, equal to zero, or greater than zero, respectively. SEE ALSO abs -------------------------------------------------------------- sin SYNOPSIS Compute the sine of an number USAGE y = sin (x) DESCRIPTION The `sin' function computes the sine of a number and returns the result as an array. If its argument is an array, the `sin' function will be applied to each element and the result returned as an array. SEE ALSO cos, atan, acosh, cosh -------------------------------------------------------------- sinh SYNOPSIS Compute the hyperbolic sine of an number USAGE y = sinh (x) DESCRIPTION The `sinh' function computes the hyperbolic sine of a number and returns the result as an array. If its argument is an array, the `sinh' function will be applied to each element and the result returned as an array. SEE ALSO cos, atan, acosh, cosh -------------------------------------------------------------- sqr SYNOPSIS Compute the square of a number USAGE y = sqr(x) DESCRIPTION The `sqr' function returns the square of an arithmetic type. If its argument is a complex number (`Complex_Type'), then it returns the square of the modulus. If the argument is an array, a new array will be created whose elements are obtained from the original array by using the `sqr' function. SEE ALSO abs, mul2 -------------------------------------------------------------- sqrt SYNOPSIS Compute the square root of an number USAGE y = sqrt (x) DESCRIPTION The `sqrt' function computes the square root of a number and returns the result as an array. If its argument is an array, the `sqrt' function will be applied to each element and the result returned as an array. SEE ALSO sqr, cos, atan, acosh, cosh -------------------------------------------------------------- tan SYNOPSIS Compute the tangent of an number USAGE y = tan (x) DESCRIPTION The `tan' function computes the tangent of a number and returns the result as an array. If its argument is an array, the `tan' function will be applied to each element and the result returned as an array. SEE ALSO cos, atan, acosh, cosh -------------------------------------------------------------- tanh SYNOPSIS Compute the hyperbolic tangent of an number USAGE y = tanh (x) DESCRIPTION The `tanh' function computes the hyperbolic tangent of a number and returns the result as an array. If its argument is an array, the `tanh' function will be applied to each element and the result returned as an array. SEE ALSO cos, atan, acosh, cosh -------------------------------------------------------------- error SYNOPSIS Generate an error condition USAGE error (String_Type msg DESCRIPTION The `error' function generates a S-Lang error condition causing the interpreter to start unwinding to top-level. It takes a single string parameter which is displayed on the stderr output device. The error condition may be cleared via an `ERROR_BLOCK' with the `_clear_error' function. Consult \user-manual for more information. EXAMPLE define add_txt_extension (file) { if (typeof (file) != String_Type) error ("add_extension: parameter must be a string"); file += ".txt"; return file; } SEE ALSO verror, _clear_error, message -------------------------------------------------------------- message SYNOPSIS Print a string onto the message device USAGE message (String_Type s DESCRIPTION The `message' function will print the string specified by `s' onto the message device. EXAMPLE define print_current_time () { message (time ()); } NOTES The message device will depend upon the application. For example, the output message device for the `jed' editor correspond to the line at the bottom of the display window. The default message device is the standard output device. SEE ALSO vmessage, sprintf, error -------------------------------------------------------------- usage SYNOPSIS Generate a usage error USAGE usage (String_Type msg) DESCRIPTION The `usage' function generates a usage exception and displays `msg' to the message device. EXAMPLE Suppose that some function `plot' plots an array of `x' and `y' values. The such a function could be written to issue a usage message if the wrong number of arguments were passed: define plot () { variable x, y; if (_NARGS != 2) usage ("plot (x, y)"); (x, y) = (); % Now do the hard part . . } SEE ALSO error, message -------------------------------------------------------------- verror SYNOPSIS Generate an error condition USAGE verror (String_Type fmt, ...) DESCRIPTION The `verror' function performs the same role as the `error' function. The only difference is that instead of a single string argument, `verror' takes a sprintf style argument list. EXAMPLE define open_file (file) { variable fp; fp = fopen (file, "r"); if (fp == NULL) verror ("Unable to open %s", file); return fp; } NOTES In the current implementation, strictly speaking, the `verror' function is not an intrinsic function. Rather it is a predefined S-Lang function using a combination of `Sprintf' and `error'. SEE ALSO error, Sprintf, vmessage -------------------------------------------------------------- vmessage SYNOPSIS Print a formatted string onto the message device USAGE vmessage (String_Type fmt, ...) DESCRIPTION The `vmessage' function formats a sprintf style argument list and displays the resulting string onto the message device. NOTES In the current implementation, strictly speaking, the `vmessage' function is not an intrinsic function. Rather it is a predefined S-Lang function using a combination of `Sprintf' and `message'. SEE ALSO message, Sprintf, verror -------------------------------------------------------------- __get_reference SYNOPSIS Get a reference to a global object USAGE Ref_Type __get_reference (String_Type nm) DESCRIPTION This function returns a reference to a global variable or function whose name is specified by `nm'. If no such object exists, it returns `NULL', otherwise it returns a reference. EXAMPLE For example, consider the function: define runhooks (hook) { variable f; f = __get_reference (hook); if (f != NULL) @f (); } This function could be called from another S-Lang function to allow customization of that function, e.g., if the function represents a mode, the hook could be called to setup keybindings for the mode. SEE ALSO is_defined, typeof, eval, autoload, __is_initialized, __uninitialize -------------------------------------------------------------- __uninitialize SYNOPSIS Uninitialize a variable USAGE __uninitialize (Ref_Type x) DESCRIPTION The `__uninitialize' function may be used to uninitialize the variable referenced by the parameter `x'. EXAMPLE The following two lines are equivalent: () = __tmp(z); __uninitialize (&z); SEE ALSO __tmp, __is_initialized -------------------------------------------------------------- _auto_declare SYNOPSIS Set automatic variable declaration mode USAGE Integer_Type _auto_declare DESCRIPTION The `_auto_declare' may be used to have all undefined variables implicitely declared as `static'. If set to zero, any variable must be declared witha `variable' declaration before it can be used. If set to one, then any undeclared variabled will be declared as a `static' global variable. The `_auto_declare' variable is is local to each compilation unit and setting its value in one unit has no effect upon its value in other units. The value of this variable has no effect upon the variables in a function. EXAMPLE The following code will not compile if `X' not been declared: X = 1; However, _auto_declare = 1; % declare variables as static. X = 1; is equivalent to static variable X = 1; NOTES This variable should be used sparingly and is intended primarily for interactive applications where one types S-Lang commands at a prompt. -------------------------------------------------------------- getenv SYNOPSIS Get the value of an environment variable USAGE String_Type getenv(String_Type var) DESCRIPTION The `getenv' function returns a string that represents the value of an environment variable `var'. It will return `NULL' if there is no environment variable whose name is given by `var'. EXAMPLE if (NULL != getenv ("USE_COLOR")) { set_color ("normal", "white", "blue"); set_color ("status", "black", "gray"); USE_ANSI_COLORS = 1; } SEE ALSO putenv, strlen, is_defined -------------------------------------------------------------- implements SYNOPSIS Name a private namespace USAGE implements (String_Type name); DESCRIPTION The `implements' function may be used to name the private namespace associated with the current compilation unit. Doing so will enable access to the members of the namespace from outside the unit. The name of the global namespace is `Global'. EXAMPLE Suppose that some file `t.sl' contains: implements ("Ts_Private"); static define message (x) { Global->vmessage ("Ts_Private message: %s", x); } message ("hello"); will produce `"Ts_Private message: hello"'. This `message' function may be accessed from outside via: Ts_Private->message ("hi"); NOTES Since `message' is an intrinsic function, it is global and may not be redefined in the global namespace. SEE ALSO use_namespace, current_namespace, import -------------------------------------------------------------- putenv SYNOPSIS Add or change an environment variable USAGE putenv (String_Type s) DESCRIPTION This functions adds string `s' to the environment. Typically, `s' should of the form `"name=value"'. The function signals a S-Lang error upon failure. NOTES This function is not available on all systems. SEE ALSO getenv, sprintf -------------------------------------------------------------- use_namespace SYNOPSIS Change to another namespace USAGE use_namespace (String_Type name) DESCRIPTION The `use_namespace' function changes the current namespace to the one specified by the parameter. If the specified namespace does not exist, an error will be generated. SEE ALSO implements, current_namespace, import -------------------------------------------------------------- current_namespace SYNOPSIS Get the name of the current namespace USAGE String_Type current_namespace () DESCRIPTION The `current_namespace' function returns the name of the current namespace. If the current namespace is anonymous, that is, has not been given a name via the `implements' function, the empty string `""' will be returned. SEE ALSO implements, use_namespace, import -------------------------------------------------------------- path_basename SYNOPSIS Get the basename part of a pathname USAGE String_Type path_basename (String_Type path) DESCRIPTION The `path_basename' function returns the basename associated with the `path' parameter. The basename is the non-directory part of the filename, e.g., on unix `c' is the basename of `/a/b/c'. SEE ALSO path_dirname, path_extname, path_concat, path_is_absolute -------------------------------------------------------------- path_concat SYNOPSIS Combine elements of a pathname USAGE String_Type path_concat (String_Type dir, String_Type basename) DESCRIPTION The `path_concat' function combines the arguments `dir' and `basename' to produce a pathname. For example, on unix is `dir' is `x/y' and `basename' is `z', then the function will return `x/y/z'. SEE ALSO path_dirname, path_basename, path_extname, path_is_absolute -------------------------------------------------------------- path_dirname SYNOPSIS Get the directory name part of a pathname USAGE String_Type path_dirname (String_Type path) DESCRIPTION The `path_dirname' function returns the directory name associated with a specified pathname. NOTES On systems that include a drive specifier as part of the pathname, the value returned by this function will include the driver specifier. SEE ALSO path_basename, path_extname, path_concat, path_is_absolute -------------------------------------------------------------- path_extname SYNOPSIS Return the extension part of a pathname USAGE String_Type path_extname (String_Type path) DESCRIPTION The `path_extname' function returns the extension portion of a specified pathname. If an extension is present, this function will also include the dot as part of the extension, i.e., if `path' is `file.c', then this function returns `".c"'. If no extension is present, the function returns an empty string `""'. NOTES Under VMS, the file version number is not returned as part of the extension. SEE ALSO path_sans_extname, path_dirname, path_basename, path_concat, path_is_absolute -------------------------------------------------------------- path_is_absolute SYNOPSIS Determine whether or not a pathname is absolute USAGE Int_Type path_is_absolute (String_Type path) DESCRIPTION The `path_is_absolute' function will return non-zero is `path' refers to an absolute pathname, otherwise it returns zero. SEE ALSO path_dirname, path_basename, path_extname, path_concat -------------------------------------------------------------- path_sans_extname SYNOPSIS Strip the extension from a pathname USAGE String_Type path_sans_extname (String_Type path) DESCRIPTION The `path_sans_extname' function removes the file name extension (including the dot) from the path and returns the result. SEE ALSO path_extname, path_basename, path_dirname, path_concat -------------------------------------------------------------- close SYNOPSIS Close an open file descriptor USAGE Int_Type close (FD_Type fd) DESCRIPTION The `close' function is used to open file descriptor of type `FD_Type'. Upon success 0 is returned, otherwise the function returns -1 and sets `errno' accordingly. SEE ALSO open, fclose, read, write -------------------------------------------------------------- dup_fd SYNOPSIS Duplicate a file descriptor USAGE FD_Type dup_fd (FD_Type fd) DESCRIPTION The `dup_fd' function duplicates and file descriptor and returns its duplicate. If the function fails, NULL will be returned and `errno' set accordingly. NOTES This function is essentually a wrapper around the POSIX `dup' function. SEE ALSO open, close -------------------------------------------------------------- fileno SYNOPSIS Convert a stdio File_Type object to a FD_Type descriptor USAGE FD_Type fileno (File_Type fp) DESCRIPTION The `fileno' function returns the `FD_Type' descriptor associated with the `File_Type' file pointer. Upon failure, NULL is returned. SEE ALSO fopen, open, fclose, close, dup_fd -------------------------------------------------------------- isatty SYNOPSIS Determine if an open file descriptor refers to a terminal USAGE Int_Type isatty (FD_Type or File_Type fd) DESCRIPTION This function returns 1 if the file descriptor `fd' refers to a terminal; otherwise it returns 0. The object `fd' may either be a `File_Type' stdio descriptor or an `FD_Type' object. SEE ALSO fopen, fclose, fileno -------------------------------------------------------------- lseek SYNOPSIS Reposition a file descriptor's file pointer USAGE Long_Type lseek (FD_Type fd, Long_Type ofs, int mode) SEEK_SET Set the offset to ofs SEEK_CUR Add ofs to the current offset SEEK_END Add ofs to the current file size NOTES Not all file descriptors are capable of supporting the seek operation, e.g., a descriptor associated with a pipe. By using `SEEK_END' with a positive value of the `ofs' parameter, it is possible to position the file pointer beyond the current size of the file. SEE ALSO fseek, ftell, open, close -------------------------------------------------------------- open SYNOPSIS Open a file USAGE FD_Type open (String_Type filename, Int_Type flags [,Int_Type mode]) DESCRIPTION The `open' function attempts to open a file specified by the `filename' parameter according to the `flags' parameter, which must be one of the following values: O_RDONLY (read-only) O_WRONLY (write-only) O_RDWR (read/write) In addition, `flags' may also be bitwise-or'd with any of the following: O_BINARY (open the file in binary mode) O_TEXT (open the file in text mode) O_CREAT (create file if it does not exists) O_EXCL (fail if the file already exists) O_NOCTTY (do not make the device the controlling terminal) O_TRUNC (truncate the file if it exists) O_APPEND (open the file in append mode) O_NONBLOCK (open the file in non-blocking mode) If `O_CREAT' is used for the `flags' parameterm then the `mode' parameter must be present. `mode' specifies the permissions to use if a new file is created. The actual file permissions will be affected by the process's `umask' via `mode&~umask'. The `mode' parameter's value is constructed via bitwise-or of the following values: S_IRWXU (Owner has read/write/execute permission) S_IRUSR (Owner has read permission) S_IWUSR (Owner has write permission) S_IXUSR (Owner has execute permission) S_IRWXG (Group has read/write/execute permission) S_IRGRP (Group has read permission) S_IWGRP (Group has write permission) S_IXGRP (Group has execute permission) S_IRWXO (Others have read/write/execute permission) S_IROTH (Others have read permission) S_IWOTH (Others have write permission) S_IXOTH (Others have execute permission) Upon success `open' returns a file descriptor object (`FD_Type'), otherwise `NULL' is returned and `errno' is set. NOTES If you are not familiar with the `open' system call, then it is recommended that you use `fopen' instead. SEE ALSO fopen, close, read, write, stat_file -------------------------------------------------------------- read SYNOPSIS Read from an open file descriptor USAGE UInt_Type read (FD_Type fd, Ref_Type buf, UInt_Type num) DESCRIPTION The `read' function attempts to read at most `num' bytes into the variable indicated by `buf' from the open file descriptor `fd'. It returns the number of bytes read, or -1 and sets `errno' upon failure. The number of bytes read may be less than `num', and will be zero if an attempt is made to read past the end of the file. NOTES `read' is a low-level function and may return -1 for a variety of reasons. For example, if non-blocking I/O has been specified for the open file descriptor and no data is available for reading then the function will return -1 and set `errno' to `EAGAIN'. SEE ALSO fread, open, close, write -------------------------------------------------------------- write SYNOPSIS Write to an open file descriptor USAGE UInt_Type write (FD_Type fd, BString_Type buf) DESCRIPTION The `write' function attempts to write the bytes specified by the `buf' parameter to the open file descriptor `fd'. It returns the number of bytes successfully written, or -1 and sets `errno' upon failure. The number of bytes written may be less than `length(buf)'. SEE ALSO read, fwrite, open, close -------------------------------------------------------------- errno SYNOPSIS Error code set by system functions. USAGE Integer_Type errno DESCRIPTION A system function can fail for a variety of reasons. For example, a file operation may fail because lack of disk space, or the process does not have permission to perform the operation. Such functions will return `-1' and set the variable `errno' to an error code describing the reason for failure. Particular values of `errno' may be specified by the following symbolic constants (read-only variables) and the corresponding `errno_string' value: EPERM "Not owner" ENOENT "No such file or directory" ESRCH "No such process" ENXIO "No such device or address" ENOEXEC "Exec format error" EBADF "Bad file number" ECHILD "No children" ENOMEM "Not enough core" EACCES "Permission denied" EFAULT "Bad address" ENOTBLK "Block device required" EBUSY "Mount device busy" EEXIST "File exists" EXDEV "Cross-device link" ENODEV "No such device" ENOTDIR "Not a directory" EISDIR "Is a directory" EINVAL "Invalid argument" ENFILE "File table overflow" EMFILE "Too many open files" ENOTTY "Not a typewriter" ETXTBSY "Text file busy" EFBIG "File too large" ENOSPC "No space left on device" ESPIPE "Illegal seek" EROFS "Read-only file system" EMLINK "Too many links" EPIPE "Broken pipe" ELOOP "Too many levels of symbolic links" ENAMETOOLONG "File name too long" EXAMPLE The `mkdir' function will attempt to create a directory. If that directory already exists, the function will fail and set `errno' to `EEXIST'. define create_dir (dir) { if (0 == mkdir (dir)) return; if (errno != EEXIST) error ("mkdir %s failied: %s", dir, errno_string); } SEE ALSO errno_string, error, mkdir -------------------------------------------------------------- errno_string SYNOPSIS Return a string describing an errno. USAGE String_Type errno_string (Integer_Type err) DESCRIPTION The `errno_string' function returns a string describing the integer error code `err'. The variable `err' usually corresponds to the `errno' intrinsic function. See the description for `errno' for more information. EXAMPLE The `errno_string' function may be used as follows: define sizeof_file (file) { variable st = stat (file); if (st == NULL) verror ("%s: %s", file, errno_string (errno); return st.st_size; } SEE ALSO errno, stat, verror -------------------------------------------------------------- getegid SYNOPSIS Get the effective group id USAGE Int_Type getegid () DESCRIPTION The `getegid' function returns the effective group ID of the current process. NOTES This function is not supported by all systems. SEE ALSO getgid, geteuid, setgid -------------------------------------------------------------- geteuid SYNOPSIS Get the effective user-id of the current process USAGE Int_Type geteuid () DESCRIPTION The `geteuid' function returns the effective user-id of the current process. NOTES This function is not supported by all systems. SEE ALSO getuid, setuid, setgid -------------------------------------------------------------- getgid SYNOPSIS Get the group id USAGE Integer_Type getgid () DESCRIPTION The `getgid' function returns the real group id of the current process. NOTES This function is not supported by all systems. SEE ALSO getpid, getppid -------------------------------------------------------------- getpid SYNOPSIS Get the current process id USAGE Integer_Type getpid () DESCRIPTION The `getpid' function returns the current process identification number. SEE ALSO getppid, getgid -------------------------------------------------------------- getppid SYNOPSIS Get the parent process id USAGE Integer_Type getppid () DESCRIPTION The `getpid' function returns the process identification number of the parent process. NOTES This function is not supported by all systems. SEE ALSO getpid, getgid -------------------------------------------------------------- getuid SYNOPSIS Get the user-id of the current process USAGE Int_Type getuid () DESCRIPTION The `getuid' function returns the user-id of the current process. NOTES This function is not supported by all systems. SEE ALSO getuid, getegid -------------------------------------------------------------- kill SYNOPSIS Send a signal to a process USAGE Integer_Type kill (Integer_Type pid, Integer_Type sig) DESCRIPTION This function may be used to send a signal given by the integer `sig' to the process specified by `pid'. The function returns zero upon sucess and `-1' upon failure setting errno accordingly. EXAMPLE The `kill' function may be used to determine whether or not a specific process exists: define process_exists (pid) { if (-1 == kill (pid, 0)) return 0; % Process does not exist return 1; } NOTES This function is not supported by all systems. SEE ALSO getpid -------------------------------------------------------------- mkfifo SYNOPSIS Create a named pipe USAGE Int_Type mkfifo (String_Type name, Int_Type mode) DESCRIPTION The `mkfifo' attempts to create a named pipe with the specified name and mode (modified by the process's umask). The function returns 0 upon success, or -1 and sets `errno' upon failure. NOTES Not all systems support the `mkfifo' function and even on systems that do implement the `mkfifo' system call, the underlying file system may not support the concept of a named pipe, e.g, an NFS filesystem. SEE ALSO stat_file -------------------------------------------------------------- setgid SYNOPSIS Set the group-id of the current process USAGE Int_Type setgid (Int_Type gid) DESCRIPTION The `setgid' function sets the effective group-id of the current process. It returns zero upon success, or -1 upon error and sets `errno' appropriately. NOTES This function is not supported by all systems. SEE ALSO getgid, setuid -------------------------------------------------------------- setpgid SYNOPSIS Set the process group-id USAGE Int_Type setpgid (Int_Type pid, Int_Type gid) DESCRIPTION The `setpgid' function sets the group-id `gid' of the process whose process-id is `pid'. If `pid' is 0, then the current process-id will be used. If `pgid' is 0, then the pid of the affected process will be used. If successful zero will be returned, otherwise the function will return -1 and set `errno' accordingly. NOTES This function is not supported by all systems. SEE ALSO setgid, setuid -------------------------------------------------------------- setuid SYNOPSIS Set the user-id of the current process USAGE Int_Type setuid (Int_Type id) DESCRIPTION The `setuid' function sets the effective user-id of the current process. It returns zero upon success, or -1 upon error and sets `errno' appropriately. NOTES This function is not supported by all systems. SEE ALSO setgid, setpgid, getuid, geteuid -------------------------------------------------------------- sleep SYNOPSIS Pause for a specified number of seconds USAGE sleep (Double_Type n) DESCRIPTION The `sleep' function delays the current process for the specified number of seconds. If it is interrupted by a signal, it will return prematurely. NOTES Not all system support sleeping for a fractional part of a second. -------------------------------------------------------------- system SYNOPSIS Execute a shell command USAGE Integer_Type system (String_Type cmd) DESCRIPTION The `system' function may be used to execute the string expression `cmd' in an inferior shell. This function is an interface to the C `system' function which returns an implementation-defined result. On Linux, it returns 127 if the inferior shell could not be invoked, -1 if there was some other error, otherwise it returns the return code for `cmd'. EXAMPLE define dir () { () = system ("DIR"); } displays a directory listing of the current directory under MSDOS or VMS. SEE ALSO popen, listdir -------------------------------------------------------------- umask SYNOPSIS Set the file creation mask USAGE Int_Type umask (Int_Type m) DESCRIPTION The `umask' function sets the file creation mask to `m' and returns the previous mask. SEE ALSO stat_file -------------------------------------------------------------- uname SYNOPSIS Get the system name USAGE Struct_Tye uname () DESCRIPTION The `uname' function returns a structure containing information about the operating system. The structure contains the following fields: sysname (Name of the operating system) nodename (Name of the node within the network) release (Release level of the OS) version (Current version of the release) machine (Name of the hardware) NOTES Not all systems support this function. SEE ALSO getenv, pack, unpack -------------------------------------------------------------- __pop_args SYNOPSIS Remove n function arguments from the stack USAGE variable args = __pop_args(Integer_Type n); DESCRIPTION This function together with the companion function `__push_args' is useful for passing the arguments of a function to another function. `__pop_args' returns an array of `n' structures with a single structure field called `value', which represents the value of the argument. EXAMPLE Consider the following `print' function. It prints all its arguments to `stdout' separated by spaces: define print () { variable i; variable args = __pop_args (_NARGS); for (i = 0; i < _NARGS; i++) { () = fputs (string (args[i].value), stdout); () = fputs (" ", stdout); } () = fputs ("\n", stdout); () = fflush (stdout); } Now consider the problem of defining a function called `ones' that returns a multi-dimensional array with all the elements set to 1. For example, `ones(10)' should return a 1-d array of ones, whereas `ones(10,20)' should return a 10x20 array. define ones () { !if (_NARGS) return 1; variable a; a = __pop_args (_NARGS); return @Array_Type (Integer_Type, [__push_args (a)]) + 1; } Here, `__push_args' was used to push on the arguments passed to the `ones' function onto the stack to be used when dereferencing `Array_Type'. SEE ALSO __push_args, typeof, _pop_n -------------------------------------------------------------- __push_args SYNOPSIS Remove n function arguments onto the stack USAGE __push_args (Struct_Type args); DESCRIPTION This function together with the companion function `__pop_args' is useful for passing the arguments of one function to another. See the desription of `__pop_args' for more information. SEE ALSO __pop_args, typeof, _pop_n -------------------------------------------------------------- _pop_n SYNOPSIS Remove objects from the stack USAGE _pop_n (Integer_Type n); DESCRIPTION The `_pop_n' function pops `n' objects from the top of the stack. EXAMPLE define add3 () { variable x, y, z; if (_NARGS != 3) { _pop_n (_NARGS); error ("add3: Expecting 3 arguments"); } (x, y, z) = (); return x + y + z; } SEE ALSO _stkdepth, pop -------------------------------------------------------------- _print_stack SYNOPSIS print the values on the stack. USAGE _print_stack () DESCRIPTION This function dumps out what is currently on the S-Lang. It does not alter the stack and it is usually used for debugging purposes. SEE ALSO _stkdepth, string -------------------------------------------------------------- _stk_reverse SYNOPSIS Reverse the order of the objects on the stack. USAGE _stk_reverse (Integer_Type n) DESCRIPTION The `_stk_reverse' function reverses the order of the top `n' items on the stack. SEE ALSO _stkdepth, _stk_roll -------------------------------------------------------------- _stk_roll SYNOPSIS Roll items on the stack USAGE _stk_roll (Integer_Type n); DESCRIPTION This function may be used to alter the arrangement of objects on the stack. Specifically, if the integer `n' is positive, the top `n' items on the stack are rotated up. If `n' is negative, the top `abs(n)' items on the stack are rotated down. EXAMPLE If the stack looks like: item-0 item-1 item-2 item-3 where `item-0' is at the top of the stack, then `_stk_roll(-3)' will change the stack to: item-2 item-0 item-1 item-3 NOTES This function only has an effect for `abs(n) > 1'. SEE ALSO _stkdepth, _stk_reverse, _pop_n, _print_stack -------------------------------------------------------------- _stkdepth USAGE Get the number of objects currently on the stack. SYNOPSIS Integer_Type _stkdepth () DESCRIPTION The `_stkdepth' function returns number of items on stack prior to the call of `_stkdepth'. SEE ALSO _print_stack, _stk_reverse, _stk_roll -------------------------------------------------------------- dup SYNOPSIS Duplicate the value at the top of the stack USAGE dup () DESCRIPTION This function returns an exact duplicate of the object on top of the stack. For some objects such as arrays or structures, it creates a new reference to the array. However, for simple scalar S-Lang types such as strings, integers, and doubles, it creates a new copy of the object. SEE ALSO pop, typeof -------------------------------------------------------------- exch SYNOPSIS Exchange two items on the stack USAGE exch () DESCRIPTION The `exch' swaps the two top items on the stack. SEE ALSO pop, _stk_reverse, _stk_roll -------------------------------------------------------------- pop SYNOPSIS Discard an item from the stack USAGE pop () DESCRIPTION The `pop' function removes the top item from the stack. SEE ALSO _pop_n -------------------------------------------------------------- clearerr SYNOPSIS Clear the error of a file stream USAGE clearerr (File_Type fp DESCRIPTION The `clearerr' function clears the error and end-of-file flags associated with the open file stream `fp'. SEE ALSO ferror, feof, fopen -------------------------------------------------------------- fclose SYNOPSIS Close a file USAGE Integer_Type fclose (File_Type fp) DESCRIPTION The `fclose' function may be used to close an open file pointer `fp'. Upon success it returns zero, and upon failure it sets `errno' and returns `-1'. Failure usually indicates a that the file system is full or that `fp' does not refer to an open file. NOTES Many C programmers call `fclose' without checking the return value. The S-Lang language requires the programmer to explicitly handle any value returned by a S-Lang function. The simplest way to handle the return value from `fclose' is to use it as: () = fclose (fp); SEE ALSO fopen, fgets, fflush, pclose, errno -------------------------------------------------------------- fdopen SYNOPSIS Convert a FD_Type file descriptor to a stdio File_Type object USAGE File_Type fdopen (FD_Type, String_Type mode) DESCRIPTION The `fdopen' function creates and returns a stdio `File_Type' object from the open `FD_Type' descriptor `fd'. The `mode' parameter corresponds to the `mode' parameter of the `fopen' function and must be consistent with the mode of the descriptor `fd'. The function returns NULL upon failure and sets `errno'. NOTES The `fclose' function does not close the `File_Type' object returned from this function. The underlying file object must be closed by the `close' function. SEE ALSO fileno, fopen, open, close, fclose -------------------------------------------------------------- feof SYNOPSIS Get the end-of-file status USAGE Integer_Type feof (File_Type fp) DESCRIPTION This function may be used to determine the state of the end-of-file indicator of the open file descriptor `fp'. It returns `0' if the indicator is not set, or non-zero if it is. The end-of-file indicator may be cleared by the `clearerr' function. SEE ALSO ferror, clearerr, fopen -------------------------------------------------------------- ferror SYNOPSIS Determine the error status of an open file descriptor USAGE Integer_Type ferror (File_Type fp) DESCRIPTION This function may be used to determine the state of the error indicator of the open file descriptor `fp'. It returns `0' if the indicator is not set, or non-zero if it is. The error indicator may be cleared by the `clearerr' function. SEE ALSO feof, clearerr, fopen -------------------------------------------------------------- fflush SYNOPSIS Flush an output stream USAGE Integer_Type fflush (File_Type fp) DESCRIPTION The `fflush' function may be used to update the _output_ stream specified by `fp'. It returns `0' upon success, or `-1' upon failure and sets `errno' accordingly. In particular, this function will fail if `fp' does not represent an output stream, or if `fp' is associated with a disk file and there is insufficient disk space. EXAMPLE This example illustrates how to use the `fflush' function without regard to the return value: () = fputs ("Enter value> ", stdout); () = fflush (stdout); NOTES Many C programmers disregard the return value from the `fflush' function. The above example illustrates how to properly do this in the S-Lang langauge. SEE ALSO fopen, fclose -------------------------------------------------------------- fgets SYNOPSIS Read a line from a file. USAGE Integer_Type fgets (SLang_Ref_Type ref, File_Type fp) DESCRIPTION `fgets' reads a line from the open file specified by `fp' and places the characters in the variable whose reference is specified by `ref'. It returns `-1' if `fp' is not associated with an open file or an attempt was made to read at the end the file; otherwise, it returns the number of characters read. EXAMPLE The following example returns the lines of a file via a linked list: define read_file (file) { variable buf, fp, root, tail; variable list_type = struct { text, next }; root = NULL; fp = fopen(file, "r"); if (fp == NULL) error("fopen %s failed." file); while (-1 != fgets (&buf, fp)) { if (root == NULL) { root = @list_type; tail = root; } else { tail.next = @list_type; tail = tail.next; } tail.text = buf; tail.next = NULL; } () = fclose (fp); return root; } SEE ALSO fopen, fclose, fputs, fread, error -------------------------------------------------------------- fgetslines SYNOPSIS Read all the lines from an open file USAGE String_Type[] fgetslines (File_Type fp) DESCRIPTION The `fgetslines' function returns all the remaining lines as an array of strings in the file specified by the open file pointer `fp'. If the file is empty, an empty string array will be returned. The function returns `NULL' upon error. EXAMPLE The following function returns the number of lines in a file: define count_lines_in_file (file) { variable fp, lines; fp = fopen (file, "r"); if (fp == NULL) return -1; lines = fgetslines (fp); if (lines == NULL) return -1; return length (lines); } Note that the file was implicitly closed by the function. NOTES This function should not be used if the file contains many lines since that would require that all the lines be read into memory. SEE ALSO fgets, fread, fopen -------------------------------------------------------------- fopen SYNOPSIS Open a file USAGE File_Type fopen (String_Type f, String_Type m) DESCRIPTION The `fopen' function opens a file `f' according to the mode string `m'. Allowed values for `m' are: "r" Read only "w" Write only "a" Append "r+" Reading and writing at the beginning of the file. "w+" Reading and writing. The file is created if it does not exist; otherwise, it is truncated. "a+" Reading and writing at the end of the file. The file is created if it does not already exist. In addition, the mode string can also include the letter `'b'' as the last character to indicate that the file is to be opened in binary mode. Upon success, `fopen' a `File_Type' object which is meant to be used in other operations that require an open file. Upon failure, the function returns `NULL'. EXAMPLE The following function opens a file in append mode and writes a string to it: define append_string_to_file (file, str) { variable fp = fopen (file, "a"); if (fp == NULL) verror ("%s could not be opened", file); () = fputs (string, fp); () = fclose (fp); } Note that the return values from `fputs' and `fclose' are ignored. NOTES There is no need to explicitly close a file opened with `fopen'. If the returned `File_Type' object goes out of scope, S-Lang will automatically close the file. However, explicitly closing a file after use is recommended. SEE ALSO fclose, fgets, fputs, popen -------------------------------------------------------------- fprintf SYNOPSIS Create and write a formatted string to a file USAGE Int_Type fprintf (File_Type fp, String_Type fmt, ...) DESCRIPTION `fprintf' formats the objects specified by the variable argument list according to the format `fmt' and write the result to the open file pointer `fp'. The format string obeys the same syntax and semantics as the `sprintf' format string. See the description of the `sprintf' function for more information. `fprintf' returns the number of characters written to the file, or -1 upon error. SEE ALSO fputs, printf, fwrite, message -------------------------------------------------------------- fputs SYNOPSIS Write a string to an open stream USAGE Integer_Type fputs (String_Type s, File_Type fp); DESCRIPTION The `fputs' function writes the string `s' to the open file pointer `fp'. It returns -1 upon failure and sets `errno', otherwise it returns the length of the string. EXAMPLE The following function opens a file in append mode and uses the `fputs' function to write to it. define append_string_to_file (str, file) { variable fp; fp = fopen (file, "a"); if (fp == NULL) verror ("Unable to open %s", file); if ((-1 == fputs (s, fp)) or (-1 == fclose (fp))) verror ("Error writing to %s", file); } NOTES One must not disregard the return value from the `fputs' function, as many C programmers do. Doing so may lead to a stack overflow error. To write an object that contains embedded null characters, use the `fwrite' function. SEE ALSO fclose, fopen, fgets, fwrite -------------------------------------------------------------- fread SYNOPSIS Read binary data from a file USAGE UInt_Type fread (Ref_Type b, DataType_Type t, UInt_Type n, File_Type fp) DESCRIPTION The `fread' function may be used to read `n' objects of type `t' from an open file pointer `fp'. Upon success, it returns the number of objects read from the file and places the objects in the variable specified by `b'. Upon error or end of file, it returns `-1'. If more than one object is read from the file, those objects will be placed in an array of the appropriate size. The exception to this is when reading `Char_Type' or `UChar_Type' objects from a file, in which case the data will be returned as a BString_Type binary string. EXAMPLE The following example illustrates how to read 50 bytes from a file: define read_50_bytes_from_file (file) { variable fp, n, buf; fp = fopen (file, "rb"); if (fp == NULL) error ("Open failed"); n = fread (&buf, Char_Type, 50, fp); if (n == -1) error ("fread failed"); () = fclose (fp); return buf; } NOTES Use the `pack' and `unpack' functions to read data with a specific byte-ordering. SEE ALSO fwrite, fgets, fopen, pack, unpack -------------------------------------------------------------- fseek SYNOPSIS Reposition a stream USAGE Integer_Type fseek (File_Type fp, Integer_Type ofs, Integer_Type whence DESCRIPTION The `fseek' function may be used to reposition the file position pointer associated with the open file stream `fp'. Specifically, it moves the pointer `ofs' bytes relative to the position indicated by `whence'. If whence is set to one of the symbolic constants `SEEK_SET', `SEEK_CUR', or `SEEK_END', the offset is relative to the start of the file, the current position indicator, or end-of-file, respectively. The function return zero upon success, or -1 upon failure and sets `errno' accordingly. EXAMPLE define rewind (fp) { if (0 == fseek (fp, 0, SEEK_SET)) return; vmessage ("rewind failed, reason: %s", errno_string (errno)); } NOTES The current implementation uses an integer to specify the offset. One some systems, a long integer may be required making this function fail for very large files, i.e., files that are longer than the maximum value of an integer. SEE ALSO ftell, fopen -------------------------------------------------------------- ftell SYNOPSIS Obtain the current position in an open stream USAGE Integer_Type ftell (File_Type fp) DESCRIPTION The ftell function may be used to obtain the current position in the stream associated with the open file pointer `fp'. It returns the position of the pointer measured in bytes from the beginning of the file. Upon error, it returns `-1' and sets `errno'. SEE ALSO fseek, fopen -------------------------------------------------------------- fwrite SYNOPSIS Write binary data to a file USAGE UInt_Type fwrite (b, File_Type fp) DESCRIPTION The `fwrite' may be used to write the object represented by `b' to an open file. If `b' is a string or an array, the function will attempt to write all elements of the object to the file. It returns the number of objects successfully written, otherwise it returns -1 upon error and sets `errno' accordingly. EXAMPLE The following example illustrates how to write an integer array to a file. In this example, `fp' is an open file descriptor: variable a = [1:50]; % 50 element integer array if (50 != fwrite (a, fp)) error ("fwrite failed"); Here is how to write the array one element at a time: variable a = [1:50]; foreach (a) { variable ai = (); if (1 != fwrite(ai, fp)) error ("fwrite failed"); } NOTES Not all data types may support the `fwrite' operation. However, it is supported by all vector, scalar, and string objects. SEE ALSO fread, fputs, fopen, pack, unpack -------------------------------------------------------------- pclose SYNOPSIS Close an object opened with popen USAGE Integer_Type pclose (File_Type fp) DESCRIPTION The `pclose' function waits for the process associated with `fp' to exit and the returns the exit status of the command. SEE ALSO pclose, fclose -------------------------------------------------------------- popen SYNOPSIS Open a process USAGE File_Type popen (String_Type cmd, String_Type mode) DESCRIPTION The `popen' function executes a process specified by `cmd' and opens a unidirectional pipe to the newly created process. The `mode' indicates whether or not the the pipe is open for reading or writing. Specifically, if `mode' is `"r"', then the pipe is opened for reading, or if `mode' is `"w"', then the pipe will be open for writing. Upon success, a `File_Type' pointer will be returned, otherwise the function failed and `NULL' will be returned. NOTES This function is not available on all systems. SEE ALSO pclose, fopen -------------------------------------------------------------- printf SYNOPSIS Create and write a formatted string to stdout USAGE Int_Type printf (String_Type fmt, ...) DESCRIPTION `fprintf' formats the objects specified by the variable argument list according to the format `fmt' and write the result to `stdout'. This function is equivalent to `fprintf' used with the `stdout' file pointer. See `fprintf' for more information. `printf' returns the number of characters written to the file, or -1 upon error. NOTES Many C programmers do not check the return status of the `printf' C library function. Make sure that if you do not care about whether or not the function succeeds, then code it as in the following example: () = printf ("%s laid %d eggs\n", chicken_name, num_egg); SEE ALSO fputs, printf, fwrite, message -------------------------------------------------------------- Sprintf SYNOPSIS Format objects into a string USAGE String_Type Sprintf (String_Type format, ..., Integer_Type n) DESCRIPTION `Sprintf' formats a string from `n' objects according to `format'. Unlike `sprintf', the `Sprintf' function requires the number of items to format. The format string is a C library `sprintf' style format descriptor. Briefly, the format string may consist of ordinary characters (not including the `%' character), which are copied into the output string as-is, and a conversion specification introduced by the `%' character. The `%' character must be followed by at least one other character to specify the conversion: s value is a string f value is a floating point number e print float in exponential form, e.g., 2.345e08 g print float as e or g, depending upon its value c value is an ascii character % print the percent character d print a signed decimal integer u print an unsigned decimal integer o print an integer as octal X print an integer as hexadecimal S convert value to a string and format as string Note that `%S' is a S-Lang extension which will cause the value to be formatted as string. In fact, `sprintf("%S",x)' is equivalent to `sprintf("%s",string(x))'. s = Sprintf("%f is greater than %f but %s is better than %s\n", PI, E, "Cake" "Pie", 4); The final argument to `Sprintf' is the number of items to format; in this case, there are 4 items. SEE ALSO sprintf, string, sscanf -------------------------------------------------------------- create_delimited_string SYNOPSIS Concatenate strings using a delimiter USAGE String_Type create_delimited_string (delim, s_1, s_2, ..., s_n, n) String_Type delim, s_1, ..., s_n Integer_Type n DESCRIPTION `create_delimited_string' performs a concatenation operation on the `n' strings `s_1', ...,`s_n', using the string `delim' as a delimiter. The resulting string is equivalent to one obtained via s_1 + delim + s_2 + delim + ... + s_n EXAMPLE One use for this function is to construct path names, e.g., create_delimited_string ("/", "user", "local", "bin", 3); will produce `"usr/local/bin"'. NOTES The expression `strcat(a,b)' is equivalent to `create_delimited_string("", a, b, 2)'. SEE ALSO strjoin, is_list_element, extract_element, strchop, strcat -------------------------------------------------------------- extract_element SYNOPSIS Extract the nth element of a string with delimiters USAGE String_Type extract_element (String_Type list, Integer_Type nth, Integer_Type delim); DESCRIPTION The `extract_element' function may be used to extract the `nth' element of the `delim' delimited list of strings `list'. The function will return the `nth' element of the list, unless `nth' specifies more elements than the list contains, in which case `NULL' will be returned. Elements in the list are numbered from `0'. EXAMPLE The expression extract_element ("element 0, element 1, element 2", 1, ',') returns the string `" element 1"', whereas extract_element ("element 0, element 1, element 2", 1, ' ') returns `"0,"'. The following function may be used to compute the number of elements in the list: define num_elements (list, delim) { variable nth = 0; while (NULL != extract_element (list, nth, delim)) nth++; return nth; } Alternatively, the `strchop' function may be more useful. In fact, `extract_element' may be expressed in terms of the function `strchop' as define extract_element (list, nth, delim) { list = strchop(list, delim, 0); if (nth >= length (list)) return NULL; else return list[nth]; } and the `num_elements' function used above may be recoded more simply as: define num_elements (list, delim) { return length (strchop (length, delim, 0)); } SEE ALSO is_list_element, is_substr, strtok, strchop, create_delimited_string -------------------------------------------------------------- is_list_element SYNOPSIS Test whether a delimited string contains a specific element USAGE Integer_Type is_list_element (String_Type list, String_Type elem, Integer_Type delim) DESCRIPTION The `is_list_element' function may be used to determine whether or not a delimited list of strings, `list', contains the element `elem'. If `elem' is not an element of `list', the function will return zero, otherwise, it returns 1 plus the matching element number. EXAMPLE The expression is_list_element ("element 0, element 1, element 2", "0,", ' '); returns `2' since `"0,"' is element number one of the list (numbered from zero). SEE ALSO extract_element, is_substr, create_delimited_string -------------------------------------------------------------- is_substr SYNOPSIS Test for a specified substring within a string. USAGE Integer_Type is_substr (String_Type a, String_Type b) DESCRIPTION This function may be used to determine if `a' contains the string `b'. If it does not, the function returns 0; otherwise it returns the position of the first occurance of `b' in `a'. NOTES It is important to remember that the first character of a string corresponds to a position value of `1'. SEE ALSO substr, string_match, strreplace -------------------------------------------------------------- make_printable_string SYNOPSIS Format a string suitable for parsing USAGE String_Type make_printable_string(String_Type str) DESCRIPTION This function formats a string in such a way that it may be used as an argument to the `eval' function. The resulting string is identical to `str' except that it is enclosed in double quotes and the backslash, newline, and double quote characters are expanded. SEE ALSO eval, str_quote_string -------------------------------------------------------------- sprintf SYNOPSIS Format objects into a string USAGE String sprintf (String format, ...); DESCRIPTION This function performs a similar task as the C function with the same name. It differs from the S-Lang function `Sprintf' in that it does not require the number of items to format. See the documentation for `Sprintf' for more information. SEE ALSO Sprintf, string, sscanf, vmessage -------------------------------------------------------------- sscanf SYNOPSIS Parse a formatted string USAGE Int_Type sscanf (s, fmt, r1, ... rN) String_Type s, fmt; Ref_Type r1, ..., rN DESCRIPTION The `sscanf' function parses the string `s' according to the format `fmt' and sets the variables whose references are given by `r1', ..., `rN'. The function returns the number of references assigned, or `-1' upon error. The format string `fmt' consists of ordinary characters and conversion specifiers. A conversion specifier begins with the special character `%' and is described more fully below. A white space character in the format string matches any amount of whitespace in the input string. Parsing of the format string stops whenever a match fails. The `%' is used to denote a conversion specifier whose general form is given by `%[*][width][type]format' where the brackets indicate optional items. If `*' is present, then the conversion will be performed by no assignment to a reference will be made. The `width' specifier specifies the maximum field width to use for the conversion. The `type' modifier is used to indicate size of the object, e.g., a short integer, as follows. If _type_ is given as the character `h', then if the format conversion is for an integer (`dioux'), the object assigned will be a short integer. If _type_ is `l', then the conversion will be to a long integer for integer conversions, or to a double precession floating point number for floating point conversions. The format specifier is a character that specifies the conversion: % Matches a literal percent character. No assigment is performed. d Matches a signed decimal integer. D Matches a long decimal integer (equiv to `ld') u Matches an unsigned decimal integer U Matches an unsigned long decimal integer (equiv to `lu') i Matches either a hexidecimal integer, decimal integer, or octal integer. I Equivalent to `li'. x Matches a hexidecimal integer. X Matches a long hexidecimal integer (same as `lx'). e,f,g Matches a decimal floating point number (Float_Type). E,F,G Matches a double precision floating point number, same as `lf'. s Matches a string of non-whitespace characters (String_Type). c Matches one character. If width is given, width characters are matched. n Assigns the number of characters scanned so far. [...] Matches zero or more characters from the set of characters enclosed by the square brackets. If '^' is given as the first character, then the complement set is matched. EXAMPLE Suppose that `s' is `"Coffee: (3,4,12.4)"'. Then n = sscanf (s, "%[a-zA-Z]: (%d,%d,%lf)", &item, &x, &y, &z); will set `n' to 4, `item' to `"Coffee"', `x' to 3, `y' to 4, and `z' to the double precision number `12.4'. However, n = sscanf (s, "%s: (%d,%d,%lf)", &item, &x, &y, &z); will set `n' to 1, `item' to `"Coffee:"' and the remaining variables will not be assigned. SEE ALSO sprintf, unpack, string, atof, int, integer, string_match -------------------------------------------------------------- str_delete_chars SYNOPSIS Delete characters from a string USAGE String_Type str_delete_chars (String_Type str, String_Type del_set DESCRIPTION This function may be used to delete the set of characters specified by `del_set' from the string `str'. The result is returned. EXAMPLE str = str_delete_chars (str, "^A-Za-z"); will remove all characters except `A-Z' and `a-z' from `str'. -------------------------------------------------------------- str_quote_string SYNOPSIS Escape characters in a string. USAGE String_Type str_quote_string(String_Type str, String_Type qlis, Integer_Type quote) DESCRIPTION The `str_quote_string' returns a string identical to `str' except that all characters in the set specified by the string `qlis' are escaped with the `quote' character, including the quote character itself. This function is useful for making a string that can be used in a regular expression. EXAMPLE Execution of the statements node = "Is it [the coat] really worth $100?"; tag = str_quote_string (node, "\\^$[]*.+?", '\\'); will result in `tag' having the value: Is it \[the coat\] really worth \$100\? SEE ALSO str_uncomment_string, make_printable_string -------------------------------------------------------------- str_replace SYNOPSIS Replace a substring of a string USAGE Integer_Type str_replace (String_Type a, String_Type b, String_Type c) DESCRIPTION The `str_replace' function replaces the first occurance of `b' in `a' with `c' and returns an integer that indicates whether a replacement was made or not. If `b' does not occur in `a', zero is returned. However, if `b' occurs in `a', a non-zero integer is returned as well as the new string resulting from the replacement. NOTES This function has been superceded by `strreplace'. SEE ALSO strreplace -------------------------------------------------------------- str_uncomment_string SYNOPSIS Remove comments from a string USAGE String_Type str_uncomment_string(String_Type s, String_Type beg, String_Type end) DESCRIPTION This function may be used to remove comments from a string `s'. The parameters, `beg' and `end', are strings of equal length whose corresponding characters specify the begin and end comment characters, respectively. It returns the uncommented string. EXAMPLE The expression str_uncomment_string ("Hello (testing) 'example' World", "'(", "')") returns the string `"Hello World"'. NOTES This routine does not handle multicharacter comment delimiters and it assumes that comments are not nested. SEE ALSO str_quote_string -------------------------------------------------------------- strcat SYNOPSIS Concatenate strings USAGE String_Type strcat (String_Type a_1, ..., String_Type a_N) DESCRIPTION The `strcat' function concatenates its N `String_Type' arguments `a_1', ... `a_N' together and returns the result. EXAMPLE strcat ("Hello", " ", "World"); produces the string `"Hello World"'. NOTES This function is equivalent to the binary operation `a_1+...+a_N'. However, `strcat' is much faster making it the preferred method to concatenate string. SEE ALSO sprintf, create_delimited_string -------------------------------------------------------------- strchop SYNOPSIS Chop or split a string into substrings. USAGE String_Type[] strchop (String_Type str, Integer_Type delim, Integer_Type quote) DESCRIPTION The `strchop' function may be used to split-up a string `str' that consists of substrings delimited by the character specified by `delim'. If the integer `quote' is non-zero, it will be taken as a quote character for the delimiter. The function returns the substrings as an array. EXAMPLE The following function illustrates how to sort a comma separated list of strings: define sort_string_list (a) { variable i, b, c; b = strchop (a, ',', 0); i = array_sort (b, &strcmp); b = b[i]; % rearrange % Convert array back into comma separated form return strjoin (b, ","); } NOTES The semantics of this `strchop' and `strchopr' have been changed since version 1.2.x of the interpreter. Old versions of these functions returned the values on the stack, which meant that one could not chop up arbitrarily long strings that consist of many substrings. The function `strchopr' should be used if it is desired to have the string chopped-up in the reverse order. SEE ALSO strchopr, extract_element, strjoin, strtok -------------------------------------------------------------- strchopr SYNOPSIS Chop or split a string into substrings. USAGE String_Type[] strchopr (String_Type str, String_Type delim, String_Type quote) DESCRIPTION This routine performs exactly the same function as `strchop' except that it returns the substrings in the reverse order. See the documentation for `strchop' for more information. SEE ALSO strchop, extract_element, strtok, strjoin -------------------------------------------------------------- strcmp SYNOPSIS Compare two strings USAGE Interpret strcmp (String_Type a, String_Type b) DESCRIPTION The `strcmp' function may be used to perform a case-sensitive string comparison, in the lexicongraphic sense, on strings `a' and `b'. It returns 0 if the strings are identical, a negative integer if `a' is less than `b', or a positive integer if `a' is greater than `b'. EXAMPLE The `strup' function may be used to perform a case-insensitive string comparison: define case_insensitive_strcmp (a, b) { return strcmp (strup(a), strup(b)); } NOTES One may also use one of the binary comparison operators, e.g., `a > b'. SEE ALSO strup, strncmp -------------------------------------------------------------- strcompress SYNOPSIS Remove excess whitespace characters from a string USAGE String_Type strcompress (String_Type s, String_Type white) DESCRIPTION The `strcompress' function compresses the string `s' by replacing a sequence of one or more characters from the set `white' by the first character of `white'. In addition, it also removes all leading and trailing characters from `s' that are part of `white'. EXAMPLE The expression strcompress (",;apple,,cherry;,banana", ",;"); returns the string `"apple,cherry,banana"'. SEE ALSO strtrim, strtrans -------------------------------------------------------------- string_match SYNOPSIS Match a string against a regular expression USAGE Integer_Type string_match(String_Type str, String_Type pat, Integer_Type pos) DESCRIPTION The `string_match' function returns zero if `str' does not match regular expression specified by `pat'. This function performs the match starting at position `pos' (numbered from 1) in `str'. This function returns the position of the start of the match. To find the exact substring actually matched, use `string_match_nth'. SEE ALSO string_match_nth, strcmp, strncmp -------------------------------------------------------------- string_match_nth SYNOPSIS Get the result of the last call to string_match USAGE (Integer_Type, Integer_Type) = string_match_nth(Integer_Type nth) DESCRIPTION The `string_match_nth' function returns two integers describing the result of the last call to `string_match'. It returns both the offset into the string and the length of characters matches by the `nth' submatch. By convention, `nth' equal to zero means the entire match. Otherwise, `nth' must be an integer with a value 1 through 9, and refers to the set of characters matched by the `nth' regular expression enclosed by the pairs `\(, \)'. EXAMPLE Consider: variable matched, pos, len; matched = string_match("hello world", "\\([a-z]+\\) \\([a-z]+\\)", 1); if (matched) (pos, len) = string_match_nth(2); This will set `matched' to 1 since a match will be found at the first position, `pos' to 6 since `w' is offset 6 characters from the beginning of the string, and `len' to 5 since `"world"' is 5 characters long. NOTES The position offset is _not_ affected by the value of the offset parameter to the `string_match' function. For example, if the value of the last parameter to the `string_match' function had been 3, `pos' would still have been set to 6. Note also that `string_match_nth' returns the _offset_ from the beginning of the string and not the position of the match. SEE ALSO string_match -------------------------------------------------------------- strjoin SYNOPSIS Concatenate elements of a string array USAGE String_Type strjoin (Array_Type a, String_Type delim) DESCRIPTION The `strjoin' function operates on an array of strings by joining successive elements together separated with a delimiter `delim'. If `delim' is the empty string `""', then the result will simply be the concatenation of the elements. EXAMPLE Suppose that days = ["Sun","Mon","Tue","Wed","Thu","Fri","Sat","Sun"]; Then `strjoin (days,"+")' will produce `"Sun+Mon+Tue+Wed+Thu+Fri+Sat+Sun"'. Similarly, `strjoin (["","",""], "X")' will produce `"XX"'. SEE ALSO create_delimited_string, strchop, strcat -------------------------------------------------------------- strlen SYNOPSIS Compute the length of a string USAGE Integer_Type strlen (String_Type a) DESCRIPTION The `strlen' function may be used to compute the length of a string. EXAMPLE After execution of variable len = strlen ("hello"); `len' will have a value of `5'. SEE ALSO bstrlen, length, substr -------------------------------------------------------------- strlow SYNOPSIS Convert a string to lowercase USAGE String_Type strlow (String_Type s) DESCRIPTION The `strlow' function takes a string `s' and returns another string identical to `s' except that all upper case characters that comprise `s' will be converted to lower case. EXAMPLE The function define Strcmp (a, b) { return strcmp (strlow (a), strlow (b)); } performs a case-insensitive comparison operation of two strings by converting them to lower case first. SEE ALSO strup, tolower, strcmp, strtrim, define_case -------------------------------------------------------------- strncmp SYNOPSIS Compare the first few characters of two strings USAGE Integer_Type strncmp (String_Type a, String_Type b, Integer_Type n) DESCRIPTION This function behaves like `strcmp' except that it compares only the first `n' characters in the strings `a' and `b'. See the documentation for `strcmp' for information about the return value. EXAMPLE The expression strcmp ("apple", "appliance", 3); will return zero since the first three characters match. SEE ALSO strcmp, strlen -------------------------------------------------------------- strreplace SYNOPSIS Replace one or more substrings USAGE (new, n) = strreplace (a, b, c, max_n) String_Type a, b, c, rep; Int_Type n, max_n; DESCRIPTION The `strreplace' function may be used to replace one or more occurances of `b' in `a' with `c'. If the integer `max_n' is positive, then the first `max_n' occurances of `b' in `a' will be replaced. Otherwise, if `max_n' is negative, then the last `abs(max_n)' occurances will be replaced. The function returns the resulting string and an integer indicating how many replacements were made. EXAMPLE The following function illustrates how `strreplace' may be used to remove all occurances of a specified substring define delete_substrings (a, b) { (a, ) = strreplace (a, b, "", strlen (a)); return a; } SEE ALSO is_substr, strsub, strtrim, strtrans, str_delete_chars -------------------------------------------------------------- strsub SYNOPSIS Replace a character with another in a string. USAGE String_Type strsub (String_Type s, Integer_Type pos, Integer_Type ch) DESCRIPTION The `strsub' character may be used to substitute the character `ch' for the character at position `pos' of the string `s'. The resulting string is returned. EXAMPLE define replace_spaces_with_comma (s) { variable n; while (n = is_substr (s, " "), n) s = strsub (s, n, ','); return s; } For uses such as this, the `strtrans' function is a better choice. NOTES The first character in the string `s' is specified by `pos' equal to 1. SEE ALSO is_substr, strreplace, strlen -------------------------------------------------------------- strtok SYNOPSIS Extract tokens from a string USAGE String_Type[] strtok (String_Type str [,String_Type white]) DESCRIPTION `strtok' breaks the string `str' into a series of tokens and returns them as an array of strings. If the second parameter `white' is present, then it specifies the set of characters that are to be regarded as whitespace when extracting the tokens, and may consist of the whitespace characters or a range of such characters. If the first character of `white' is `'^'', then the whitespace characters consist of all characters except those in `white'. For example, if `white' is `" \t\n,;."', then those characters specifiy the whitespace characters. However, if `white' is given by `"^a-zA-Z0-9_"', then any character is a whitespace character except those in the ranges `a-z', `A-Z', `0-9', and the underscore character. If the second parameter is not present, then it defaults to `" \t\r\n\f"'. EXAMPLE The following example may be used to count the words in a text file: define count_words (file) { variable fp, line, count; fp = fopen (file, "r"); if (fp == NULL) return -1; count = 0; while (-1 != fgets (&line, fp)) { line = strtok (line, "^a-zA-Z"); count += length (line); } () = fclose (fp); return count; } SEE ALSO strchop, strcompress, extract_element, strjoin -------------------------------------------------------------- strtrans SYNOPSIS Replace characters in a string USAGE String_Type strtrans (str, old_set, new_set) String_Type str, old_set, new_set; DESCRIPTION The `strtrans' function may be used to replace all the characters from the set `old_set' with the corresponding characters from `new_set' in the string `str'. If `new_set' is empty, then the characters in `new_set' will be removed from `str'. This function returns the result. EXAMPLE str = strtrans (str, "A-Z", "a-z"); % lower-case str str = strtrans (str, "^0-9", " "); % Replace anything but 0-9 by space SEE ALSO strreplace, strtrim, strup, strlow -------------------------------------------------------------- strtrim SYNOPSIS Remove whitespace from the ends of a string USAGE String_Type strtrim (String_Type s [,String_Type w]) DESCRIPTION The `strtrim' function removes all leading and trailing whitespace characters from the string `s' and returns the result. The optional second parameter specifies the set of whitespace characters. If the argument is not present, then the set defaults to `" \t\r\n"'. SEE ALSO strtrim_beg, strtrim_end, strcompress -------------------------------------------------------------- strtrim_beg SYNOPSIS Remove leading whitespace from a string USAGE String_Type strtrim_beg (String_Type s [,String_Type w]) DESCRIPTION The `strtrim_beg' function removes all leading whitespace characters from the string `s' and returns the result. The optional second parameter specifies the set of whitespace characters. If the argument is not present, then the set defaults to `" \t\r\n"'. SEE ALSO strtrim, strtrim_end, strcompress -------------------------------------------------------------- strtrim_end SYNOPSIS Remove trailing whitespace from a string USAGE String_Type strtrim_end (String_Type s [,String_Type w]) DESCRIPTION The `strtrim_end' function removes all trailing whitespace characters from the string `s' and returns the result. The optional second parameter specifies the set of whitespace characters. If the argument is not present, then the set defaults to `" \t\r\n"'. SEE ALSO strtrim, strtrim_beg, strcompress -------------------------------------------------------------- strup SYNOPSIS Convert a string to uppercase USAGE String_Type strup (String_Type s) DESCRIPTION The `strup' function takes a string `s' and returns another string identical to `s' except that all lower case characters that comprise `s' will be converted to upper case. EXAMPLE The function define Strcmp (a, b) { return strcmp (strup (a), strup (b)); } performs a case-insensitive comparison operation of two strings by converting them to upper case first. SEE ALSO strlow, toupper, strcmp, strtrim, define_case, strtrans -------------------------------------------------------------- substr SYNOPSIS Extract a substring from a string USAGE String_Type substr (String_Type s, Integer_Type n, Integer_Type len) DESCRIPTION The `substr' function returns a substring with length `len' of the string `s' beginning at position `n'. If `len' is `-1', the entire length of the string `s' will be used for `len'. The first character of `s' is given by `n' equal to 1. EXAMPLE substr ("To be or not to be", 7, 5); returns `"or no"' NOTES In many cases it is more convenient to use array indexing rather than the `substr' function. In fact, `substr(s,i+1,strlen(s))' is equivalent to `s[[i:]]'. SEE ALSO is_substr, strlen -------------------------------------------------------------- _push_struct_field_values SYNOPSIS Push the values of a structure's fields onto the stack USAGE Integer_Type num = _push_struct_field_values (Struct_Type s) DESCRIPTION The `_push_struct_field_values' function pushes the values of all the fields of a structure onto the stack, returning the number of items pushed. The fields are pushed such that the last field of the structure is pushed first. SEE ALSO get_struct_field_names, get_struct_field -------------------------------------------------------------- get_struct_field SYNOPSIS Get the value associated with a structure field USAGE x = get_struct_field (Struct_Type s, String field_name) DESCRIPTION The `get_struct_field' function gets the value of the field whose name is specified by `field_name' of the structure `s'. EXAMPLE The following example illustrates how this function may be used to to print the value of a structure. define print_struct (s) { variable name; foreach (get_struct_field_names (s)) { name = (); value = get_struct_field (s, name); vmessage ("s.%s = %s\n", name, string(value)); } } SEE ALSO set_struct_field, get_struct_field_names, array_info -------------------------------------------------------------- get_struct_field_names SYNOPSIS Retrieve the field names associated with a structure USAGE String_Type[] = get_struct_field_names (Struct_Type s) DESCRIPTION The `get_struct_field_names' function returns an array of strings whose elements specify the names of the fields of the struct `s'. EXAMPLE The following example illustrates how the `get_struct_field_names' function may be used to print the value of a structure. define print_struct (s) { variable name, value; foreach (get_struct_field_names (s)) { name = (); value = get_struct_field (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 the parameter refers to a structure or a user-defined type. If the object is neither, 0 will be returned. SEE ALSO typeof, _typeof -------------------------------------------------------------- set_struct_field SYNOPSIS Set the value associated with a structure field USAGE set_struct_field (s, field_name, field_value) Struct_Type s; String_Type field_name; Generic_Type field_value; DESCRIPTION The `set_struct_field' function sets the value of the field whose name is specified by `field_name' of the structure `s' to `field_value'. SEE ALSO get_struct_field, get_struct_field_names, set_struct_fields, array_info -------------------------------------------------------------- set_struct_fields SYNOPSIS Set the fields of a structure USAGE set_struct_fields (Struct_Type s, ...) DESCRIPTION The `set_struct_fields' function may be used to set zero or more fields of a structure. The fields are set in the order in which they were created when the structure was defined. EXAMPLE variable s = struct { "name", "age", "height" }; set_struct_fields (s, "Bill", 13, 64); SEE ALSO set_struct_field, get_struct_field_names -------------------------------------------------------------- _time SYNOPSIS Get the current time in seconds USAGE ULong_Type _time () DESCRIPTION The `_time' function returns the number of elapsed seconds since 00:00:00 GMT, January 1, 1970. The `ctime' function may be used to convert this into a string representation. SEE ALSO ctime, time, localtime, gmtime -------------------------------------------------------------- ctime SYNOPSIS Convert a calendar time to a string USAGE String_Type ctime(ULong_Type secs) DESCRIPTION This function returns a string representation of the time as given by `secs' seconds since 1970. SEE ALSO time, _time, localtime, gmtime -------------------------------------------------------------- gmtime SYNOPSIS Break down a time in seconds to GMT timezone USAGE Struct_Type gmtime (Long_Type secs) DESCRIPTION The `gmtime' function is exactly like `localtime' except that the values in the structure it returns are with respect to GMT instead of the local timezone. See the documentation for `localtime' for more information. NOTES On systems that do not support the `gmtime' C library function, this function is the same as `localtime'. SEE ALSO localtime, _time -------------------------------------------------------------- localtime SYNOPSIS Break down a time in seconds to local timezone USAGE Struct_Type localtime (Long_Type secs) DESCRIPTION The `localtime' function takes a parameter `secs' representing the number of seconds since 00:00:00, January 1 1970 UTC and returns a structure containing information about `secs' in the local timezone. The structure contains the following `Int_Type' fields: `tm_sec' The number of seconds after the minute, normally in the range 0 to 59, but can be up to 61 to allow for leap seconds. `tm_min' The number of minutes after the hour, in the range 0 to 59. `tm_hour' The number of hours past midnight, in the range 0 to 23. `tm_mday' The day of the month, in the range 1 to 31. `tm_mon' The number of months since January, in the range 0 to 11. `tm_year' The number of years since 1900. `tm_wday' The number of days since Sunday, in the range 0 to 6. `tm_yday' The number of days since January 1, in the range 0 to 365. `tm_isdst' A flag that indicates whether daylight saving time is in effect at the time described. The value is positive if daylight saving time is in effect, zero if it is not, and negative if the information is not available. SEE ALSO gmtime, _time, ctime -------------------------------------------------------------- tic SYNOPSIS Start timing USAGE void tic () DESCRIPTION The `tic' function restarts the internal clock used for timing the execution of commands. To get the elapsed time of the clock, use the `toc' function. SEE ALSO toc, times -------------------------------------------------------------- time SYNOPSIS Return the current data and time as a string USAGE String_Type time () DESCRIPTION This function returns the current time as a string of the form: Sun Apr 21 13:34:17 1996 SEE ALSO ctime, message, substr -------------------------------------------------------------- times SYNOPSIS Get process times USAGE Struct_Type times () DESCRIPTION The `times' function returns a structure containing the following fields: tms_utime (user time) tms_stime (system time) tms_cutime (user time of child processes) tms_cstime (system time of child processes) NOTES Not all systems support this function. SEE ALSO tic, toc, _times -------------------------------------------------------------- toc SYNOPSIS Get elapsed CPU time USAGE Double_Type toc () DESCRIPTION The `toc' function returns the elapsed CPU time in seconds since the last call to `tic'. The CPU time is the amount of time the CPU spent running the code of the current process. EXAMPLE The `tic' and `toc' functions are ideal for timing the execution of the interpreter: variable a = "hello", b = "world", c, n = 100000, t; tic (); loop (n) c = a + b; t = toc (); vmessage ("a+b took %f seconds\n", t); tic (); loop (n) c = strcat(a,b); t = toc (); vmessage ("strcat took %f seconds\n", t); NOTES This function may not be available on all systems. The implementation of this function is based upon the `times' system call. The precision of the clock is system dependent. SEE ALSO tic, times, _time -------------------------------------------------------------- _slang_guess_type SYNOPSIS Guess the data type that a string represents. USAGE DataType_Type _slang_guess_type (String_Type s) DESCRIPTION This function tries to determine whether its argument `s' represents an integer or a floating point number. If it appears to be neither, then a string is assumed. It returns one of three values depending on the format of the string `s': Integer_Type : If it appears to be an integer Double_Type : If it appears to be a double String_Type : Anything else. For example, `_slang_guess_type("1e2")' returns `Double_Type' but `_slang_guess_type("e12")' returns `String_Type'. SEE ALSO integer, string, double -------------------------------------------------------------- _typeof SYNOPSIS Get the data type of an object USAGE DataType_Type _typeof (x) DESCRIPTION This function is similar to the `typeof' function except in the case of arrays. If the object `x' is an array, then the data type of the array will be returned. otherwise `_typeof' returns the data type of `x'. EXAMPLE if (Integer_Type == _typeof (x)) message ("x is an integer or an integer array"); SEE ALSO typeof, array_info, _slang_guess_type, typecast -------------------------------------------------------------- atof SYNOPSIS Convert a string to a double precision number USAGE Double_Type atof (String_Type s) DESCRIPTION This function converts a string `s' to a double precision value and returns the result. It performs no error checking on the format of the string. The function `_slang_guess_type' may be used to check the syntax of the string. EXAMPLE define error_checked_atof (s) { switch (_slang_guess_type (s)) { case Double_Type: return atof (s); } { case Integer_Type: return double (integer (s)); } verror ("%s is is not a double", s); } SEE ALSO typecast, double, _slang_guess_type -------------------------------------------------------------- char SYNOPSIS Convert an ascii value into a string USAGE String_Type char (Integer_Type c) DESCRIPTION The `char' function converts an integer ascii value `c' to a string of unit length such that the first character of the string is `c'. For example, `char('a')' returns the string `"a"'. SEE ALSO integer, string, typedef -------------------------------------------------------------- define_case SYNOPSIS Define upper-lower case conversion. USAGE define_case (Integer_Type ch_up, Integer_Type ch_low); DESCRIPTION This function defines an upper and lowercase relationship between two characters specified by the arguments. This relationship is used by routines which perform uppercase and lowercase conversions. The first integer `ch_up' is the ascii value of the uppercase character and the second parameter `ch_low' is the ascii value of its lowercase counterpart. SEE ALSO strlow, strup -------------------------------------------------------------- double SYNOPSIS Convert an object to double precision USAGE result = double (x) DESCRIPTION The `double' function typecasts an object `x' to double precision. For example, if `x' is an array of integers, an array of double types will be returned. If an object cannot be converted to `Double_Type', a type-mismatch error will result. NOTES The `double' function is equivalent to the typecast operation typecast (x, Double_Type) To convert a string to a double precision number, use `atoi' function. SEE ALSO typecast, atoi, int -------------------------------------------------------------- int SYNOPSIS Typecast an object to an integer USAGE int (s) DESCRIPTION This function performs a typecast of `s' from its data type to an object of `Integer_Type'. If `s' is a string, it returns returns the ascii value value of the first character of the string `s'. If `s' is `Double_Type', `int' truncates the number to an integer and returns it. EXAMPLE `int' can be used to convert single character strings to integers. As an example, the intrinsic function `isdigit' may be defined as define isdigit (s) { if ((int (s) >= '0') and (int (s) <= '9')) return 1; return 0; } NOTES This function is equalent to `typecast (s, Integer_Type)'; SEE ALSO typecast, double, integer, char, isdigit -------------------------------------------------------------- integer SYNOPSIS Convert a string to an integer USAGE Integer_Type integer (String_Type s) DESCRIPTION The `integer' function converts a string representation of an integer back to an integer. If the string does not form a valid integer, a type-mismatch error will be generated. EXAMPLE `integer ("1234")' returns the integer value `1234'. NOTES This function operates only on strings and is not the same as the more general `typecast' operator. SEE ALSO typecast, _slang_guess_type, string, sprintf, char -------------------------------------------------------------- isdigit SYNOPSIS Tests for a decimal digit character USAGE Integer_Type isdigit (String_Type s) DESCRIPTION This function returns a non-zero value if the first character in the string `s' is a digit; otherwise, it returns zero. EXAMPLE A simple, user defined implementation of `isdigit' is define isdigit (s) { return ((s[0] <= '9') and (s[0] >= '0')); } However, the intrinsic function `isdigit' executes many times faster than the equivalent representation defined above. NOTES Unlike the C function with the same name, the S-Lang function takes a string argument. SEE ALSO int, integer -------------------------------------------------------------- string SYNOPSIS Convert an object to a string representation. USAGE Integer_Type string (obj) DESCRIPTION The `string' function may be used to convert an object `obj' of any type to a string representation. For example, `string(12.34)' returns `"12.34"'. EXAMPLE define print_anything (anything) { message (string (anything)); } NOTES This function is _not_ the same as typecasting to a `String_Type' using the `typecast' function. SEE ALSO typecast, sprintf, integer, char -------------------------------------------------------------- tolower SYNOPSIS Convert a character to lowercase. USAGE Integer_Type lower (Integer_Type ch) DESCRIPTION This function takes an integer `ch' and returns its lowercase equivalent. SEE ALSO toupper, strup, strlow, int, char, define_case -------------------------------------------------------------- toupper SYNOPSIS Convert a character to uppercase. USAGE Integer_Type toupper (Integer_Type ch) DESCRIPTION This function takes an integer `ch' and returns its uppercase equivalent. SEE ALSO tolower, strup, strlow, int, char, define_case -------------------------------------------------------------- typecast SYNOPSIS Convert an object from one data type to another. USAGE typecast (x, new_type) DESCRIPTION The `typecast' function performs a generic typecast operation on `x' to convert it to `new_type'. If `x' represents an array, the function will attempt to convert all elements of `x' to `new_type'. Not all objects can be converted and a type-mismatch error will result upon failure. EXAMPLE define to_complex (x) { return typecast (x, Complex_Type); } defines a function that converts its argument, `x' to a complex number. SEE ALSO int, double, typeof -------------------------------------------------------------- typeof SYNOPSIS Get the data type of an object. USAGE DataType_Type typeof (x) DESCRIPTION This function returns the data type of `x'. EXAMPLE if (Integer_Type == typeof (x)) message ("x is an integer"); SEE ALSO _typeof, is_struct_type, array_info, _slang_guess_type, typecast --------------------------------------------------------------