Edit File: slangfun.txt
all SYNOPSIS Tests if all elements of an array are non-zero USAGE Char_Type all (Array_Type a [,Int_Type dim]) DESCRIPTION The `all' function examines the elements of a numeric array and returns 1 if all elements are non-zero, otherwise it returns 0. If a second argument is given, then it specifies the dimension of the array over which the function is to be applied. In this case, the result will be an array with the same shape as the input array minus the specified dimension. EXAMPLE Consider the 2-d array 1 2 3 4 5 6 7 8 9 10 generated by a = _reshape ([1:10], [2, 5]); Then `all(a)' will return 1, and `all(a>3, 0)' will return a 1-d array [0, 0, 0, 1, 1] Similarly, `all(a>3, 1)' will return the 1-d array [0,1] SEE ALSO where, any -------------------------------------------------------------- any SYNOPSIS Test if any element of an array is non-zero USAGE Char_Type any (Array_Type a [,Int_Type dim]) DESCRIPTION The `any' function examines the elements of a numeric array and returns 1 if any element is both non-zero and not a NaN, otherwise it returns 0. If a second argument is given, then it specifies the dimension of the array to be tested. EXAMPLE Consider the 2-d array 1 2 3 4 5 6 7 8 9 10 generated by a = _reshape ([1:10], [2, 5]); Then `any(a==3)' will return 1, and `any(a==3, 0)' will return a 1-d array with elements: 0 0 1 0 0 SEE ALSO where, all -------------------------------------------------------------- array_info SYNOPSIS Returns information about an array USAGE (Array_Type, Integer_Type, DataType_Type) array_info (Array_Type a) DESCRIPTION The `array_info' function returns information about the array `a'. It returns three values: an 1-d integer array specifying the size of each dimension of `a', the number of dimensions of `a', and the data type of `a'. EXAMPLE The `array_info' function may be used to find the number of rows of an array: define num_rows (a) { variable dims, num_dims, data_type; (dims, num_dims, data_type) = array_info (a); return dims [0]; } SEE ALSO typeof, array_shape, length, reshape, _reshape -------------------------------------------------------------- array_map SYNOPSIS Apply a function to each element of an array USAGE Array_Type array_map (type, func, 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 resulting values as an array of the specified type. The `type' parameter indicates what kind of array should be returned and generally corresponds to the return type of the function. 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 mathematical 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_reverse SYNOPSIS Reverse the elements of an array USAGE array_reverse (Array_Type a [,Int_Type i0, Int_Type i1] [,Int_Type dim]) DESCRIPTION In its simplest form, the `array_reverse' function reverses the elements of an array. If passed 2 or 4 arguments, `array_reverse' reverses the elements of the specified dimension of a multi-dimensional array. If passed 3 or 4 arguments, the parameters `i0' and `i1' specify a range of elements to reverse. EXAMPLE If `a' is a one dimensional array, then array_reverse (a, i, j); a[[i:j]] = a[[j:i:-1]]; are equivalent to one another. However, the form using `array_reverse' is about 10 times faster than the version that uses explicit array indexing. SEE ALSO array_swap, transpose -------------------------------------------------------------- array_shape SYNOPSIS Get the shape or dimensions of an array USAGE dims = array_shape (Array_Type a) DESCRIPTION This function returns an array representing the dimensionality or shape of a specified array. The `array_info' function also returns this information but for many purposes the `array_shape' function is more convenient. SEE ALSO array_info, reshape -------------------------------------------------------------- array_sort SYNOPSIS Sort an array 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 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 comparison 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 performed using the `strcmp' function. The integer array returned by this function is simply an index array 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: A = ["gamma", "alpha", "beta"]; I = array_sort (A, &strcmp); Alternatively, one may use variable I = array_sort (A); to use the built-in comparison function. After the `array_sort' has executed, the variable `I' will have the values `[2, 0, 1]'. This array can be used to re-shuffle the elements of `A' into the sorted order via the array index expression `A = A[I]'. This operation may also be written: A = A[array_sort(A)]; EXAMPLE A homogeneous list may be sorted by first converting it to an array as follows: list = list[ array_sort( list_to_array(list) ) ]; Alternatively one may use a = list_to_array (list); list[*] = a[array_sort(a)]; to get the effect of an "in-place" sort. SEE ALSO strcmp, list_to_array -------------------------------------------------------------- array_swap SYNOPSIS Swap elements of an array USAGE array_swap (Array_Type a, Int_Type i, Int_Type j) DESCRIPTION The `array_swap' function swaps the specified elements of an array. It is equivalent to (a[i], a[j]) = (a[j], a[i]); except that it executes several times faster than the above construct. SEE ALSO array_reverse, transpose -------------------------------------------------------------- cumsum SYNOPSIS Compute the cumulative sum of an array USAGE result = cumsum (Array_Type a [, Int_Type dim]) DESCRIPTION The `cumsum' function performs a cumulative sum over the elements of a numeric array and returns the result. If a second argument is given, then it specifies the dimension of the array to be summed over. For example, the cumulative sum of `[1,2,3,4]', is the array `[1,1+2,1+2+3,1+2+3+4]', i.e., `[1,3,6,10]'. SEE ALSO sum, sumsq -------------------------------------------------------------- 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 -------------------------------------------------------------- _isnull SYNOPSIS Check an array for NULL elements USAGE Char_Type[] = _isnull (a[]) DESCRIPTION This function may be used to test for the presence of NULL elements of an array. Specifically, it returns a Char_Type array of with the same number of elements and dimensionality of the input array. If an element of the input array is NULL, then the corresponding element of the output array will be set to 1, otherwise it will be set to 0. EXAMPLE Set all NULL elements of a string array `A' to the empty string `""': A[where(_isnull(A))] = ""; NOTES It is important to understand the difference between `A==NULL' and `_isnull(A)'. The latter tests all elements of `A' against NULL, whereas the former only tests `A' itself. SEE ALSO where, array_map -------------------------------------------------------------- length SYNOPSIS Get the length of an object USAGE Integer_Type length (obj) DESCRIPTION The `length' function may be used to get information about the length of an object. For simple scalar data-types, it returns 1. For arrays, it returns the total number of elements of the array. NOTES If `obj' is a string, `length' returns 1 because a String_Type object is considered to be a scalar. To get the number of characters in a string, use the `strlen' function. SEE ALSO array_info, array_shape, typeof, strlen -------------------------------------------------------------- max SYNOPSIS Get the maximum value of an array USAGE result = max (Array_Type a [,Int_Type dim]) DESCRIPTION The `max' function examines the elements of a numeric array and returns the value of the largest element. If a second argument is given, then it specifies the dimension of the array to be searched. In this case, an array of dimension one less than that of the input array will be returned with the corresponding elements in the specified dimension replaced by the maximum value in that dimension. EXAMPLE Consider the 2-d array 1 2 3 4 5 6 7 8 9 10 generated by a = _reshape ([1:10], [2, 5]); Then `max(a)' will return `10', and `max(a,0)' will return a 1-d array with elements 6 7 8 9 10 NOTES This function ignores NaNs in the input array. SEE ALSO min, maxabs, sum, reshape -------------------------------------------------------------- maxabs SYNOPSIS Get the maximum absolute value of an array USAGE result = maxabs (Array_Type a [,Int_Type dim]) DESCRIPTION The `maxabs' function behaves like the `max' function except that it returns the maximum absolute value of the array. That is, `maxabs(x)' is equivalent to `max(abs(x)'. See the documentation for the `max' function for more information. SEE ALSO min, max, minabs -------------------------------------------------------------- min SYNOPSIS Get the minimum value of an array USAGE result = min (Array_Type a [,Int_Type dim]) DESCRIPTION The `min' function examines the elements of a numeric array and returns the value of the smallest element. If a second argument is given, then it specifies the dimension of the array to be searched. In this case, an array of dimension one less than that of the input array will be returned with the corresponding elements in the specified dimension replaced by the minimum value in that dimension. EXAMPLE Consider the 2-d array 1 2 3 4 5 6 7 8 9 10 generated by a = _reshape ([1:10], [2, 5]); Then `min(a)' will return `1', and `min(a,0)' will return a 1-d array with elements 1 2 3 4 5 NOTES This function ignores NaNs in the input array. SEE ALSO max, sum, reshape -------------------------------------------------------------- minabs SYNOPSIS Get the minimum absolute value of an array USAGE result = minabs (Array_Type a [,Int_Type dim]) DESCRIPTION The `minabs' function behaves like the `min' function except that it returns the minimum absolute value of the array. That is, `minabs(x)' is equivalent to `min(abs(x)'. See the documentation for the `min' function for more information. SEE ALSO min, max, maxabs -------------------------------------------------------------- _reshape SYNOPSIS Copy an array to a new shape USAGE Array_Type _reshape (Array_Type A, Array_Type I) DESCRIPTION The `_reshape' function creates a copy of an array `A', reshapes it to the form specified by `I' and returns the result. The elements of `I' specify the new dimensions of the copy of `A' and must be consistent with the number of elements `A'. EXAMPLE If `A' is a `100' element 1-d array, a new 2-d array of size `20' by `5' may be created from the elements of `A' by B = _reshape (A, [20, 5]); NOTES The `reshape' function performs a similar function to `_reshape'. In fact, the `_reshape' function could have been implemented via: define _reshape (a, i) { a = @a; % Make a new copy reshape (a, i); return a; } SEE ALSO reshape, array_shape, array_info -------------------------------------------------------------- reshape SYNOPSIS Reshape an array USAGE reshape (Array_Type A, Array_Type I) DESCRIPTION The `reshape' function changes the shape of `A' to have the shape specified by the 1-d integer array `I'. The elements of `I' specify the new dimensions of `A' and must be consistent with the number of elements `A'. EXAMPLE If `A' is a `100' element 1-d array, it can be changed to a 2-d `20' by `5' array via reshape (A, [20, 5]); However, `reshape(A, [11,5])' will result in an error because the `[11,5]' array specifies `55' elements. NOTES Since `reshape' modifies the shape of an array, and arrays are treated as references, then all references to the array will reference the new shape. If this effect is unwanted, then use the `_reshape' function instead. SEE ALSO _reshape, array_info, array_shape -------------------------------------------------------------- sum SYNOPSIS Sum over the elements of an array USAGE result = sum (Array_Type a [, Int_Type dim]) DESCRIPTION The `sum' function sums over the elements of a numeric array and returns its result. If a second argument is given, then it specifies the dimension of the array to be summed over. In this case, an array of dimension one less than that of the input array will be returned. If the input array is an integer type, then the resulting value will be a Double_Type. If the input array is a Float_Type, then the result will be a Float_Type. EXAMPLE The mean of an array `a' of numbers is sum(a)/length(a) SEE ALSO cumsum, sumsq, transpose, reshape -------------------------------------------------------------- sumsq SYNOPSIS Sum over the squares of the elements of an array USAGE result = sumsq (Array_Type a [, Int_Type dim]) DESCRIPTION The `sumsq' function sums over the squares of the elements of a numeric array and returns its result. If a second argument is given, then it specifies the dimension of the array to be summed over. In this case, an array of dimension one less than that of the input array will be returned. If the input array is an integer type, then the resulting value will be a Double_Type. If the input array is a Float_Type, then the result will be a Float_Type. For complex arrays, the sum will be over the squares of the moduli of the complex elements. SEE ALSO cumsum, sumsq, hypot, transpose, reshape -------------------------------------------------------------- transpose SYNOPSIS Transpose an array USAGE Array_Type transpose (Array_Type a) DESCRIPTION The `transpose' function returns the transpose of a specified array. By definition, the transpose of an array, say one with elements `a[i,j,...k]' is an array whose elements are `a[k,...,j,i]'. SEE ALSO _reshape, reshape, sum, array_info, array_shape -------------------------------------------------------------- where USAGE Array_Type where (Array_Type a [, Ref_Type jp]) DESCRIPTION The `where' function examines a numeric array `a' and returns an integer array giving the indices of `a' where the corresponding element of `a' is non-zero. The function accepts an optional Ref_Type argument that will be set to complement set of indices, that is, the indices where `a' is zero. In fact i = where (a); j = where (not a); and i = where (a, &j); are equivalent, but the latter form is prefered since it executes about twice as fast as the former. Although this function may appear to be simple or even trivial, it is arguably one of the most important and powerful functions for manipulating arrays. EXAMPLE Consider the following: variable X = [0.0:10.0:0.01]; variable A = sin (X); variable I = where (A < 0.0); A[I] = cos (X) [I]; Here the variable `X' has been assigned an array of doubles whose elements range from `0.0' through `10.0' in increments of `0.01'. The second statement assigns `A' to an array whose elements are the `sin' of the elements of `X'. The third statement uses the `where' function to get the indices of the elements of `A' that are less than 0. Finally, the last statement replaces those elements of `A' by the cosine of the corresponding elements of `X'. NOTES Support for the optional argument was added to version 2.1.0. SEE ALSO wherefirst, wherelast, wherenot, array_info, array_shape, _isnull -------------------------------------------------------------- wherenot SYNOPSIS Get indices where a numeric array is 0 USAGE Array_Type wherenot (Array_Type) DESCRIPTION This function is equivalent to `where(not a)'. See the documentation for `where' for more information. SEE ALSO where, wherefirst, wherelast -------------------------------------------------------------- wherefirst SYNOPSIS Get the index of the first non-zero array element USAGE Int_Type wherefirst (Array_Type a [,start_index]) DESCRIPTION The `wherefirst' function returns the index of the first non-zero element of a specified array. If the optional parameter `start_index' is given, the search will take place starting from that index. If a non-zero element is not found, the function will return NULL. NOTES The single parameter version of this function is equivalent to define wherefirst (a) { variable i = where (a); if (length(i)) return i[0]; else return NULL; } SEE ALSO where, wherelast -------------------------------------------------------------- wherelast SYNOPSIS Get the index of the last non-zero array element USAGE Int_Type wherelast (Array_Type a [,start_index]) DESCRIPTION The `wherelast' function returns the index of the last non-zero element of a specified array. If the optional parameter `start_index' is given, the backward search will take place starting from that index. If a non-zero element is not found, the function will return NULL. NOTES The single parameter version of this function is equivalent to define wherefirst (a) { variable i = where (a); if (length(i)) return i[-1]; else return NULL; } SEE ALSO where, wherefirst -------------------------------------------------------------- assoc_delete_key SYNOPSIS Delete a key from an Associative Array USAGE assoc_delete_key (Assoc_Type a, String_Type k) DESCRIPTION The `assoc_delete_key' function deletes a key given by `k' from the associative array `a'. If the specified key does not exist in `a', then this function has no effect. SEE ALSO assoc_key_exists, assoc_get_keys -------------------------------------------------------------- assoc_get_keys SYNOPSIS Return all the key names of an Associative Array USAGE String_Type[] assoc_get_keys (Assoc_Type a) DESCRIPTION This function returns all the key names of an associative array `a' as an ordinary one dimensional array of strings. If the associative array contains no keys, an empty array will be returned. SEE ALSO assoc_get_values, assoc_key_exists, assoc_delete_key, length -------------------------------------------------------------- assoc_get_values SYNOPSIS Return all the values of an Associative Array USAGE Array_Type assoc_get_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 v = assoc_get_values (a); variable 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 bytes 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 s = "hello\0"; len = bstrlen (s); % ==> len = 6 len = strlen (s); % ==> len = 5 SEE ALSO strlen, length -------------------------------------------------------------- count_byte_occurances SYNOPSIS Count the number of occurances of a byte in a binary string USAGE UInt_Type count_byte_occurances (bstring, byte) DESCRIPTION This function returns the number of times the specified byte occurs in the binary string `bstr'. NOTES This function uses byte-semanics. If character semantics are desired, use the `count_char_occurances' function. SEE ALSO count_char_occurances -------------------------------------------------------------- pack SYNOPSIS Pack objects into a binary string USAGE BString_Type pack (String_Type fmt, ...) DESCRIPTION The `pack' function combines zero or more objects (represented by the ellipses above) into a binary string according to the format string `fmt'. The format string consists of one or more data-type specification characters defined by the following table: c signed byte C unsigned byte h short H unsigned short i int I unsigned int l long L unsigned long m long long M unsigned long long j 16 bit int J 16 bit unsigned int k 32 bit int K 32 bit unsigned int q 64 bit int Q 64 bit unsigned int f float d double F 32 bit float D 64 bit float s character string, null padded S character string, space padded z character string, null padded x a null pad character A decimal length specifier may follow the data-type specifier. With the exception of the `s' and `S' specifiers, the length specifier indicates how many objects of that data type are to be packed or unpacked from the string. When used with the `s', `S', or `z' specifiers, it indicates the field width to be used. If the length specifier is not present, the length defaults to one. When packing, unlike the `s' specifier, the `z' specifier guarantees that at least one null byte will be written even if the field has to be truncated to do so. With the exception of `c', `C', `s', `S', and `x', each of these may be prefixed by a character that indicates the byte-order of the object: > big-endian order (network order) < little-endian order = native byte-order The default is to use native byte order. When unpacking via the `unpack' function, if the length specifier is greater than one, then an array of that length will be returned. In addition, trailing whitespace and null characters are stripped when unpacking an object given by the `S' specifier. Trailing null characters will be stripped from an object represented by the `z' specifier. No such stripping is performed by the `s' specifier. EXAMPLE a = pack ("cc", 'A', 'B'); % ==> a = "AB"; a = pack ("c2", 'A', 'B'); % ==> a = "AB"; a = pack ("xxcxxc", 'A', 'B'); % ==> a = "\0\0A\0\0B"; a = pack ("h2", 'A', 'B'); % ==> a = "\0A\0B" or "\0B\0A" a = pack (">h2", 'A', 'B'); % ==> a = "\0\xA\0\xB" a = pack ("<h2", 'A', 'B'); % ==> a = "\0B\0A" a = pack ("s4", "AB", "CD"); % ==> a = "AB\0\0" a = pack ("s4s2", "AB", "CD"); % ==> a = "AB\0\0CD" a = pack ("S4", "AB", "CD"); % ==> a = "AB " a = pack ("S4S2", "AB", "CD"); % ==> a = "AB CD" a = pack ("z4", "AB"); % ==> a = "AB\0\0" a = pack ("s4", "ABCDEFG"); % ==> a = "ABCD" a = pack ("z4", "ABCDEFG"); % ==> a = "ABC\0" SEE ALSO unpack, sizeof_pack, pad_pack_format, sprintf -------------------------------------------------------------- pad_pack_format SYNOPSIS Add padding to a pack format USAGE BString_Type pad_pack_format (String_Type fmt) DESCRIPTION The `pad_pack_format' function may be used to add the appropriate padding characters to the format `fmt' such that the data types specified by the format will be properly aligned on word boundaries. This is especially important when reading or writing files that assume the native alignment. SEE ALSO pack, unpack, sizeof_pack -------------------------------------------------------------- sizeof_pack SYNOPSIS Compute the size implied by a pack format string USAGE UInt_Type sizeof_pack (String_Type fmt) DESCRIPTION The `sizeof_pack' function returns the size of the binary string represented by the format string `fmt'. This information may be needed when reading a structure from a file. SEE ALSO pack, unpack, pad_pack_format -------------------------------------------------------------- unpack SYNOPSIS Unpack Objects from a Binary String USAGE (...) = unpack (String_Type fmt, BString_Type s) DESCRIPTION The `unpack' function unpacks objects from a binary string `s' according to the format `fmt' and returns the objects to the stack in the order in which they were unpacked. See the documentation of the `pack' function for details about the format string. EXAMPLE (x,y) = unpack ("cc", "AB"); % ==> x = 'A', y = 'B' x = unpack ("c2", "AB"); % ==> x = ['A', 'B'] x = unpack ("x<H", "\0\xAB\xCD"); % ==> x = 0xCDABuh x = unpack ("xxs4", "a b c\0d e f"); % ==> x = "b c\0" x = unpack ("xxS4", "a b c\0d e f"); % ==> x = "b c" SEE ALSO pack, sizeof_pack, pad_pack_format -------------------------------------------------------------- Assoc_Type SYNOPSIS An associative array or hash type DESCRIPTION An Assoc_Type object is like an array except that it is indexed using strings and not integers. Unlike an Array_Type object, the size of an associative array is not fixed, but grows as objects are added to the array. Another difference is that ordinary arrays represent ordered object; however, the ordering of the elements of an `Assoc_Type' object is unspecified. An Assoc_Type object whose elements are of some data-type `d' may be created using using A = Assoc_Type[d]; For example, A = Assoc_Type[Int_Type]; will create an associative array of integers. To create an associative array capable of storing an arbitrary type, use the form A = Assoc_Type[]; An optional parameter may be used to specify a default value for array elements. For example, A = Assoc_Type[Int_Type, -1]; creates an integer-valued associative array with a default element value of -1. Then `A["foo"]' will return -1 if the key `"foo"' does not exist in the array. Default values are available only if the type was specified when the associative array was created. The following functions may be used with associative arrays: assoc_get_keys assoc_get_values assoc_key_exists assoc_delete_key The `length' function may be used to obtain the number of elements in the array. The `foreach' construct may be used with associative arrays via one of the following forms: foreach k,v (A) {...} foreach k (A) using ("keys") { ... } foreach v (A) using ("values") { ... } foreach k,v (A) using ("keys", "values") { ... } In all the above forms, the loop is over all elements of the array such that `v=A[k]'. SEE ALSO List_Type, Array_Type, Struct_Type -------------------------------------------------------------- List_Type SYNOPSIS A list object DESCRIPTION An object of type `List_Type' represents a list, which is defined as an ordered heterogeneous collection of objects. A list may be created using, e.g., empty_list = {}; list_with_4_items = {[1:10], "three", 9, {1,2,3}}; Note that the last item of the list in the last example is also a list. A List_Type object may be manipulated by the following functions: list_new list_insert list_append list_delete list_reverse list_pop A `List_Type' object may be indexed using an array syntax with the first item on the list given by an index of 0. The `length' function may be used to obtain the number of elements in the list. A copy of the list may be created using the @ operator, e.g., `copy = @list'. The `foreach' statement may be used with a List_Type object to loop over its elements: foreach elem (list) {....} SEE ALSO Array_Type, Assoc_Type, Struct_Type -------------------------------------------------------------- String_Type SYNOPSIS A string object DESCRIPTION An object of type `String_Type' represents a string of bytes or characters, which in general have different semantics depending upon the UTF-8 mode. The string obeys byte-semantics when indexed as an array. That is, `S[0]' will return the first byte of the string `S'. For character semantics, the nth character in the string may be obtained using `substr' function. The `foreach' statement may be used with a String_Type object `S' to loop over its bytes: foreach b (S) {....} foreach b (S) using ("bytes") {....} To loop over its characters, the following form may be used: foreach c (S) using ("chars") {...} When UTF-8 mode is not in effect, the byte and character forms will produce the same sequence. Otherwise, the string will be decoded to generate the (wide) character sequence. If the string contains an invalid UTF-8 encoded character, sucessive bytes of the invalid sequence will be returned as negative integers. For example, `"a\xAB\x{AB}"' specifies a string composed of the character `a', a byte `0xAB', and the character `0xAB'. In this case, foreach c ("a\xAB\x{AB}") {...} will produce the integer-valued sequence `'a', -0xAB, 0xAB'. SEE ALSO Array_Type, _slang_utf8_ok -------------------------------------------------------------- Struct_Type SYNOPSIS A structure datatype DESCRIPTION A Struct_Type object with fields `f1', `f2',..., `fN' may be created using s = struct { f1, f2, ..., fN }; The fields may be accessed via the "dot" operator, e.g., s.f1 = 3; if (s12.f1 == 4) s.f1++; By default, all fields will be initialized to NULL. A structure may also be created using the dereference operator (@): s = @Struct_Type ("f1", "f2", ..., "fN"); s = @Struct_Type ( ["f1", "f2", ..., "fN"] ); Functions for manipulating structure fields include: _push_struct_field_values get_struct_field get_struct_field_names set_struct_field set_struct_fields The `foreach' loop may be used to loop over elements of a linked list. Suppose that first structure in the list is called `root', and that the `child' field is used to form the chain. Then one may walk the list using: foreach s (root) using ("child") { % s will take on successive values in the list . . } The loop will terminate when the last elements `child' field is NULL. If no ``linking'' field is specified, the field name will default to `next'. User-defined data types are similar to the `Struct_Type'. A type, e.g., `Vector_Type' may be created using: typedef struct { x, y, z } Vector_Type; Objects of this type may be created via the @ operator, e.g., v = @Vector_Type; It is recommended that this be used in a function for creating such types, e.g., define vector (x, y, z) { variable v = @Vector_Type; v.x = x; v.y = y; v.z = z; return v; } The action of the binary and unary operators may be defined for such types. Consider the "+" operator. First define a function for adding two `Vector_Type' objects: static define vector_add (v1, v2) { return vector (v1.x+v2.x, v1.y+v2.y, v1.z, v2.z); } Then use __add_binary ("+", Vector_Type, &vector_add, Vector_Type, Vector_Type); to indicate that the function is to be called whenever the "+" binary operation between two `Vector_Type' objects takes place, e.g., V1 = vector (1, 2, 3); V2 = vector (8, 9, 1); V3 = V1 + V2; will assigned the vector (9, 11, 4) to `V3'. Similarly, the `"*"' operator between scalars and vectors may be defined using: static define vector_scalar_mul (v, a) { return vector (a*v.x, a*v.y, a*v.z); } static define scalar_vector_mul (a, v) { return vector_scalar_mul (v, a); } __add_binary ("*", Vector_Type, &scalar_vector_mul, Any_Type, Vector_Type); __add_binary ("*", Vector_Type, &vector_scalar_mul, Vector_Type, Any_Type); Related functions include: __add_unary __add_string __add_destroy SEE ALSO List_Type, Assoc_Type -------------------------------------------------------------- File_Type SYNOPSIS A type representing a C stdio object DESCRIPTION An File_Type is the interpreter's representation of a C stdio FILE object and is usually created using the `fopen' function, i.e., fp = fopen ("file.dat", "r"); Functions that utilize the File_Type include: fopen fclose fgets fputs ferror feof fflush fprintf fseek ftell fread fwrite fread_bytes The `foreach' construct may be used with File_Type objects via one of the following forms: foreach line (fp) {...} foreach byte (A) using ("char") { ... } % read bytes foreach line (A) using ("line") { ... } % read lines (default) foreach line (A) using ("wsline") { ... } % whitespace stripped from lines SEE ALSO List_Type, Array_Type, Struct_Type -------------------------------------------------------------- _bofeof_info SYNOPSIS Control the generation of function callback code USAGE Int_Type _bofeof_info DESCRIPTION This value of this variable dictates whether or not the S-Lang interpeter will generate code to call the beginning and end of function callback handlers. The value of this variable is local to the compilation unit, but is inherited by other units loaded by the current unit. If the value of this variable is 1 when a function is defined, then when the function is executed, the callback handlers defined via `_set_bof_handler' and `_set_eof_handler' will be called. SEE ALSO _set_bof_handler, _set_eof_handler, _boseos_info -------------------------------------------------------------- _boseos_info SYNOPSIS Control the generation of BOS/EOS callback code USAGE Int_Type _boseos_info DESCRIPTION This value of this variable dictates whether or not the S-Lang interpeter will generate code to call the beginning and end of statement callback handlers. The value of this variable is local to the compilation unit, but is inherited by other units loaded by the current unit. The value of `_boseos_info' controls the generation of code for callbacks as follows: Value Description ----------------------------------------------------------------- 0 No code for making callbacks will be produced. 1 Callback generation will take place for all non-branching and looping statements. 2 Same as for 1 with the addition that code will also be generated for branching statements (if, !if, loop, ...) 3 Same as 2, but also including break and continue statements. A non-branching statement is one that does not effect chain of execution. Branching statements include all looping statements, conditional statement, `break', `continue', and `return'. EXAMPLE Consider the following: _boseos_info = 1; define foo () { if (some_expression) some_statement; } _boseos_info = 2; define bar () { if (some_expression) some_statement; } The function `foo' will be compiled with code generated to call the BOS and EOS handlers when `some_statement' is executed. The function `bar' will be compiled with code to call the handlers for both `some_expression' and `some_statement'. NOTES The `sldb' debugger and `slsh''s `stkcheck.sl' make use of this facility. SEE ALSO _set_bos_handler, _set_eos_handler, _bofeof_info -------------------------------------------------------------- _clear_error SYNOPSIS Clear an error condition (deprecated) USAGE _clear_error () DESCRIPTION This function has been deprecated. New code should make use of try-catch exception handling. This function may be used in error-blocks to clear the error that triggered execution of the error block. Execution resumes following the statement, in the scope of the error-block, that triggered the error. EXAMPLE Consider the following wrapper around the `putenv' function: define try_putenv (name, value) { variable status; ERROR_BLOCK { _clear_error (); status = -1; } status = 0; putenv (sprintf ("%s=%s", name, value); return status; } If `putenv' fails, it generates an error condition, which the `try_putenv' function catches and clears. Thus `try_putenv' is a function that returns -1 upon failure and 0 upon success. SEE ALSO _trace_function, _slangtrace, _traceback -------------------------------------------------------------- _set_bof_handler SYNOPSIS Set the beginning of function callback handler USAGE _set_bof_handler (Ref_Type func) DESCRIPTION This function is used to set the function to be called prior to the execution of the body S-Lang function but after its arguments have been evaluated, provided that function was defined with `_bofeof_info' set appropriately. The callback function must be defined to take a single parameter representing the name of the function and must return nothing. EXAMPLE private define bof_handler (fun) { () = fputs ("About to execute $fun"$, stdout); } _set_bos_handler (&bof_handler); NOTES SEE ALSO _set_eof_handler, _boseos_info, _set_bos_handler -------------------------------------------------------------- _set_bos_handler SYNOPSIS Set the beginning of statement callback handler USAGE _set_bos_handler (Ref_Type func) DESCRIPTION This function is used to set the function to be called prior to the beginning of a statement. The function will be passed two parameters: the name of the file and the line number of the statement to be executed. It should return nothing. EXAMPLE private define bos_handler (file, line) { () = fputs ("About to execute $file:$line\n"$, stdout); } _set_bos_handler (&bos_handler); NOTES The beginning and end of statement handlers will be called for statements in a file only if that file was compiled with the variable `_boseos_info' set to a non-zero value. SEE ALSO _set_eos_handler, _boseos_info, _bofeof_info -------------------------------------------------------------- _set_eof_handler SYNOPSIS Set the beginning of function callback handler USAGE _set_eof_handler (Ref_Type func) DESCRIPTION This function is used to set the function to be called at the end of execution of a S-Lang function, provided that function was compiled with `_bofeof_info' set accordingly. The callback function will be passed no parameters and it must return nothing. EXAMPLE private define eof_handler () { () = fputs ("Done executing the function\n", stdout); } _set_eof_handler (&eof_handler); SEE ALSO _set_bof_handler, _bofeof_info, _boseos_info -------------------------------------------------------------- _set_eos_handler SYNOPSIS Set the end of statement callback handler USAGE _set_eos_handler (Ref_Type func) DESCRIPTION This function is used to set the function to be called at the end of a statement. The function will be passed no parameters and it should return nothing. EXAMPLE private define eos_handler () { () = fputs ("Done executing the statement\n", stdout); } _set_eos_handler (&eos_handler); NOTES The beginning and end of statement handlers will be called for statements in a file only if that file was compiled with the variable `_boseos_info' set to a non-zero value. SEE ALSO _set_bos_handler, _boseos_info, _bofeof_info -------------------------------------------------------------- _slangtrace SYNOPSIS Turn function tracing on or off USAGE Integer_Type _slangtrace DESCRIPTION The `_slangtrace' variable is a debugging aid that when set to a non-zero value enables tracing when function declared by `_trace_function' is entered. If the value is greater than zero, both intrinsic and user defined functions will get traced. However, if set to a value less than zero, intrinsic functions will not get traced. SEE ALSO _trace_function, _traceback, _print_stack -------------------------------------------------------------- _traceback SYNOPSIS Generate a traceback upon error USAGE Integer_Type _traceback DESCRIPTION `_traceback' is an intrinsic integer variable whose bitmapped value controls the generation of the call-stack traceback upon error. When set to 0, no traceback will be generated. Otherwise its value is the bitwise-or of the following integers: 1 Create a full traceback 2 Omit local variable information 4 Generate just one line of traceback The default value of this variable is 4. NOTES Running `slsh' with the `-g' option causes this variable to be set to 1. SEE ALSO _boseos_info -------------------------------------------------------------- _trace_function SYNOPSIS Set the function to trace USAGE _trace_function (String_Type f) DESCRIPTION `_trace_function' declares that the S-Lang function with name `f' is to be traced when it is called. Calling `_trace_function' does not in itself turn tracing on. Tracing is turned on only when the variable `_slangtrace' is non-zero. SEE ALSO _slangtrace, _traceback -------------------------------------------------------------- _get_frame_info SYNOPSIS Get information about a stack frame USAGE Struct_Type _get_frame_info (Integer_Type depth) DESCRIPTION `_get_frame_info' returns a structure with information about the function call stack from of depth `depth'. The structure contains the following fields: file: The file that contains the code of the stack frame. line: The line number the file the stack frame is in. function: the name of the function containing the code of the stack frame; it might be NULL if the code isn't inside a function. locals: Array of String_Type containing the names of variables local to the stack frame; it might be NULL if the stack frame doesn't belong to a function. namespace: The namespace the code of this stack frame is in. SEE ALSO _get_frame_variable, _use_frame_namespace -------------------------------------------------------------- _get_frame_variable SYNOPSIS Get the value of a variable local to a stack frame USAGE Any_Type _get_frame_variable (Integer_Type depth, String_Type name) DESCRIPTION This function returns value of the variable `name' in the stack frame at depth `depth'. This might not only be a local variable but also variables from outer scopes, e.g., a variable private to the namespace. If no variable with this name is found an `UndefinedNameError' will be thrown. An `VariableUninitializedError' will be generated if the variable has no value. SEE ALSO _get_frame_info, _use_frame_namespace -------------------------------------------------------------- _use_frame_namespace SYNOPSIS Selects the namespace of a stack frame USAGE _use_frame_namespace (Integer_Type depth) DESCRIPTION This function sets the current namespace to the one belonging to the call stack frame at depth `depth'. SEE ALSO _get_frame_info, _get_frame_variable -------------------------------------------------------------- access SYNOPSIS Check to see if a file is accessable USAGE Int_Type access (String_Type pathname, Int_Type mode) DESCRIPTION This functions checks to see if the current process has access to the specified pathname. The `mode' parameter determines the type of desired access. Its value is given by the bitwise-or of one or more of the following constants: R_OK Check for read permission W_OK Check for write permission X_OK Check for execute permission F_OK Check for existence The function will return 0 if process has the requested access permissions to the file, otherwise it will return -1 and set `errno' accordingly. Access to a file depend not only upon the file itself, but also upon the permissions of each of the directories in the pathname. The checks are done using the real user and group ids of the process, and not using the effective ids. SEE ALSO stat_file -------------------------------------------------------------- chdir SYNOPSIS Change the current working directory USAGE Int_Type chdir (String_Type dir) DESCRIPTION The `chdir' function may be used to change the current working directory to the directory specified by `dir'. Upon success it returns zero. Upon failure it returns `-1' and sets `errno' accordingly. SEE ALSO mkdir, stat_file -------------------------------------------------------------- chmod SYNOPSIS Change the mode of a file USAGE Int_Type chmod (String_Type file, Int_Type mode) DESCRIPTION The `chmod' function changes the permissions of the specified file to those given by `mode'. It returns `0' upon success, or `-1' upon failure setting `errno' accordingly. See the system specific documentation for the C library function `chmod' for a discussion of the `mode' parameter. SEE ALSO chown, stat_file -------------------------------------------------------------- chown SYNOPSIS Change the owner of a file USAGE Int_Type chown (String_Type file, Int_Type uid, Int_Type gid) DESCRIPTION The `chown' function is used to change the user-id and group-id of `file' to `uid' and `gid', respectively. It returns 0 upon success and -1 upon failure, with `errno' set accordingly. NOTES On most systems, only the superuser can change the ownership of a file. Some systems do not support this function. SEE ALSO chmod, stat_file -------------------------------------------------------------- getcwd SYNOPSIS Get the current working directory USAGE String_Type getcwd () DESCRIPTION The `getcwd' function returns the absolute pathname of the current working directory. If an error occurs or it cannot determine the working directory, it returns NULL and sets `errno' accordingly. NOTES Under Unix, OS/2, and MSDOS, the pathname returned by this function includes the trailing slash character. It may also include the drive specifier for systems where that is meaningful. SEE ALSO mkdir, chdir, errno -------------------------------------------------------------- hardlink SYNOPSIS Create a hard-link USAGE Int_Type hardlink (String_Type oldpath, String_Type newpath) DESCRIPTION The `hardlink' function creates a hard-link called `newpath' to the existing file `oldpath'. If the link was sucessfully created, the function will return 0. Upon error, the function returns -1 and sets `errno' accordingly. NOTES Not all systems support the concept of a hard-link. SEE ALSO symlink -------------------------------------------------------------- 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 Int_Type mkdir (String_Type dir [,Int_Type mode]) DESCRIPTION The `mkdir' function creates a directory whose name is specified by the `dir' parameter with permissions given by the optional `mode' parameter. Upon success `mkdir' returns 0, or it returns `-1' upon failure setting `errno' accordingly. In particular, if the directory already exists, the function will fail and set errno to EEXIST. EXAMPLE define my_mkdir (dir) { if (0 == mkdir (dir)) return; if (errno == EEXIST) return; throw IOError, sprintf ("mkdir %s failed: %s", dir, errno_string (errno)); } NOTES The `mode' parameter may not be meaningful on all systems. On systems where it is meaningful, the actual permissions on the newly created directory are modified by the process's umask. SEE ALSO rmdir, getcwd, chdir, fopen, errno -------------------------------------------------------------- readlink SYNOPSIS String_Type readlink (String_Type path) USAGE Get the value of a symbolic link DESCRIPTION The `readlink' function returns the value of a symbolic link. Upon failure, NULL is returned and `errno' set accordingly. NOTES Not all systems support this function. SEE ALSO symlink, lstat_file, stat_file, stat_is -------------------------------------------------------------- remove SYNOPSIS Delete a file USAGE Int_Type remove (String_Type file) DESCRIPTION The `remove' function deletes a file. It returns 0 upon success, or -1 upon error and sets `errno' accordingly. SEE ALSO rename, rmdir -------------------------------------------------------------- rename SYNOPSIS Rename a file USAGE Int_Type rename (String_Type old, String_Type new) DESCRIPTION The `rename' function renames a file from `old' to `new' moving it between directories if necessary. This function may fail if the directories are not on the same file system. It returns 0 upon success, or -1 upon error and sets `errno' accordingly. SEE ALSO remove, errno -------------------------------------------------------------- rmdir SYNOPSIS Remove a directory USAGE Int_Type rmdir (String_Type dir) DESCRIPTION The `rmdir' function deletes the specified directory. It returns 0 upon success or -1 upon error and sets `errno' accordingly. NOTES The directory must be empty before it can be removed. SEE ALSO rename, remove, mkdir -------------------------------------------------------------- stat_file SYNOPSIS Get information about a file USAGE Struct_Type stat_file (String_Type file) DESCRIPTION The `stat_file' function returns information about `file' through the use of the system `stat' call. If the stat call fails, the function returns NULL and sets errno accordingly. If it is successful, it returns a stat structure with the following integer-value fields: st_dev st_ino st_mode st_nlink st_uid st_gid st_rdev st_size st_atime st_mtime st_ctime See the C library documentation of `stat' for a discussion of the meanings of these fields. EXAMPLE The following example shows how the `stat_file' function may be used to get the size of a file: define file_size (file) { variable st; st = stat_file(file); if (st == NULL) throw IOError, "Unable to stat $file"$; return st.st_size; } SEE ALSO lstat_file, stat_is -------------------------------------------------------------- stat_is SYNOPSIS Parse the st_mode field of a stat structure USAGE Char_Type stat_is (String_Type type, Int_Type st_mode) DESCRIPTION The `stat_is' function returns a boolean value according to whether or not the `st_mode' parameter is of the specified type. Specifically, `type' must be one of the strings: "sock" (socket) "fifo" (fifo) "blk" (block device) "chr" (character device) "reg" (regular file) "lnk" (link) "dir" (dir) It returns a non-zero value if `st_mode' corresponds to `type'. EXAMPLE The following example illustrates how to use the `stat_is' function to determine whether or not a file is a directory: define is_directory (file) { variable st; st = stat_file (file); if (st == NULL) return 0; return stat_is ("dir", st.st_mode); } SEE ALSO stat_file, lstat_file -------------------------------------------------------------- symlink SYNOPSIS Create a symbolic link USAGE status = symlink (String_Type oldpath, String_Type new_path) DESCRIPTION The `symlink' function may be used to create a symbolic link named `new_path' for `oldpath'. If successful, the function returns 0, otherwise it returns -1 and sets `errno' appropriately. NOTES This function is not supported on all systems and even if supported, not all file systems support the concept of a symbolic link. SEE ALSO readlink, hardlink -------------------------------------------------------------- _$ SYNOPSIS Expand the dollar-escaped variables in a string USAGE String_Type _$(String_Type s) DESCRIPTION This function expands the dollar-escaped variables in a string and returns the resulting string. EXAMPLE Consider the following code fragment: private variable Format = "/tmp/foo-$time.$pid"; define make_filename () { variable pid = getpid (); variable time = _time (); return _$(Format); } Note that the variable `Format' contains dollar-escaped variables, but because the `$' suffix was omitted from the string literal, the variables are not expanded. Instead expansion is deferred until execution of the `make_filename' function through the use of the `_$' function. SEE ALSO eval, getenv -------------------------------------------------------------- autoload SYNOPSIS Load a function from a file USAGE autoload (String_Type funct, String_Type file) DESCRIPTION The `autoload' function is used to declare `funct' to the interpreter and indicate that it should be loaded from `file' when it is actually used. If `func' contains a namespace prefix, then the file will be loaded into the corresponding namespace. Otherwise, if the `autoload' function is called from an execution namespace that is not the Global namespace nor an anonymous namespace, then the file will be loaded into the execution namespace. EXAMPLE Suppose `bessel_j0' is a function defined in the file `bessel.sl'. Then the statement autoload ("bessel_j0", "bessel.sl"); will cause `bessel.sl' to be loaded prior to the execution of `bessel_j0'. SEE ALSO evalfile, import -------------------------------------------------------------- byte_compile_file SYNOPSIS Compile a file to byte-code for faster loading. USAGE byte_compile_file (String_Type file, Int_Type method) DESCRIPTION The `byte_compile_file' function byte-compiles `file' producing a new file with the same name except a `'c'' is added to the output file name. For example, `file' is `"site.sl"', then this function produces a new file named `site.slc'. NOTES The `method' parameter is not used in the current implementation, but may be in the future. For now, set it to `0'. SEE ALSO evalfile -------------------------------------------------------------- eval SYNOPSIS Interpret a string as S-Lang code USAGE eval (String_Type expression [,String_Type namespace]) DESCRIPTION The `eval' function parses a string as S-Lang code and executes the result. If called with the optional namespace argument, then the string will be evaluated in the specified namespace. If that namespace does not exist it will be created first. This is a useful function in many contexts including those where it is necessary to dynamically generate function definitions. EXAMPLE if (0 == is_defined ("my_function")) eval ("define my_function () { message (\"my_function\"); }"); SEE ALSO is_defined, autoload, evalfile -------------------------------------------------------------- evalfile SYNOPSIS Interpret a file containing S-Lang code USAGE Int_Type evalfile (String_Type file [,String_Type namespace]) DESCRIPTION The `evalfile' function loads `file' into the interpreter and executes it. If called with the optional namespace argument, the file will be loaded into the specified namespace, which will be created if necessary. If given no namespace argument and the file has already been loaded, then it will be loaded again into an anonymous namespace. A namespace argument given by the empty string will also cause the file to be loaded into a new anonymous namespace. If no errors were encountered, 1 will be returned; otherwise, a S-Lang exception will be thrown and the function will return zero. EXAMPLE define load_file (file) { try { () = evalfile (file); } catch AnyError; } NOTES For historical reasons, the return value of this function is not really useful. The file is searched along an application-defined load-path. The `get_slang_load_path' and `set_slang_load_path' functions may be used to set and query the path. SEE ALSO eval, autoload, set_slang_load_path, get_slang_load_path -------------------------------------------------------------- get_slang_load_path SYNOPSIS Get the value of the interpreter's load-path USAGE String_Type get_slang_load_path () DESCRIPTION This function retrieves the value of the delimiter-separated search path used for loading files. The delimiter is OS-specific and may be queried using the `path_get_delimiter' function. NOTES Some applications may not support the built-in load-path searching facility provided by the underlying library. SEE ALSO set_slang_load_path, path_get_delimiter -------------------------------------------------------------- set_slang_load_path SYNOPSIS Set the value of the interpreter's load-path USAGE set_slang_load_path (String_Type path) DESCRIPTION This function may be used to set the value of the delimiter-separated search path used by the `evalfile' and `autoload' functions for locating files. The delimiter is OS-specific and may be queried using the `path_get_delimiter' function. EXAMPLE public define prepend_to_slang_load_path (p) { variable s = stat_file (p); if (s == NULL) return; if (0 == stat_is ("dir", s.st_mode)) return; p = sprintf ("%s%c%s", p, path_get_delimiter (), get_slang_load_path ()); set_slang_load_path (p); } NOTES Some applications may not support the built-in load-path searching facility provided by the underlying library. SEE ALSO get_slang_load_path, path_get_delimiter, evalfile, autoload -------------------------------------------------------------- get_import_module_path SYNOPSIS Get the search path for dynamically loadable objects USAGE String_Type get_import_module_path () DESCRIPTION The `get_import_module_path' may be used to get the search path for dynamically shared objects. Such objects may be made accessible to the application via the `import' function. SEE ALSO import, set_import_module_path -------------------------------------------------------------- import SYNOPSIS Dynamically link to a specified module USAGE import (String_Type module [, String_Type namespace]) DESCRIPTION The `import' function causes the run-time linker to dynamically link to the shared object specified by the `module' parameter. It searches for the shared object as follows: First a search is performed along all module paths specified by the application. Then a search is made along the paths defined via the `set_import_module_path' function. If not found, a search is performed along the paths given by the `SLANG_MODULE_PATH' environment variable. Finally, a system dependent search is performed (e.g., using the `LD_LIBRARY_PATH' environment variable). The optional second parameter may be used to specify a namespace for the intrinsic functions and variables of the module. If this parameter is not present, the intrinsic objects will be placed into the active namespace, or global namespace if the active namespace is anonymous. This function throws an `ImportError' if the specified module is not found. NOTES The `import' function is not available on all systems. SEE ALSO set_import_module_path, use_namespace, current_namespace, getenv, evalfile -------------------------------------------------------------- set_import_module_path SYNOPSIS Set the search path for dynamically loadable objects USAGE set_import_module_path (String_Type path_list) DESCRIPTION The `set_import_module_path' may be used to set the search path for dynamically shared objects. Such objects may be made accessible to the application via the `import' function. The actual syntax for the specification of the set of paths will vary according to the operating system. Under Unix, a colon character is used to separate paths in `path_list'. For win32 systems a semi-colon is used. The `path_get_delimiter' function may be used to get the value of the delimiter. SEE ALSO import, get_import_module_path, path_get_delimiter -------------------------------------------------------------- add_doc_file SYNOPSIS Make a documentation file known to the help system USAGE add_doc_file (String_Type file) DESCRIPTION The `add_doc_file' is used to add a documentation file to the system. Such files are searched by the `get_doc_string_from_file' function. The `file' must be specified using the full path. SEE ALSO set_doc_files, get_doc_files, get_doc_string_from_file -------------------------------------------------------------- _apropos SYNOPSIS Generate a list of functions and variables USAGE Array_Type _apropos (String_Type ns, String_Type s, Integer_Type flags) DESCRIPTION The `_apropos' function may be used to get a list of all defined objects in the namespace `ns' whose name matches the regular expression `s' and whose type matches those specified by `flags'. It returns an array of strings containing the names matched. The 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 name (a) message (name); } prints a list of all matches. NOTES If the namespace specifier `ns' is the empty string `""', then the namespace will default to the static namespace of the current compilation unit. SEE ALSO is_defined, sprintf, _get_namespaces -------------------------------------------------------------- _function_name SYNOPSIS Returns the name of the currently executing function USAGE String_Type _function_name () DESCRIPTION This function returns the name of the currently executing function. If called from top-level, it returns the empty string. SEE ALSO _trace_function, is_defined -------------------------------------------------------------- __get_defined_symbols SYNOPSIS Get the symbols defined by the preprocessor USAGE Int_Type __get_defined_symbols () DESCRIPTION The `__get_defined_symbols' functions is used to get the list of all the symbols defined by the S-Lang preprocessor. It pushes each of the symbols on the stack followed by the number of items pushed. SEE ALSO is_defined, _apropos, _get_namespaces -------------------------------------------------------------- get_doc_files SYNOPSIS Get the list of documentation files USAGE String_Type[] = get_doc_files () DESCRIPTION The `get_doc_files' function returns the internal list of documentation files as an array of strings. SEE ALSO set_doc_files, add_doc_file, get_doc_string_from_file -------------------------------------------------------------- get_doc_string_from_file SYNOPSIS Read documentation from a file USAGE String_Type get_doc_string_from_file ([String_Type f,] String_Type t) DESCRIPTION If called with two arguments, `get_doc_string_from_file' opens the documentation file `f' and searches it for topic `t'. Otherwise, it will search an internal list of documentation files looking for the documentation associated with the topic `t'. If found, the documentation for `t' will be returned, otherwise the function will return NULL. Files may be added to the internal list via the `add_doc_file' or `set_doc_files' functions. SEE ALSO add_doc_file, set_doc_files, get_doc_files, _slang_doc_dir -------------------------------------------------------------- _get_namespaces SYNOPSIS Returns a list of namespace names USAGE String_Type[] _get_namespaces () DESCRIPTION This function returns a string array containing the names of the currently defined namespaces. SEE ALSO _apropos, use_namespace, implements, __get_defined_symbols -------------------------------------------------------------- is_defined SYNOPSIS Determine if a variable or function is defined USAGE Integer_Type is_defined (String_Type name) DESCRIPTION This function is used to determine whether or not a function or variable of the given name has been defined. If the specified name has not been defined, the function returns 0. Otherwise, it returns a non-zero value that depends on the type of object attached to the name. Specifically, it returns one of the following values: +1 intrinsic function +2 slang function -1 intrinsic variable -2 slang variable 0 undefined EXAMPLE Consider the function: define runhooks (hook) { if (2 == is_defined(hook)) eval(hook); } This function could be called from another S-Lang function to allow customization of that function, e.g., if the function represents a mode, the hook could be called to setup keybindings for the mode. SEE ALSO typeof, eval, autoload, __get_reference, __is_initialized -------------------------------------------------------------- __is_initialized SYNOPSIS Determine whether or not a variable has a value USAGE Integer_Type __is_initialized (Ref_Type r) DESCRIPTION This function returns non-zero of the object referenced by `r' is initialized, i.e., whether it has a value. It returns 0 if the referenced object has not been initialized. EXAMPLE The function: define zero () { variable f; return __is_initialized (&f); } will always return zero, but define one () { variable f = 0; return __is_initialized (&f); } will return one. SEE ALSO __get_reference, __uninitialize, is_defined, typeof, eval -------------------------------------------------------------- _NARGS SYNOPSIS The number of parameters passed to a function USAGE Integer_Type _NARGS The value of the `_NARGS' variable represents the number of arguments passed to the function. This variable is local to each function. EXAMPLE This example uses the `_NARGS' variable to print the list of values passed to the function: define print_values () { variable arg; if (_NARGS == 0) { message ("Nothing to print"); return; } foreach arg (__pop_args (_NARGS)) vmessage ("Argument value is: %S", arg.value); } SEE ALSO __pop_args, __push_args, typeof -------------------------------------------------------------- set_doc_files SYNOPSIS Set the internal list of documentation files USAGE set_doc_files (String_Type[] list) DESCRIPTION The `set_doc_files' function may be used to set the internal list of documentation files. It takes a single parameter, which is required to be an array of strings. The internal file list is set to the files specified by the elements of the array. EXAMPLE The following example shows how to add all the files in a specified directory to the internal list. It makes use of the `glob' function that is distributed as part of `slsh'. files = glob ("/path/to/doc/files/*.sld"); set_doc_files ([files, get_doc_files ()]); SEE ALSO get_doc_files, add_doc_file, get_doc_string_from_file -------------------------------------------------------------- _slang_doc_dir SYNOPSIS Installed documentation directory USAGE String_Type _slang_doc_dir DESCRIPTION The `_slang_doc_dir' variable is a read-only variable that specifies the compile-time installation location of the S-Lang documentation. SEE ALSO get_doc_string_from_file -------------------------------------------------------------- _slang_version SYNOPSIS The S-Lang library version number USAGE Integer_Type _slang_version DESCRIPTION `_slang_version' is a read-only variable that gives the version number of the S-Lang library. SEE ALSO _slang_version_string -------------------------------------------------------------- _slang_version_string SYNOPSIS The S-Lang library version number as a string USAGE String_Type _slang_version_string DESCRIPTION `_slang_version_string' is a read-only variable that gives a string representation of the version number of the S-Lang library. SEE ALSO _slang_version -------------------------------------------------------------- list_append SYNOPSIS Append an object to a list USAGE list_append (List_Type list, object [,Int_Type nth]) DESCRIPTION The `list_append' function is like `list_insert' except this function appends the object to the the list. The optional argument `nth' may be used to specify where the object is to be appended. See the documentation on `list_insert' for more details. SEE ALSO list_insert, list_delete, list_pop, list_new, list_reverse -------------------------------------------------------------- list_delete SYNOPSIS Remove an item from a list USAGE list_delete (List_Type list, Int_Type nth) DESCRIPTION This function removes the `nth' item in the specified list. The first item in the list corresponds to a value of `nth' equal to zero. If `nth' is negative, then the indexing is with respect to the end of the list with the last item corresponding to `nth' equal to -1. SEE ALSO list_insert, list_append, list_pop, list_new, list_reverse -------------------------------------------------------------- list_insert SYNOPSIS Insert an item into a list USAGE list_insert (List_Type list, object [,Int_Type nth]) DESCRIPTION This function may be used to insert an object into the specified list. With just two arguments, the object will be inserted at the beginning of the list. The optional third argument, `nth', may be used to specify the insertion point. The first item in the list corresponds to a value of `nth' equal to zero. If `nth' is negative, then the indexing is with respect to the end of the list with the last item given by a value of `nth' equal to -1. NOTES It is important to note that list_insert (list, object, 0); is not the same as list = {object, list} since the latter creates a new list with two items, `object' and the old list. SEE ALSO list_append, list_pop, list_delete, list_new, list_reverse -------------------------------------------------------------- list_new SYNOPSIS Create a new list USAGE List_Type list_new () DESCRIPTION This function creates a new empty List_Type object. Such a list may also be created using the syntax list = {}; SEE ALSO list_delete, list_insert, list_append, list_reverse, list_pop -------------------------------------------------------------- list_pop SYNOPSIS Extract an item from a list USAGE object = list_pop (List_Type list [, Int_Type nth]) DESCRIPTION The `list_pop' function returns a object from a list deleting the item from the list in the process. If the second argument is present, then it may be used to specify the position in the list where the item is to be obtained. If called with a single argument, the first item in the list will be used. SEE ALSO list_delete, list_insert, list_append, list_reverse, list_new -------------------------------------------------------------- list_reverse SYNOPSIS Reverse a list USAGE list_reverse (List_Type list) DESCRIPTION This function may be used to reverse the items in list. NOTES This function does not create a new list. The list passed to the function will be reversed upon return from the function. If it is desired to create a separate reversed list, then a separate copy should be made, e.g., rev_list = @list; list_reverse (rev_list); SEE ALSO list_new, list_insert, list_append, list_delete, list_pop -------------------------------------------------------------- list_to_array SYNOPSIS Convert a list into an array USAGE Array_Type list_to_array (List_Type list) DESCRIPTION The `list_to_array' function converts a list of objects into an array of the same length and returns the result. This function will generate an exception if the list is empty, or the objects in the list cannot be converted to a common type. NOTES A future version of this function may produce an Any_Type array for an empty or heterogeneous list. SEE ALSO length, typecast, __pop_list, typeof, array_sort -------------------------------------------------------------- abs SYNOPSIS Compute the absolute value of a number USAGE y = abs(x) DESCRIPTION The `abs' function returns the absolute value of an arithmetic type. If its argument is a complex number (Complex_Type), then it returns the modulus. If the argument is an array, a new array will be created whose elements are obtained from the original array by using the `abs' function. SEE ALSO sign, sqr -------------------------------------------------------------- acos SYNOPSIS Compute the arc-cosine of a number USAGE y = acos (x) DESCRIPTION The `acos' function computes the arc-cosine of a number and returns the result. If its argument is an array, the `acos' function will be applied to each element and the result returned as an array. SEE ALSO cos, atan, acosh, cosh -------------------------------------------------------------- acosh SYNOPSIS Compute the inverse cosh of a number USAGE y = acosh (x) DESCRIPTION The `acosh' function computes the inverse hyperbolic cosine of a number and returns the result. If its argument is an array, the `acosh' function will be applied to each element and the result returned as an array. SEE ALSO cos, atan, acosh, cosh -------------------------------------------------------------- asin SYNOPSIS Compute the arc-sine of a number USAGE y = asin (x) DESCRIPTION The `asin' function computes the arc-sine of a number and returns the result. If its argument is an array, the `asin' function will be applied to each element and the result returned as an array. SEE ALSO cos, atan, acosh, cosh -------------------------------------------------------------- asinh SYNOPSIS Compute the inverse-sinh of a number USAGE y = asinh (x) DESCRIPTION The `asinh' function computes the inverse hyperbolic sine of a number and returns the result. If its argument is an array, the `asinh' function will be applied to each element and the result returned as an array. SEE ALSO cos, atan, acosh, cosh -------------------------------------------------------------- atan SYNOPSIS Compute the arc-tangent of a number USAGE y = atan (x) DESCRIPTION The `atan' function computes the arc-tangent of a number and returns the result. If its argument is an array, the `atan' function will be applied to each element and the result returned as an array. SEE ALSO atan2, cos, acosh, cosh -------------------------------------------------------------- atan2 SYNOPSIS Compute the arc-tangent of the ratio of two variables USAGE z = atan2 (y, x) DESCRIPTION The `atan2' function computes the arc-tangent of the ratio `y/x' and returns the result as a value that has the proper sign for the quadrant where the point (x,y) is located. The returned value `z' will satisfy (-PI < z <= PI). If either of the arguments is an array, an array of the corresponding values will be returned. SEE ALSO hypot, cos, atan, acosh, cosh -------------------------------------------------------------- atanh SYNOPSIS Compute the inverse-tanh of a number USAGE y = atanh (x) DESCRIPTION The `atanh' function computes the inverse hyperbolic tangent of a number and returns the result. If its argument is an array, the `atanh' function will be applied to each element and the result returned as an array. SEE ALSO cos, atan, acosh, cosh -------------------------------------------------------------- ceil SYNOPSIS Round x up to the nearest integral value USAGE y = ceil (x) DESCRIPTION This function rounds its numeric argument up to the nearest integral value. If the argument is an array, the corresponding array will be returned. SEE ALSO floor, round -------------------------------------------------------------- Conj SYNOPSIS Compute the complex conjugate of a number USAGE z1 = Conj (z) DESCRIPTION The `Conj' function returns the complex conjugate of a number. If its argument is an array, the `Conj' function will be applied to each element and the result returned as an array. SEE ALSO Real, Imag, abs -------------------------------------------------------------- cos SYNOPSIS Compute the cosine of a number USAGE y = cos (x) DESCRIPTION The `cos' function computes the cosine of a number and returns the result. If its argument is an array, the `cos' function will be applied to each element and the result returned as an array. SEE ALSO cos, atan, acosh, cosh -------------------------------------------------------------- cosh SYNOPSIS Compute the hyperbolic cosine of a number USAGE y = cosh (x) DESCRIPTION The `cosh' function computes the hyperbolic cosine of a number and returns the result. If its argument is an array, the `cosh' function will be applied to each element and the result returned as an array. SEE ALSO cos, atan, acosh, cosh -------------------------------------------------------------- _diff SYNOPSIS Compute the absolute difference of two values USAGE y = _diff (x, y) DESCRIPTION The `_diff' function returns a floating point number equal to the absolute value of the difference of its two arguments. If either argument is an array, an array of the corresponding values will be returned. SEE ALSO abs -------------------------------------------------------------- exp SYNOPSIS Compute the exponential of a number USAGE y = exp (x) DESCRIPTION The `exp' function computes the exponential of a number and returns the result. If its argument is an array, the `exp' function will be applied to each element and the result returned as an array. SEE ALSO expm1, cos, atan, acosh, cosh -------------------------------------------------------------- expm1 SYNOPSIS Compute exp(x)-1 USAGE y = expm1(x) DESCRIPTION The `expm1' function computes `exp(x)-1' and returns the result. If its argument is an array, the `expm1' function will be applied to each element and the results returned as an array. This function should be called whenever `x' is close to 0 to avoid the numerical error that would arise in a naive computation of `exp(x)-1'. SEE ALSO expm1, log1p, cos, atan, acosh, cosh -------------------------------------------------------------- feqs SYNOPSIS Test the approximate equality of two numbers USAGE Char_Type feqs (a, b [,reldiff [,absdiff]] DESCRIPTION This function compares two floating point numbers `a' and `b', and returns a non-zero value if they are equal to within a specified tolerance; otherwise 0 will be returned. If either is an array, a corresponding boolean array will be returned. The tolerances are specified as relative and absolute differences via the optional third and fourth arguments. If no optional arguments are present, the tolerances default to `reldiff=0.01' and `absdiff=1e-6'. If only the relative difference has been specified, the absolute difference (`absdiff') will be taken to be 0.0. For the case when `|b|>=|a|', `a' and `b' are considered to be equal to within the specified tolerances if either `|b-a|<=absdiff' or `|b-a|/|b|<=reldiff' is true. SEE ALSO fneqs, fgteqs, flteqs -------------------------------------------------------------- fgteqs SYNOPSIS Compare two numbers using specified tolerances . USAGE Char_Type feqs (a, b [,reldiff [,absdiff]] DESCRIPTION This function is functionally equivalent to: (a >= b) or feqs(a,b,...) See the documentation of `feqs' for more information. SEE ALSO feqs, fneqs, flteqs -------------------------------------------------------------- floor SYNOPSIS Round x down to the nearest integer USAGE y = floor (x) DESCRIPTION This function rounds its numeric argument down to the nearest integral value. If the argument is an array, the corresponding array will be returned. SEE ALSO ceil, round, nint -------------------------------------------------------------- flteqs SYNOPSIS Compare two numbers using specified tolerances . USAGE Char_Type feqs (a, b [,reldiff [,absdiff]] DESCRIPTION This function is functionally equivalent to: (a <= b) or feqs(a,b,...) See the documentation of `feqs' for more information. SEE ALSO feqs, fneqs, fgteqs -------------------------------------------------------------- fneqs SYNOPSIS Test the approximate inequality of two numbers USAGE Char_Type feqs (a, b [,reldiff [,absdiff]] DESCRIPTION This function is functionally equivalent to: not fneqs(a,b,...) See the documentation of `feqs' for more information. SEE ALSO feqs, fgteqs, flteqs -------------------------------------------------------------- get_float_format SYNOPSIS Get the format for printing floating point values. USAGE String_Type get_float_format () DESCRIPTION The `get_float_format' retrieves the format string used for printing single and double precision floating point numbers. See the documentation for the `set_float_format' function for more information about the format. SEE ALSO set_float_format -------------------------------------------------------------- hypot SYNOPSIS Compute sqrt(x^2+y^2) USAGE r = hypot (x [,y]) DESCRIPTION If given two arguments, `hypot' function computes the quantity `sqrt(x^2+y^2)' except that it employs an algorithm that tries to avoid arithmetic overflow when `x' or `y' are large. If either argument is an array, an array of the corresponding values will be returned. If given a single array argument `x', the `hypot' function will compute `sqrt(sumsq(x))', where `sumsq(x)' computes the sum of the squares of the elements of `x'. SEE ALSO atan2, cos, atan, acosh, cosh, sum, sumsq -------------------------------------------------------------- Imag SYNOPSIS Compute the imaginary part of a number USAGE i = Imag (z) DESCRIPTION The `Imag' function returns the imaginary part of a number. If its argument is an array, the `Imag' function will be applied to each element and the result returned as an array. SEE ALSO Real, Conj, abs -------------------------------------------------------------- isinf SYNOPSIS Test for infinity USAGE y = isinf (x) DESCRIPTION This function returns 1 if x corresponds to an IEEE infinity, or 0 otherwise. If the argument is an array, an array of the corresponding values will be returned. SEE ALSO isnan, _Inf -------------------------------------------------------------- isnan SYNOPSIS isnan USAGE y = isnan (x) DESCRIPTION This function returns 1 if x corresponds to an IEEE NaN (Not a Number), or 0 otherwise. If the argument is an array, an array of the corresponding values will be returned. SEE ALSO isinf, _NaN -------------------------------------------------------------- log SYNOPSIS Compute the logarithm of a number USAGE y = log (x) DESCRIPTION The `log' function computes the natural logarithm of a number and returns the result. If its argument is an array, the `log' function will be applied to each element and the result returned as an array. SEE ALSO cos, atan, acosh, cosh, log1p -------------------------------------------------------------- log10 SYNOPSIS Compute the base-10 logarithm of a number USAGE y = log10 (x) DESCRIPTION The `log10' function computes the base-10 logarithm of a number and returns the result. If its argument is an array, the `log10' function will be applied to each element and the result returned as an array. SEE ALSO cos, atan, acosh, cosh -------------------------------------------------------------- log1p SYNOPSIS Compute the logarithm of 1 plus a number USAGE y = log1p (x) DESCRIPTION The `log1p' function computes the natural logarithm of 1.0 plus `x' returns the result. If its argument is an array, the `log1p' function will be applied to each element and the results returned as an array. This function should be used instead of `log(1+x)' to avoid numerical errors whenever `x' is close to 0. SEE ALSO log, expm1, cos, atan, acosh, cosh -------------------------------------------------------------- _max SYNOPSIS Compute the maximum of two values USAGE z = _max (x,y) DESCRIPTION The `_max' function returns a floating point number equal to the maximum value of its two arguments. If either argument is an array, an array of the corresponding values will be returned. NOTES This function returns a floating point result even when both arguments are integers. SEE ALSO max, _min, min -------------------------------------------------------------- _min SYNOPSIS Compute the minimum of two values USAGE z = _min (x,y) DESCRIPTION The `_min' function returns a floating point number equal to the minimum value of its two arguments. If either argument is an array, an array of the corresponding values will be returned. NOTES This function returns a floating point result even when both arguments are integers. SEE ALSO min, _max, max -------------------------------------------------------------- mul2 SYNOPSIS Multiply a number by 2 USAGE y = mul2(x) DESCRIPTION The `mul2' function multiplies an arithmetic type by two and returns the result. If its argument is an array, a new array will be created whose elements are obtained from the original array by using the `mul2' function. SEE ALSO sqr, abs -------------------------------------------------------------- nint SYNOPSIS Round to the nearest integer USAGE i = nint(x) DESCRIPTION The `nint' rounds its argument to the nearest integer and returns the result. If its argument is an array, a new array will be created whose elements are obtained from the original array elements by using the `nint' function. SEE ALSO round, floor, ceil -------------------------------------------------------------- polynom SYNOPSIS Evaluate a polynomial USAGE Double_Type polynom([a0,a1,...aN], x [,use_factorial]) DESCRIPTION The `polynom' function returns the value of the polynomial expression a0 + a1*x + a2*x^2 + ... + aN*x^N where the coefficients are given by an array of values `[a0,...,aN]'. If `x' is an array, the function will return a corresponding array. If the value of the optional `use_factorial' parameter is non-zero, then each term in the sum will be normalized by the corresponding factorial, i.e., a0/0! + a1*x/1! + a2*x^2/2! + ... + aN*x^N/N! NOTES Prior to version 2.2, this function had a different calling syntax and and was less useful. The `polynom' function does not yet support complex-valued coefficients. For the case of a scalar value of `x' and a small degree polynomial, it is more efficient to use an explicit expression. SEE ALSO exp -------------------------------------------------------------- Real SYNOPSIS Compute the real part of a number USAGE r = Real (z) DESCRIPTION The `Real' function returns the real part of a number. If its argument is an array, the `Real' function will be applied to each element and the result returned as an array. SEE ALSO Imag, Conj, abs -------------------------------------------------------------- round SYNOPSIS Round to the nearest integral value USAGE y = round (x) DESCRIPTION This function rounds its argument to the nearest integral value and returns it as a floating point result. If the argument is an array, an array of the corresponding values will be returned. SEE ALSO floor, ceil, nint -------------------------------------------------------------- set_float_format SYNOPSIS Set the format for printing floating point values. USAGE set_float_format (String_Type fmt) DESCRIPTION The `set_float_format' function is used to set the floating point format to be used when floating point numbers are printed. The routines that use this are the traceback routines and the `string' function, any anything based upon the `string' function. The default value is `"%S"', which causes the number to be displayed with enough significant digits such that `x==atof(string(x))'. EXAMPLE set_float_format ("%S"); % default s = string (PI); % --> s = "3.141592653589793" set_float_format ("%16.10f"); s = string (PI); % --> s = "3.1415926536" set_float_format ("%10.6e"); s = string (PI); % --> s = "3.141593e+00" SEE ALSO get_float_format, string, sprintf, atof, double -------------------------------------------------------------- sign SYNOPSIS Compute the sign of a number USAGE y = sign(x) DESCRIPTION The `sign' function returns the sign of an arithmetic type. If its argument is a complex number (Complex_Type), the `sign' will be applied to the imaginary part of the number. If the argument is an array, a new array will be created whose elements are obtained from the original array by using the `sign' function. When applied to a real number or an integer, the `sign' function returns -1, 0, or `+1' according to whether the number is less than zero, equal to zero, or greater than zero, respectively. SEE ALSO abs -------------------------------------------------------------- sin SYNOPSIS Compute the sine of a number USAGE y = sin (x) DESCRIPTION The `sin' function computes the sine of a number and returns the result. If its argument is an array, the `sin' function will be applied to each element and the result returned as an array. SEE ALSO cos, atan, acosh, cosh -------------------------------------------------------------- sinh SYNOPSIS Compute the hyperbolic sine of a number USAGE y = sinh (x) DESCRIPTION The `sinh' function computes the hyperbolic sine of a number and returns the result. If its argument is an array, the `sinh' function will be applied to each element and the result returned as an array. SEE ALSO cos, atan, acosh, cosh -------------------------------------------------------------- sqr SYNOPSIS Compute the square of a number USAGE y = sqr(x) DESCRIPTION The `sqr' function returns the square of an arithmetic type. If its argument is a complex number (Complex_Type), then it returns the square of the modulus. If the argument is an array, a new array will be created whose elements are obtained from the original array by using the `sqr' function. NOTES For real scalar numbers, using `x*x' instead of `sqr(x)' will result in faster executing code. However, if `x' is an array, then `sqr(x)' will execute faster. SEE ALSO abs, mul2 -------------------------------------------------------------- sqrt SYNOPSIS Compute the square root of a number USAGE y = sqrt (x) DESCRIPTION The `sqrt' function computes the square root of a number and returns the result. If its argument is an array, the `sqrt' function will be applied to each element and the result returned as an array. SEE ALSO sqr, cos, atan, acosh, cosh -------------------------------------------------------------- tan SYNOPSIS Compute the tangent of a number USAGE y = tan (x) DESCRIPTION The `tan' function computes the tangent of a number and returns the result. If its argument is an array, the `tan' function will be applied to each element and the result returned as an array. SEE ALSO cos, atan, acosh, cosh -------------------------------------------------------------- tanh SYNOPSIS Compute the hyperbolic tangent of a number USAGE y = tanh (x) DESCRIPTION The `tanh' function computes the hyperbolic tangent of a number and returns the result. If its argument is an array, the `tanh' function will be applied to each element and the result returned as an array. SEE ALSO cos, atan, acosh, cosh -------------------------------------------------------------- _ispos SYNOPSIS Test if a number is greater than 0 USAGE Char_Type _ispos(x) DESCRIPTION This function returns 1 if a number is greater than 0, and zero otherwise. If the argument is an array, then the corresponding array of boolean (Char_Type) values will be returned. SEE ALSO _isneg, _isnonneg -------------------------------------------------------------- _isneg SYNOPSIS Test if a number is less than 0 USAGE Char_Type _isneg(x) DESCRIPTION This function returns 1 if a number is less than 0, and zero otherwise. If the argument is an array, then the corresponding array of boolean (Char_Type) values will be returned. SEE ALSO _ispos, _isnonneg -------------------------------------------------------------- _isnonneg SYNOPSIS Test if a number is greater than or equal to 0 USAGE Char_Type _isnonneg(x) DESCRIPTION This function returns 1 if a number is greater or equal to 0, and zero otherwise. If the argument is an array, then the corresponding array of boolean (Char_Type) values will be returned. SEE ALSO _isneg, _isnonneg -------------------------------------------------------------- errno SYNOPSIS Error code set by system functions USAGE Int_Type errno DESCRIPTION A system function can fail for a variety of reasons. For example, a file operation may fail because lack of disk space, or the process does not have permission to perform the operation. Such functions will return -1 and set the variable `errno' to an error code describing the reason for failure. Particular values of `errno' may be specified by the following symbolic constants (read-only variables) and the corresponding `errno_string' value: 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) throw IOError, sprintf ("mkdir %s failed: %s", dir, errno_string (errno)); } SEE ALSO errno_string, error, mkdir -------------------------------------------------------------- errno_string SYNOPSIS Return a string describing an errno. USAGE String_Type errno_string ( [Int_Type err ]) DESCRIPTION The `errno_string' function returns a string describing the integer errno code `err'. If the `err' parameter is omitted, the current value of `errno' will be used. See the description for `errno' for more information. EXAMPLE The `errno_string' function may be used as follows: define sizeof_file (file) { variable st = stat_file (file); if (st == NULL) throw IOError, sprintf ("%s: %s", file, errno_string (errno)); return st.st_size; } SEE ALSO errno, stat_file -------------------------------------------------------------- error SYNOPSIS Generate an error condition (deprecated) USAGE error (String_Type msg DESCRIPTION This function has been deprecated in favor of `throw'. The `error' function generates a S-Lang `RunTimeError' exception. It takes a single string parameter which is displayed on the stderr output device. EXAMPLE define add_txt_extension (file) { if (typeof (file) != String_Type) error ("add_extension: parameter must be a string"); file += ".txt"; return file; } SEE ALSO verror, message -------------------------------------------------------------- __get_exception_info SYNOPSIS Get information about the current exception USAGE Struct_Type __get_exception_info () DESCRIPTION This function returns information about the currently active exception in the form as a structure with the following fields: error The current exception, e.g., RunTimeError descr A description of the exception file Name of the file generating the exception line Line number where the exception originated function Function where the exception originated object A user-defined object thrown by the exception message A user-defined message traceback Traceback messages If no exception is active, NULL will be returned. This same information may also be obtained via the optional argument to the `try' statement: variable e = NULL; try (e) { do_something (); } finally { if (e != NULL) vmessage ("An error occured: %s", e.message); } SEE ALSO error -------------------------------------------------------------- message SYNOPSIS Print a string onto the message device USAGE message (String_Type s DESCRIPTION The `message' function will print the string specified by `s' onto the message device. EXAMPLE define print_current_time () { message (time ()); } NOTES The message device will depend upon the application. For example, the output message device for the jed editor corresponds to the line at the bottom of the display window. The default message device is the standard output device. SEE ALSO vmessage, sprintf, error -------------------------------------------------------------- new_exception SYNOPSIS Create a new exception USAGE new_exception (String_Type name, Int_Type baseclass, String_Type descr) DESCRIPTION This function creates a new exception called `name' subclassed upon `baseclass'. The description of the exception is specified by `descr'. EXAMPLE new_exception ("MyError", RunTimeError, "My very own error"); try { if (something_is_wrong ()) throw MyError; } catch RunTimeError; In this case, catching `RunTimeError' will also catch `MyError' since it is a subclass of `RunTimeError'. SEE ALSO error, verror -------------------------------------------------------------- usage SYNOPSIS Generate a usage error USAGE usage (String_Type msg) DESCRIPTION The `usage' function generates a `UsageError' exception and displays `msg' to the message device. EXAMPLE Suppose that a function called `plot' plots an array of `x' and `y' values. Then such a function could be written to issue a usage message if the wrong number of arguments was passed: define plot () { variable x, y; if (_NARGS != 2) usage ("plot (x, y)"); (x, y) = (); % Now do the hard part . . } SEE ALSO error, message -------------------------------------------------------------- verror SYNOPSIS Generate an error condition (deprecated) USAGE verror (String_Type fmt, ...) DESCRIPTION This function has been deprecated in favor or `throw'. The `verror' function performs the same role as the `error' function. The only difference is that instead of a single string argument, `verror' takes a sprintf style argument list. EXAMPLE define open_file (file) { variable fp; fp = fopen (file, "r"); if (fp == NULL) verror ("Unable to open %s", file); return fp; } NOTES In the current implementation, the `verror' function is not an intrinsic function. Rather it is a predefined S-Lang function using a combination of `sprintf' and `error'. To generate a specific exception, a `throw' statement should be used. In fact, a `throw' statement such as: if (fp == NULL) throw OpenError, "Unable to open $file"$; is preferable to the use of `verror' in the above example. SEE ALSO error, Sprintf, vmessage -------------------------------------------------------------- vmessage SYNOPSIS Print a formatted string onto the message device USAGE vmessage (String_Type fmt, ...) DESCRIPTION The `vmessage' function formats a sprintf style argument list and displays the resulting string onto the message device. NOTES In the current implementation, the `vmessage' function is not an intrinsic function. Rather it is a predefined S-Lang function using a combination of `Sprintf' and `message'. SEE ALSO message, sprintf, Sprintf, verror -------------------------------------------------------------- _auto_declare SYNOPSIS Set automatic variable declaration mode USAGE Integer_Type _auto_declare DESCRIPTION The `_auto_declare' variable may be used to have undefined variable implicitly declared. If set to zero, any variable must be declared with a `variable' declaration before it can be used. If set to one, then any undeclared variable will be declared as a `static' variable. The `_auto_declare' variable is local to each compilation unit and setting its value in one unit has no effect upon its value in other units. The value of this variable has no effect upon the variables in a function. EXAMPLE The following code will not compile if `X' not been declared: X = 1; However, _auto_declare = 1; % declare variables as static. X = 1; is equivalent to static variable X = 1; NOTES This variable should be used sparingly and is intended primarily for interactive applications where one types S-Lang commands at a prompt. -------------------------------------------------------------- __class_id SYNOPSIS Return the class-id of a specified type USAGE Int_Type __class_id (DataType_Type type) DESCRIPTION This function returns the internal class-id of a specified data type. SEE ALSO typeof, _typeof, __class_type, __datatype -------------------------------------------------------------- __class_type SYNOPSIS Return the class-type of a specified type USAGE Int_Type __class_type (DataType_Type type)) DESCRIPTION Internally S-Lang objects are classified according to four types: scalar, vector, pointer, and memory managed types. For example, an integer is implemented as a scalar, a complex number as a vector, and a string is represented as a pointer. The `__class_type' function returns an integer representing the class-type associated with the specified data type. Specifically, it returns: 0 memory-managed 1 scalar 2 vector 3 pointer SEE ALSO typeof, _typeof, __class_id, __datatype -------------------------------------------------------------- current_namespace SYNOPSIS Get the name of the current namespace USAGE String_Type current_namespace () DESCRIPTION The `current_namespace' function returns the name of the static namespace associated with the compilation unit. If there is no such namespace associated with the compilation unit, then the empty string `""' will be returned. SEE ALSO implements, use_namespace, import, evalfile -------------------------------------------------------------- __datatype SYNOPSIS Get the DataType_Type for a specified internal class-id USAGE DataType_Type __datatype (Int_Type id) DESCRIPTION This function is the inverse of __class_type in the sense that it returns the DataType_Type for the specified class-id. If no such class exists, the function will return NULL. NOTES One should not expect distinct interpreter instances to always return the same value for a dynamically assigned class-id such as one defined by a module or one stemming from a `typedef' statement. SEE ALSO __class_id, __class_type, typeof -------------------------------------------------------------- _eqs SYNOPSIS Test for equality of two objects USAGE Int_Type _eqs (a, b) DESCRIPTION This function tests its two arguments for equality and returns 1 if they are equal or 0 otherwise. What it means to be equal depends upon the data types of the objects being compared. If the types are numeric, they are regarded as equal if their numerical values are equal. If they are arrays, then they are equal if they have the same shape with equal elements. If they are structures, then they are equal if they contain identical fields, and the corresponding values are equal. EXAMPLE _eqs (1, 1) ===> 1 _eqs (1, 1.0) ===> 1 _eqs ("a", 1) ===> 0 _eqs ([1,2], [1.0,2.0]) ===> 1 SEE ALSO typeof, _eqs, __get_reference, __is_callable NOTES For testing sameness, use `__is_same'. -------------------------------------------------------------- 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 -------------------------------------------------------------- __get_reference SYNOPSIS Get a reference to a global object USAGE Ref_Type __get_reference (String_Type nm) DESCRIPTION This function returns a reference to a global variable or function whose name is specified by `nm'. If no such object exists, it returns NULL, otherwise it returns a reference. EXAMPLE Consider the function: define runhooks (hook) { variable f; f = __get_reference (hook); if (f != NULL) @f (); } This function could be called from another S-Lang function to allow customization of that function, e.g., if the function represents a jed editor mode, the hook could be called to setup keybindings for the mode. SEE ALSO is_defined, typeof, eval, autoload, __is_initialized, __uninitialize -------------------------------------------------------------- implements SYNOPSIS Create a new static namespace USAGE implements (String_Type name) DESCRIPTION The `implements' function may be used to create a new static namespace and have it associated with the current compilation unit. If a namespace with the specified name already exists, a `NamespaceError' exception will be thrown. In addition to creating a new static namespace and associating it with the compilation unit, the function will also create a new private namespace. As a result, any symbols in the previous private namespace will be no longer be accessable. For this reason, it is recommended that this function should be used before any private symbols have been created. EXAMPLE Suppose that some file `t.sl' contains: implements ("My"); define message (x) { Global->message ("My's message: $x"$); } message ("hello"); will produce `"My's message: hello"'. This `message' function may be accessed from outside the namespace via: My->message ("hi"); NOTES Since `message' is an intrinsic function, it is public and may not be redefined in the public namespace. The `implements' function should rarely be used. It is preferable to allow a static namespace to be associated with a compilation unit using, e.g., `evalfile'. SEE ALSO use_namespace, current_namespace, import -------------------------------------------------------------- __is_callable SYNOPSIS Determine whether or not an object is callable USAGE Int_Type __is_callable (obj) DESCRIPTION This function may be used to determine if an object is callable by dereferencing the object. It returns 1 if the argument is callable, or zero otherwise. EXAMPLE __is_callable (7) ==> 0 __is_callable (&sin) ==> 1 a = [&sin]; __is_callable (a[0]) ==> 1 __is_callable (&a[0]) ==> 0 SEE ALSO __is_numeric, is_defined -------------------------------------------------------------- __is_numeric SYNOPSIS Determine whether or not an object is a numeric type USAGE Int_Type __is_numeric (obj) DESCRIPTION This function may be used to determine if an object represents a numeric type. It returns 0 if the argument is non-numeric, 1 if it is an integer, 2 if a floating point number, and 3 if it is complex. If the argument is an array, then the array type will be used for the test. EXAMPLE __is_numeric ("foo"); ==> 0 __is_numeric ("0"); ==> 0 __is_numeric (0); ==> 1 __is_numeric (PI); ==> 2 __is_numeric (2j); ==> 3 __is_numeric ([1,2]); ==> 1 __is_numeric ({1,2}); ==> 0 SEE ALSO typeof, __is_datatype_numeric -------------------------------------------------------------- __is_datatype_numeric SYNOPSIS Determine whether or not a type is a numeric type USAGE Int_Type __is_datatype_numeric (DataType_Type type) DESCRIPTION This function may be used to determine if the specified datatype represents a numeric type. It returns 0 if the datatype does not represents a numeric type; otherwise it returns 1 for an integer type, 2 for a floating point type, and 3 for a complex type. SEE ALSO typeof, __is_numeric, __is_callable -------------------------------------------------------------- __is_same SYNOPSIS Test for sameness of two objects USAGE Int_Type __is_same (a, b) DESCRIPTION This function tests its two arguments for sameness and returns 1 if they are the same, or 0 otherwise. To be the same, the data type of the arguments must match and the values of the objects must reference the same underlying object. EXAMPLE __is_same (1, 1) ===> 1 __is_same (1, 1.0) ===> 0 __is_same ("a", 1) ===> 0 __is_same ([1,2], [1,2]) ===> 0 SEE ALSO typeof, _eqs, __get_reference, __is_callable NOTES For testing equality, use `_eqs'. -------------------------------------------------------------- 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 throws an `OSError' upon failure. NOTES This function may not be available on all systems. SEE ALSO getenv, sprintf -------------------------------------------------------------- _slang_install_prefix SYNOPSIS S-Lang's installation prefix USAGE String_Type _slang_install_prefix DESCRIPTION The value of this variable is set at the S-Lang library's compilation time. On Unix systems, the value corresponds to the value of the `prefix' variable in the Makefile. For normal installations, the library itself will be located in the `lib' subdirectory of the `prefix' directory. NOTES The value of this variable may or may not have anything to do with where the slang library is located. As such, it should be regarded as a hint. A standard installation will have the `slsh' library files located in the `share/slsh' subdirectory of the installation prefix. SEE ALSO _slang_doc_dir -------------------------------------------------------------- _slang_utf8_ok SYNOPSIS Test if the interpreter running in UTF-8 mode USAGE Int_Type _slang_utf8_ok DESCRIPTION If the value of this variable is non-zero, then the interpreter is running in UTF-8 mode. In this mode, characters in strings are interpreted as variable length byte sequences according to the semantics of the UTF-8 encoding. NOTES When running in UTF-8 mode, one must be careful not to confuse a character with a byte. For example, in this mode the `strlen' function returns the number of characters in a string which may be different than the number of bytes. The latter information may be obtained by the `strbytelen' function. SEE ALSO strbytelen, strlen, strcharlen -------------------------------------------------------------- __uninitialize SYNOPSIS Uninitialize a variable USAGE __uninitialize (Ref_Type x) DESCRIPTION The `__uninitialize' function may be used to uninitialize the variable referenced by the parameter `x'. EXAMPLE The following two lines are equivalent: () = __tmp(z); __uninitialize (&z); SEE ALSO __tmp, __is_initialized -------------------------------------------------------------- use_namespace SYNOPSIS Change to another namespace USAGE use_namespace (String_Type name) DESCRIPTION The `use_namespace' function changes the current static namespace to the one specified by the parameter. If the specified namespace does not exist, a `NamespaceError' exception will be generated. SEE ALSO implements, current_namespace, import -------------------------------------------------------------- path_basename SYNOPSIS Get the basename part of a filename USAGE String_Type path_basename (String_Type filename) DESCRIPTION The `path_basename' function returns the basename associated with the `filename' parameter. The basename is the non-directory part of the filename, e.g., on unix `c' is the basename of `/a/b/c'. SEE ALSO path_dirname, path_extname, path_concat, path_is_absolute -------------------------------------------------------------- path_basename_sans_extname SYNOPSIS Get the basename part of a filename but without the extension USAGE String_Type path_basename_sans_extname (String_Type path) DESCRIPTION The `path_basename_sans_extname' function returns the basename associated with the `filename' parameter, omitting the extension if present. The basename is the non-directory part of the filename, e.g., on unix `c' is the basename of `/a/b/c'. SEE ALSO path_dirname, path_basename, path_extname, path_concat, path_is_absolute -------------------------------------------------------------- path_concat SYNOPSIS Combine elements of a filename USAGE String_Type path_concat (String_Type dir, String_Type basename) DESCRIPTION The `path_concat' function combines the arguments `dir' and `basename' to produce a filename. For example, on Unix if `dir' is `x/y' and `basename' is `z', then the function will return `x/y/z'. SEE ALSO path_dirname, path_basename, path_extname, path_is_absolute -------------------------------------------------------------- path_dirname SYNOPSIS Get the directory name part of a filename USAGE String_Type path_dirname (String_Type filename) DESCRIPTION The `path_dirname' function returns the directory name associated with a specified filename. NOTES On systems that include a drive specifier as part of the filename, the value returned by this function will also include the drive specifier. SEE ALSO path_basename, path_extname, path_concat, path_is_absolute -------------------------------------------------------------- path_extname SYNOPSIS Return the extension part of a filename USAGE String_Type path_extname (String_Type filename) DESCRIPTION The `path_extname' function returns the extension portion of the specified filename. If an extension is present, this function will also include the dot as part of the extension, e.g., if `filename' is `"file.c"', then this function will return `".c"'. If no extension is present, the function returns an empty string `""'. NOTES Under VMS, the file version number is not returned as part of the extension. SEE ALSO path_sans_extname, path_dirname, path_basename, path_concat, path_is_absolute -------------------------------------------------------------- path_get_delimiter SYNOPSIS Get the value of a search-path delimiter USAGE Char_Type path_get_delimiter () DESCRIPTION This function returns the value of the character used to delimit fields of a search-path. SEE ALSO set_slang_load_path, get_slang_load_path -------------------------------------------------------------- path_is_absolute SYNOPSIS Determine whether or not a filename is absolute USAGE Int_Type path_is_absolute (String_Type filename) DESCRIPTION The `path_is_absolute' function will return non-zero is `filename' refers to an absolute filename, otherwise it returns zero. SEE ALSO path_dirname, path_basename, path_extname, path_concat -------------------------------------------------------------- path_sans_extname SYNOPSIS Strip the extension from a filename USAGE String_Type path_sans_extname (String_Type filename) DESCRIPTION The `path_sans_extname' function removes the file name extension (including the dot) from the filename and returns the result. SEE ALSO path_basename_sans_extname, path_extname, path_basename, path_dirname, path_concat -------------------------------------------------------------- close SYNOPSIS Close an open file descriptor USAGE Int_Type close (FD_Type fd) DESCRIPTION The `close' function is used to close and open file descriptor created by the `open' function. Upon success 0 is returned, otherwise the function returns -1 and sets `errno' accordingly. SEE ALSO open, fclose, read, write -------------------------------------------------------------- dup_fd SYNOPSIS Duplicate a file descriptor USAGE FD_Type dup_fd (FD_Type fd) DESCRIPTION The `dup_fd' function duplicates a specified file descriptor and returns the duplicate. If the function fails, NULL will be returned and `errno' set accordingly. NOTES This function is essentially a wrapper around the POSIX `dup' function. SEE ALSO open, close -------------------------------------------------------------- _fileno SYNOPSIS Get the underlying integer file descriptor USAGE Int_Type fileno (File_Type|FD_Type fp) DESCRIPTION The `_fileno' function returns the underlying integer descriptor for a specified stdio File_Type or FD_Type object. Upon failure it returns -1 and sets `errno' accordingly. SEE ALSO fileno, fopen, open, fclose, close, dup_fd -------------------------------------------------------------- fileno SYNOPSIS Convert a stdio File_Type object to a FD_Type descriptor USAGE FD_Type fileno (File_Type fp) DESCRIPTION The `fileno' function returns the FD_Type descriptor associated with the stdio File_Type file pointer. Upon failure, NULL is returned. NOTES Closing the resulting file descriptor will have no effect. SEE ALSO fopen, open, fclose, close, dup_fd, _fileno -------------------------------------------------------------- isatty SYNOPSIS Determine if an open file descriptor refers to a terminal USAGE Int_Type isatty (FD_Type or File_Type fd) DESCRIPTION This function returns 1 if the file descriptor `fd' refers to a terminal; otherwise it returns 0. The object `fd' may either be a File_Type stdio descriptor or a lower-level FD_Type object. SEE ALSO fopen, fclose, fileno -------------------------------------------------------------- lseek SYNOPSIS Reposition a file descriptor's file pointer USAGE Long_Type lseek (FD_Type fd, LLong_Type ofs, int mode) The `lseek' function repositions the file pointer associated with the open file descriptor `fd' to the offset `ofs' according to the mode parameter. Specifically, `mode' must be one of the values: SEEK_SET Set the offset to ofs from the beginning of the file SEEK_CUR Add ofs to the current offset SEEK_END Add ofs to the current file size Upon error, `lseek' returns -1 and sets `errno'. If successful, it returns the new filepointer offset. NOTES Not all file descriptors are capable of supporting the seek operation, e.g., a descriptor associated with a pipe. By using SEEK_END with a positive value of the `ofs' parameter, it is possible to position the file pointer beyond the current size of the file. SEE ALSO fseek, ftell, open, close -------------------------------------------------------------- open SYNOPSIS Open a file USAGE FD_Type open (String_Type filename, Int_Type flags [,Int_Type mode]) DESCRIPTION The `open' function attempts to open a file specified by the `filename' parameter according to the `flags' parameter, which must be one of the following values: O_RDONLY (read-only) O_WRONLY (write-only) O_RDWR (read/write) In addition, `flags' may also be bitwise-or'd with any of the following: O_BINARY (open the file in binary mode) O_TEXT (open the file in text mode) O_CREAT (create the file if it does not exist) O_EXCL (fail if the file already exists) O_NOCTTY (do not make the device the controlling terminal) O_TRUNC (truncate the file if it exists) O_APPEND (open the file in append mode) O_NONBLOCK (open the file in non-blocking mode) Some of these flags make sense only when combined with other flags. For example, if O_EXCL is used, then O_CREAT must also be specified, otherwise unpredictable behavior may result. If O_CREAT is used for the `flags' parameter then the `mode' parameter must be present. `mode' specifies the permissions to use if a new file is created. The actual file permissions will be affected by the process's `umask' via `mode&~umask'. The `mode' parameter's value is constructed via bitwise-or of the following values: S_IRWXU (Owner has read/write/execute permission) S_IRUSR (Owner has read permission) S_IWUSR (Owner has write permission) S_IXUSR (Owner has execute permission) S_IRWXG (Group has read/write/execute permission) S_IRGRP (Group has read permission) S_IWGRP (Group has write permission) S_IXGRP (Group has execute permission) S_IRWXO (Others have read/write/execute permission) S_IROTH (Others have read permission) S_IWOTH (Others have write permission) S_IXOTH (Others have execute permission) Upon success `open' returns a file descriptor object (FD_Type), otherwise NULL is returned and `errno' is set. NOTES If you are not familiar with the `open' system call, then it is recommended that you use `fopen' instead and use the higher level stdio interface. SEE ALSO fopen, close, read, write, stat_file -------------------------------------------------------------- read SYNOPSIS Read from an open file descriptor USAGE UInt_Type read (FD_Type fd, Ref_Type buf, UInt_Type num) DESCRIPTION The `read' function attempts to read at most `num' bytes into the variable indicated by `buf' from the open file descriptor `fd'. It returns the number of bytes read, or -1 upon failure and sets `errno'. The number of bytes read may be less than `num', and will be zero if an attempt is made to read past the end of the file. NOTES `read' is a low-level function and may return -1 for a variety of reasons. For example, if non-blocking I/O has been specified for the open file descriptor and no data is available for reading then the function will return -1 and set `errno' to EAGAIN. SEE ALSO fread, open, close, write -------------------------------------------------------------- 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 -------------------------------------------------------------- getegid SYNOPSIS Get the effective group id of the current process USAGE Int_Type getegid () DESCRIPTION The `getegid' function returns the effective group ID of the current process. NOTES This function is not supported by all systems. SEE ALSO getgid, geteuid, setgid -------------------------------------------------------------- geteuid SYNOPSIS Get the effective user-id of the current process USAGE Int_Type geteuid () DESCRIPTION The `geteuid' function returns the effective user-id of the current process. NOTES This function is not supported by all systems. SEE ALSO getuid, setuid, setgid -------------------------------------------------------------- getgid SYNOPSIS Get the group id of the current process USAGE Integer_Type getgid () DESCRIPTION The `getgid' function returns the real group id of the current process. NOTES This function is not supported by all systems. SEE ALSO getpid, getppid -------------------------------------------------------------- getpid SYNOPSIS Get the current process id USAGE Integer_Type getpid () DESCRIPTION The `getpid' function returns the current process identification number. SEE ALSO getppid, getgid -------------------------------------------------------------- getppid SYNOPSIS Get the parent process id USAGE Integer_Type getppid () DESCRIPTION The `getpid' function returns the process identification number of the parent process. NOTES This function is not supported by all systems. SEE ALSO getpid, getgid -------------------------------------------------------------- getpriority SYNOPSIS Get a process's scheduling priority USAGE result = getpriority (which, who) DESCRIPTION The `setpriority' function may be used to obtain the kernel's scheduling priority for a process, process group, or a user depending upon the values of the `which' and `who' parameters. Specifically, if the value of `which' is `PRIO_PROCESS', then the value of `who' specifies the process id of the affected process. If `which' is `PRIO_PGRP', then `who' specifies a process group id. If `which' is `PRIO_USER', then the value of `who' is interpreted as a user id. For the latter two cases, where `which' refers to a set of processes, the value returned corresponds to the highest priority of a process in the set. A value of 0 may be used for who to denote the process id, process group id, or real user ID of the current process. Upon success, the function returns the specified priority value. If an error occurs, the function will return NULL with `errno' set accordingly. NOTES SEE ALSO setpriority, getpid, getppid -------------------------------------------------------------- getuid SYNOPSIS Get the user-id of the current process USAGE Int_Type getuid () DESCRIPTION The `getuid' function returns the user-id of the current process. NOTES This function is not supported by all systems. SEE ALSO getuid, getegid -------------------------------------------------------------- kill SYNOPSIS Send a signal to a process USAGE Integer_Type kill (Integer_Type pid, Integer_Type sig) DESCRIPTION This function may be used to send a signal given by the integer `sig' to the process specified by `pid'. The function returns zero upon success or `-1' upon failure setting `errno' accordingly. EXAMPLE The `kill' function may be used to determine whether or not a specific process exists: define process_exists (pid) { if (-1 == kill (pid, 0)) return 0; % Process does not exist return 1; } NOTES This function is not supported by all systems. SEE ALSO getpid -------------------------------------------------------------- mkfifo SYNOPSIS Create a named pipe USAGE Int_Type mkfifo (String_Type name, Int_Type mode) DESCRIPTION The `mkfifo' attempts to create a named pipe with the specified name and mode (modified by the process's umask). The function returns 0 upon success, or -1 and sets `errno' upon failure. NOTES Not all systems support the `mkfifo' function and even on systems that do implement the `mkfifo' system call, the underlying file system may not support the concept of a named pipe, e.g, an NFS filesystem. SEE ALSO stat_file -------------------------------------------------------------- setgid SYNOPSIS Set the group-id of the current process USAGE Int_Type setgid (Int_Type gid) DESCRIPTION The `setgid' function sets the effective group-id of the current process. It returns zero upon success, or -1 upon error and sets `errno' appropriately. NOTES This function is not supported by all systems. SEE ALSO getgid, setuid -------------------------------------------------------------- setpgid SYNOPSIS Set the process group-id USAGE Int_Type setpgid (Int_Type pid, Int_Type gid) DESCRIPTION The `setpgid' function sets the group-id `gid' of the process whose process-id is `pid'. If `pid' is 0, then the current process-id will be used. If `pgid' is 0, then the pid of the affected process will be used. If successful 0 will be returned, otherwise the function will return -1 and set `errno' accordingly. NOTES This function is not supported by all systems. SEE ALSO setgid, setuid -------------------------------------------------------------- setpriority SYNOPSIS Set the scheduling priority for a process USAGE Int_Type setpriority (which, who, prio) DESCRIPTION The `setpriority' function may be used to set the kernel's scheduling priority for a process, process group, or a user depending upon the values of the `which' and `who' parameters. Specifically, if the value of `which' is `PRIO_PROCESS', then the value of `who' specifies the process id of the affected process. If `which' is `PRIO_PGRP', then `who' specifies a process group id. If `which' is `PRIO_USER', then the value of `who' is interpreted as a user id. A value of 0 may be used for who to denote the process id, process group id, or real user ID of the current process. Upon sucess, the `setpriority' function returns 0. If an error occurs, -1 is returned and errno will be set accordingly. EXAMPLE The `getpriority' and `setpriority' functions may be used to implement a `nice' function for incrementing the priority of the current process as follows: define nice (dp) { variable p = getpriority (PRIO_PROCESS, 0); if (p == NULL) return -1; variable s = setpriority (PRIO_PROCESS, 0, p + dp); if (s == -1) return -1; return getpriority (PRIO_PROCESS, 0); } NOTES Priority values are sometimes called "nice" values. The actual range of priority values is system dependent but commonly range from -20 to 20, with -20 being the highest scheduling priority, and +20 the lowest. SEE ALSO getpriority, getpid -------------------------------------------------------------- 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 system_intr, new_process, popen -------------------------------------------------------------- system_intr SYNOPSIS Execute a shell command USAGE Integer_Type system_intr (String_Type cmd) DESCRIPTION The `system_intr' function performs the same task as the `system' function, except that the `SIGINT' signal will not be ignored by the calling process. This means that if a S-Lang script calls `system_intr' function, and Ctrl-C is pressed, both the command invoked by the `system_intr' function and the script will be interrupted. In contrast, if the command were invoked using the `system' function, only the command called by it would be interrupted, but the script would continue executing. SEE ALSO system, new_process, popen -------------------------------------------------------------- umask SYNOPSIS Set the file creation mask USAGE Int_Type umask (Int_Type m) DESCRIPTION The `umask' function sets the file creation mask to the value of `m' and returns the previous mask. SEE ALSO stat_file -------------------------------------------------------------- uname SYNOPSIS Get the system name USAGE Struct_Type uname () DESCRIPTION The `uname' function returns a structure containing information about the operating system. The structure contains the following fields: sysname (Name of the operating system) nodename (Name of the node within the network) release (Release level of the OS) version (Current version of the release) machine (Name of the hardware) NOTES Not all systems support this function. SEE ALSO getenv -------------------------------------------------------------- qualifier SYNOPSIS Get the value of a qualifier USAGE value = qualifier (String_Type name [,default_value]) DESCRIPTION This function may be used to get the value of a qualifer. If the specified qualifier does not exist, `NULL' will be returned, unless a default value has been provided. EXAMPLE define echo (text) { variable fp = qualifier ("out", stdout); () = fputs (text, fp); } echo ("hello"); % writes hello to stdout echo ("hello"; out=stderr); % writes hello to stderr NOTES Since `NULL' is a valid value for a qualifier, this function is unable to distinguish between a non-existent qualifier and one whose value is `NULL'. If such a distinction is important, the `qualifier_exists' function can be used. For example, define echo (text) { variable fp = stdout; if (qualifier_exists ("use_stderr")) fp = stderr; () = fputs (text, fp); } echo ("hello"; use_stderr); % writes hello to stderr In this case, no value was provided for the `use_stderr' qualifier: it exists but has a value of `NULL'. SEE ALSO qualifier_exists, __qualifiers -------------------------------------------------------------- __qualifiers SYNOPSIS Get the active set of qualifiers USAGE Struct_Type __qualifiers () DESCRIPTION This function returns the set of qualifiers associated with the current execution context. If qualifiers are active, then the result is a structure representing the names of the qualifiers and their corresponding values. Otherwise `NULL' will be returned. One of the main uses of this function is to pass the current set of qualifiers to another another function. For example, consider a plotting application with a function called called `lineto' that sets the pen-color before drawing the line to the specified point: define lineto (x, y) { % The color may be specified by a qualifier, defaulting to black variable color = qualifier ("color", "black"); set_pen_color (color); . . } The `lineto' function permits the color to be specified by a qualifier. Now consider a function that make use of lineto to draw a line segment between two points: define line_segment (x0, y0, x1, y1) { moveto (x0, y0); lineto (x1, y1 ; color=qualifier("color", "black")); } line_segment (1,1, 10,10; color="blue"); Note that in this implementation of `line_segment', the `color' qualifier was explicitely passed to the `lineto' function. However, this technique does not scale well. For example, the `lineto' function might also take a qualifer that specifies the line-style, to be used as line_segment (1,1, 10,10; color="blue", linestyle="solid"); But the above implementation of `line_segment' does not pass the `linestyle' qualifier. In such a case, it is preferable to pass all the qualifiers, e.g., define line_segment (x0, y0, x1, y1) { moveto (x0, y0); lineto (x1, y1 ;; __qualifiers()); } Note the use of the double-semi colon in the `lineto' statement. This tells the parser that the qualifiers are specified by a structure-valued argument and not a set of name-value pairs. SEE ALSO qualifier, qualifier_exists -------------------------------------------------------------- qualifier_exists SYNOPSIS Check for the existence of a qualifier USAGE Int_Type qualifier_exists (String_Type name) DESCRIPTION This function will return 1 if a qualifier of the specified name exists, or 0 otherwise. SEE ALSO qualifier, __qualifiers -------------------------------------------------------------- rline_bolp SYNOPSIS Test of the editing point is at the beginning of the line USAGE Int_Type rline_bolp() DESCRIPTION The `rline_bolp' function returns a non-zero value if the current editing position is at the beginning of the line. NOTES This function is part of the S-Lang readline interface. SEE ALSO rline_eolp, rline_get_point, rline_get_line -------------------------------------------------------------- rline_eolp SYNOPSIS Test of the editing point is at the end of the line USAGE Int_Type rline_eolp() DESCRIPTION The `rline_bolp' function returns a non-zero value if the current editing position is at the end of the line. NOTES This function is part of the S-Lang readline interface. SEE ALSO rline_bolp, rline_get_point, rline_get_line -------------------------------------------------------------- rline_call SYNOPSIS Invoke an internal readline function USAGE rline_call (String_Type func) DESCRIPTION Not all of the readline functions are available directly from the S-Lang interpreter. For example, the "deleol" function, which deletes through the end of the line may be executed using rline_call("deleol"); See the documentation for the `rline_setkey' function for a list of internal functions that may be invoked by `rline_call'. NOTES This function is part of the S-Lang readline interface. SEE ALSO rline_setkey, rline_del, rline_ins -------------------------------------------------------------- rline_del SYNOPSIS Delete a specified number of characters at the current position USAGE rline_del(Int_Type n) DESCRIPTION This function delete a specified number of characters at the current editing position. If the number `n' is less than zero, then the previous `n' characters will be deleted. Otherwise, the next `n' characters will be deleted. NOTES This function is part of the S-Lang readline interface. SEE ALSO rline_ins, rline_setkey -------------------------------------------------------------- rline_get_edit_width SYNOPSIS Get the width of the readline edit window USAGE Int_Type rline_get_edit_width () DESCRIPTION This function returns the width of the edit window. For `slsh', this number corresponds to the width of the terminal window. NOTES This function is part of the S-Lang readline interface. SEE ALSO rline_ins -------------------------------------------------------------- rline_get_history SYNOPSIS Retrieve the readline history USAGE Array_Type rline_get_history () DESCRIPTION This function returns the readline edit history as an array of strings. NOTES This function is part of the S-Lang readline interface. SEE ALSO rline_set_line -------------------------------------------------------------- rline_get_line SYNOPSIS Get a copy of the line being edited USAGE String_Type rline_get_line () DESCRIPTION This function returns the current edit line. NOTES This function is part of the S-Lang readline interface. SEE ALSO rline_set_line, rline_get_history -------------------------------------------------------------- rline_get_point SYNOPSIS Get the current editing position USAGE Int_Type rline_get_point () DESCRIPTION The `rline_get_point' function returns the byte-offset of the current editing position. NOTES This function is part of the S-Lang readline interface. SEE ALSO rline_set_point -------------------------------------------------------------- rline_getkey SYNOPSIS Obtain the next byte in the readline input stream USAGE Int_Type rline_getkey () This function returns the next byte in the readline input stream. If no byte is available, the function will wait until one is. DESCRIPTION NOTES This function is part of the S-Lang readline interface. SEE ALSO rline_input_pending, rline_setkey -------------------------------------------------------------- rline_input_pending SYNOPSIS Test to see if readline input is available for reading USAGE Int_Type rline_input_pending (Int_Type tsecs) DESCRIPTION This function returns a non-zero value if readline input is available to be read. If none is immediately available, it will wait for up to `tsecs' tenths of a second for input before returning. NOTES This function is part of the S-Lang readline interface. SEE ALSO rline_getkey -------------------------------------------------------------- rline_ins SYNOPSIS Insert a string at the current editing point USAGE rline_ins (String_Type text) DESCRIPTION This function inserts the specified string into the line being edited. NOTES This function is part of the S-Lang readline interface. SEE ALSO rline_set_line, rline_del -------------------------------------------------------------- rline_set_history SYNOPSIS Replace the current history list with a new one USAGE rline_set_history (Array_Type lines) DESCRIPTION The `rline_set_history' function replaces the current history by the specified array of strings. NOTES This function is part of the S-Lang readline interface. SEE ALSO rline_get_history -------------------------------------------------------------- rline_set_line SYNOPSIS Replace the current line with a new one USAGE rline_set_line (String_Type line) DESCRIPTION The `rline_set_line' function replaces the line being edited by the specified one. NOTES This function is part of the S-Lang readline interface. SEE ALSO rline_get_line -------------------------------------------------------------- rline_set_point SYNOPSIS Move the current editing position to another USAGE rline_set_point (Int_Type ofs) DESCRIPTION The `rline_set_point' function sets the editing point to the specified byte-offset from the beginning of the line. NOTES This function is part of the S-Lang readline interface. SEE ALSO rline_get_point -------------------------------------------------------------- rline_setkey SYNOPSIS Bind a key in the readline keymap to a function USAGE rline_setkey (func, keyseq) DESCRIPTION The `rline_setkey' function binds the function `func' to the specified key sequence `keyseq'. The value of `func' may be either a reference to a S-Lang function, or a string giving the name of an internal readline function. Functions that are internal to the readline interface include: bdel Delete the previous character bol Move to the beginning of the line complete The command line completion function del Delete the character at the current position delbol Delete to the beginning of the line deleol Delete through the end of the line down Goto the next line in the history enter Return to the caller of the readline function eol Move to the end of the line kbd_quit Abort editing of the current line left Move left one character quoted_insert Insert the next byte into the line redraw Redraw the line right Move right one character self_insert Insert the byte that invoked the function trim Remove whitespace about the current position up Goto the previous line in the history NOTES This function is part of the S-Lang readline interface. SEE ALSO rline_unsetkey -------------------------------------------------------------- rline_unsetkey SYNOPSIS Unset a key binding from the readline keymap USAGE rline_unsetkey (String_Type keyseq) DESCRIPTION The `rline_unsetkey' function unbinds the specified key sequence from the readline keymap. NOTES This function is part of the S-Lang readline interface. SEE ALSO rline_setkey -------------------------------------------------------------- rline_set_list_completions_callback SYNOPSIS Set a callback function to display the list of completions USAGE rline_set_list_completions_callback (Ref_Type func) DESCRIPTION This function sets the S-Lang function that is to be used to display the list of possible completions for current word at the readline prompt. The callback function must be defined to accept a single parameter representing an array of completion strings. EXAMPLE This callback function writes the completions using the message functions: private define display_completions (strings) { variable str; vmessage ("There are %d completions:\n", length(strings)); foreach str (strings) vmessage ("%s\n", str); } rline_set_list_completions_callback (&display_completions); NOTES SEE ALSO rline_set_completion_callback -------------------------------------------------------------- rline_set_completion_callback SYNOPSIS Set the function to be used for completion at the readline prompt USAGE rline_set_completion_callback (Ref_Type func) DESCRIPTION This function sets the callback function to be used for completion at the readline prompt. The callback function must be defined to accept two values, the first being a string containing the text of the line being edited, and an integer giving the position of the byte-offset into the string where completion was requested. The callback function must return two values: an array giving the list of possible completion strings, and an integer giving the byte offset into the string of the start of the text to be completed. EXAMPLE See completion-callback function defined in the `slsh' library file `rline/complete.sl'. NOTES This function is part of the S-Lang readline interface. SEE ALSO rline_set_list_completions_callback -------------------------------------------------------------- alarm SYNOPSIS Schedule an alarm signal USAGE alarm (UInt_Type secs [, Ref_Type secs_remaining]) DESCRIPTION The `alarm' function schedules the delivery of a SIGALRM signal in `secs' seconds. Any previously scheduled alarm will be canceled. If `secs' is zero, then no new alarm will be scheduled. If the second argument is present, then it must be a reference to a variable whose value will be set upon return to the number of seconds remaining for a previously scheduled alarm to take place. EXAMPLE This example shows demonstrates how the `alarm' function may be used to read from a file within a specified amount of time: define sigalrm_handler (sig) { throw ReadError, "Read timed out"; } define read_or_timeout (secs) { variable line, e; variable fp = fopen ("/dev/tty", "r"); signal (SIGALRM, &sigalrm_handler); alarm (secs); try (e) { () = fputs ("Enter some text> ", stdout); () = fflush (stdout); if (-1 == fgets (&line, fp)) line = NULL; } catch IOError: { message (e.message); line = NULL; } return line; } NOTES Some operating systems may implement the `sleep' function using `alarm'. As a result, it is not a good idea to mix calls to `alarm' and `sleep'. The default action for SIGALRM is to terminate the process. Hence, if `alarm' is called it is wise to establish a signal handler for `SIGALRM'. SEE ALSO signal, sleep -------------------------------------------------------------- signal SYNOPSIS Establish a signal handler USAGE signal (Int_Type sig, Ref_Type func [,Ref_Type old_func]) DESCRIPTION The `signal' function assigns the signal handler represented by `func' to the signal `sig'. Here `func' is usually reference to a function that takes an integer argument (the signal) and returns nothing, e.g., define signal_handler (sig) { return; } Alternatively, `func' may be given by one of the symbolic constants SIG_IGN or SIG_DFL to indicate that the signal is to be ignored or given its default action, respectively. The first parameter, `sig', specifies the signal to be handled. The actual supported values vary with the OS. Common values on Unix include `SIGHUP', `SIGINT', and `SIGTERM'. If a third argument is present, then it must be a reference to a variable whose value will be set to the value of the previously installed handler. EXAMPLE This example establishes a handler for `SIGTSTP'. static define sig_suspend (); % forward declaration static define sig_suspend (sig) { message ("SIGTSTP received-- stopping"); signal (sig, SIG_DFL); () = kill (getpid(), SIGSTOP); message ("Resuming"); signal (sig, &sig_suspend); } signal (SIGTSTP, &sig_suspend); NOTES Currently the signal interface is supported only on systems that implement signals according to the POSIX standard. Once a signal has been received, it will remain blocked until after the signal handler has completed. This is the reason SIGSTOP was used in the above signal handler instead of SIGTSTP. SEE ALSO alarm, sigsuspend, sigprocmask -------------------------------------------------------------- sigprocmask SYNOPSIS Change the list of currently blocked signals USAGE sigprocmask (Int_Type how, Array_Type mask [,Ref_Type old_mask]) DESCRIPTION The `sigprocmask' function may be used to change the list of signals that are currently blocked. The first parameter indicates how this is accomplished. Specifically, `how' must be one of the following values: SIG_BLOCK, SIG_UNBLOCK, or SIG_SETMASK. If `how' is SIG_BLOCK, then the set of blocked signals will be the union the current set with the values specified in the `mask' argument. If `how' is SIG_UNBLOCK, then the signals specified by the `mask' parameter will be removed from the currently blocked set. If `how' is SIG_SETMASK, then the set of blocked signals will be set to those given by the `mask'. If a third argument is present, then it must be a reference to a variable whose value will be set to the previous signal mask. SEE ALSO signal, sigsuspend, alarm -------------------------------------------------------------- sigsuspend SYNOPSIS Suspend the process until a signal is delivered USAGE sigsuspend ([Array_Type signal_mask]) DESCRIPTION The sigsuspend function suspends the current process until a signal is received. An optional array argument may be passed to the function to specify a list of signals that should be temporarily blocked while waiting for a signal. EXAMPLE The following example pauses the current process for 10 seconds while blocking the SIGHUP and SIGINT signals. static variable Tripped; define sigalrm_handler (sig) { Tripped = 1; } signal (SIGALRM, &sigalrm_handler); Tripped = 0; alarm (10); while (Tripped == 0) sigsuspend ([SIGHUP, SIGINT]); Note that in this example the call to `sigsuspend' was wrapped in a while-loop. This was necessary because there is no guarantee that another signal would not cause `sigsuspend' to return. SEE ALSO signal, alarm, sigprocmask -------------------------------------------------------------- dup SYNOPSIS Duplicate the value at the top of the stack USAGE dup () DESCRIPTION This function returns an exact duplicate of the object on top of the stack. For some objects such as arrays or structures, it creates a new reference to the object. However, for simple scalar S-Lang types such as strings, integers, and doubles, it creates a new copy of the object. SEE ALSO pop, typeof -------------------------------------------------------------- exch SYNOPSIS Exchange two items on the stack USAGE exch () DESCRIPTION The `exch' swaps the two top items on the stack. SEE ALSO pop, _stk_reverse, _stk_roll -------------------------------------------------------------- pop SYNOPSIS Discard an item from the stack USAGE pop () DESCRIPTION The `pop' function removes the top item from the stack. SEE ALSO _pop_n, __pop_args -------------------------------------------------------------- __pop_args SYNOPSIS Remove n function arguments from the stack USAGE args = __pop_args(Integer_Type n) DESCRIPTION This function, together with the companion function `__push_args', is useful for creating a function that takes a variable number of arguments, as well as passing the arguments of one function to another function. `__pop_args' removes the specified number of values from the stack and returns them as an array of structures of the corresponding length. Each structure in the array consists of a single field called `value', which represents the value of the argument. EXAMPLE Consider the following function. It prints all its arguments to `stdout' separated by spaces: define print_args () { variable i; variable args = __pop_args (_NARGS); for (i = 0; i < _NARGS; i++) { () = fputs (string (args[i].value), stdout); () = fputs (" ", stdout); } () = fputs ("\n", stdout); () = fflush (stdout); } Now consider the problem of defining a function called `ones' that returns a multi-dimensional array with all the elements set to 1. For example, `ones(10)' should return a 1-d array of 10 ones, whereas `ones(10,20)' should return a 10x20 array. define ones () { !if (_NARGS) return 1; variable a; a = __pop_args (_NARGS); return @Array_Type (Integer_Type, [__push_args (a)]) + 1; } Here, `__push_args' was used to push the arguments passed to the `ones' function onto the stack to be used when dereferencing Array_Type. NOTES This function has been superseded by the `__pop_list' function, which returns the objects as a list instead of an array of structures. SEE ALSO __push_args, __pop_list, __push_list, typeof, _pop_n -------------------------------------------------------------- __pop_list SYNOPSIS Convert items on the stack to a List_Type USAGE List_Type = __pop_list (Int_Type n) DESCRIPTION This function removes a specified number of items from the stack and converts returns them in the form of a list. EXAMPLE define print_args () { variable list = __pop_list (_NARGS); variable i; _for i (0, length(list)-1, 1) { vmessage ("arg[%d]: %S", i, list[i]); } } NOTES SEE ALSO __push_list -------------------------------------------------------------- _pop_n SYNOPSIS Remove objects from the stack USAGE _pop_n (Integer_Type n); DESCRIPTION The `_pop_n' function removes the specified number of objects from the top of the stack. SEE ALSO _stkdepth, pop -------------------------------------------------------------- _print_stack SYNOPSIS Print the values on the stack. USAGE _print_stack () DESCRIPTION This function dumps out what is currently on the S-Lang stack. It does not alter the stack and it is usually used for debugging purposes. SEE ALSO _stkdepth, string, message -------------------------------------------------------------- __push_args SYNOPSIS Move n function arguments onto the stack USAGE __push_args (Struct_Type args); DESCRIPTION This function together with the companion function `__pop_args' is useful for the creation of functions that take a variable number of arguments. See the description of `__pop_args' for more information. NOTES This function has been superseded by the `__push_list' function. SEE ALSO __pop_args, __push_list, __pop_list, typeof, _pop_n -------------------------------------------------------------- __push_list SYNOPSIS Push the elements of a list to the stack USAGE __push_list (List_Type list) DESCRIPTION This function pushes the elements of a list to the stack. EXAMPLE private define list_to_array (list) { return [__push_list (list)]; } SEE ALSO __pop_list -------------------------------------------------------------- _stkdepth USAGE Get the number of objects currently on the stack SYNOPSIS Integer_Type _stkdepth () DESCRIPTION The `_stkdepth' function returns number of items on the stack. SEE ALSO _print_stack, _stk_reverse, _stk_roll -------------------------------------------------------------- _stk_reverse SYNOPSIS Reverse the order of the objects on the stack USAGE _stk_reverse (Integer_Type n) DESCRIPTION The `_stk_reverse' function reverses the order of the top `n' items on the stack. SEE ALSO _stkdepth, _stk_roll -------------------------------------------------------------- _stk_roll SYNOPSIS Roll items on the stack USAGE _stk_roll (Integer_Type n) DESCRIPTION This function may be used to alter the arrangement of objects on the stack. Specifically, if the integer `n' is positive, the top `n' items on the stack are rotated up. If `n' is negative, the top `abs(n)' items on the stack are rotated down. EXAMPLE If the stack looks like: item-0 item-1 item-2 item-3 where `item-0' is at the top of the stack, then `_stk_roll(-3)' will change the stack to: item-2 item-0 item-1 item-3 NOTES This function only has an effect if `abs(n) > 1'. SEE ALSO _stkdepth, _stk_reverse, _pop_n, _print_stack -------------------------------------------------------------- clearerr SYNOPSIS Clear the error of a file stream USAGE clearerr (File_Type fp DESCRIPTION The `clearerr' function clears the error and end-of-file flags associated with the open file stream `fp'. SEE ALSO ferror, feof, fopen -------------------------------------------------------------- fclose SYNOPSIS Close a file USAGE Integer_Type fclose (File_Type fp) DESCRIPTION The `fclose' function may be used to close an open file pointer `fp'. Upon success it returns zero, and upon failure it sets `errno' and returns `-1'. Failure usually indicates a that the file system is full or that `fp' does not refer to an open file. NOTES Many C programmers call `fclose' without checking the return value. The S-Lang language requires the programmer to explicitly handle any value returned by a function. The simplest way to handle the return value from `fclose' is to call it via: () = fclose (fp); SEE ALSO fopen, fgets, fflush, pclose, errno -------------------------------------------------------------- fdopen SYNOPSIS Convert a FD_Type file descriptor to a stdio File_Type object USAGE File_Type fdopen (FD_Type, String_Type mode) DESCRIPTION The `fdopen' function creates and returns a stdio File_Type object from the open FD_Type descriptor `fd'. The `mode' parameter corresponds to the `mode' parameter of the `fopen' function and must be consistent with the mode of the descriptor `fd'. The function returns NULL upon failure and sets `errno'. NOTES Since the stdio File_Type object created by this function is derived from the FD_Type descriptor, the FD_Type is regarded as more fundamental than the File_Type object. This means that the descriptor must be in scope while the File_Type object is used. In particular, if the descriptor goes out of scope, the descriptor will get closed causing I/O to the File_Type object to fail, e.g., fd = open ("/path/to/file", O_RDONLY); fp = fdopen (fd); fd = 0; % This will cause the FD_Type descriptor to go out of % scope. Any I/O on fp will now fail. Calling the `fclose' function on the File_Type object will cause the underlying descriptor to close. Any stdio File_Type object created by the `fdopen' function will remain associated with the FD_Type descriptor, unless the object is explicitly removed via `fclose'. This means that code such as fd = open (...); loop (50) { fp = fdopen (fd, ...); . . } will result in 50 File_Type objects attached to `fd' after the loop has terminated. SEE ALSO fileno, fopen, open, close, fclose, dup_fd -------------------------------------------------------------- feof SYNOPSIS Get the end-of-file status USAGE Integer_Type feof (File_Type fp) DESCRIPTION This function may be used to determine the state of the end-of-file indicator of the open file descriptor `fp'. It returns zero if the indicator is not set, or non-zero if it is. The end-of-file indicator may be cleared by the `clearerr' function. SEE ALSO ferror, clearerr, fopen -------------------------------------------------------------- ferror SYNOPSIS Determine the error status of an open file descriptor USAGE Integer_Type ferror (File_Type fp) DESCRIPTION This function may be used to determine the state of the error indicator of the open file descriptor `fp'. It returns zero if the indicator is not set, or non-zero if it is. The error indicator may be cleared by the `clearerr' function. SEE ALSO feof, clearerr, fopen -------------------------------------------------------------- fflush SYNOPSIS Flush an output stream USAGE Integer_Type fflush (File_Type fp) DESCRIPTION The `fflush' function may be used to update the stdio _output_ stream specified by `fp'. It returns 0 upon success, or -1 upon failure and sets `errno' accordingly. In particular, this function will fail if `fp' does not represent an open output stream, or if `fp' is associated with a disk file and there is insufficient disk space. EXAMPLE This example illustrates how to use the `fflush' function without regard to the return value: () = fputs ("Enter value> ", stdout); () = fflush (stdout); SEE ALSO fopen, fclose -------------------------------------------------------------- fgets SYNOPSIS Read a line from a file USAGE Integer_Type fgets (SLang_Ref_Type ref, File_Type fp) DESCRIPTION `fgets' reads a line from the open file specified by `fp' and places the characters in the variable whose reference is specified by `ref'. It returns -1 if `fp' is not associated with an open file or an attempt was made to read at the end the file; otherwise, it returns the number of characters read. EXAMPLE The following example returns the lines of a file via a linked list: define read_file (file) { variable buf, fp, root, tail; variable list_type = struct { text, next }; root = NULL; fp = fopen(file, "r"); if (fp == NULL) 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 fgetslines, fopen, fclose, fputs, fread, error -------------------------------------------------------------- fgetslines SYNOPSIS Read lines as an array from an open file USAGE String_Type[] fgetslines (File_Type fp [,Int_Type num]) DESCRIPTION The `fgetslines' function reads lines a specified number of lines as an array of strings from the file associated with the file pointer `fp'. If the number of lines to be read is left unspecified, the function will return the rest of the lines in the file. If the file is empty, an empty string array will be returned. The function returns NULL upon error. EXAMPLE The following function returns the number of lines in a file: define count_lines_in_file (file) { variable fp, lines; fp = fopen (file, "r"); if (fp == NULL) return -1; lines = fgetslines (fp); if (lines == NULL) return -1; return length (lines); } Note that the file was implicitly closed when the variable `fp' goes out of scope (in the case, when the function returns). SEE ALSO fgets, fread, fopen, fputslines -------------------------------------------------------------- fopen SYNOPSIS Open a file USAGE File_Type fopen (String_Type f, String_Type m) DESCRIPTION The `fopen' function opens a file `f' according to the mode string `m'. Allowed values for `m' are: "r" Read only "w" Write only "a" Append "r+" Reading and writing at the beginning of the file. "w+" Reading and writing. The file is created if it does not exist; otherwise, it is truncated. "a+" Reading and writing at the end of the file. The file is created if it does not already exist. In addition, the mode string can also include the letter `'b'' as the last character to indicate that the file is to be opened in binary mode. Upon success, `fopen' returns a File_Type object which is meant to be used by other operations that require an open file pointer. Upon failure, the function returns NULL. EXAMPLE The following function opens a file in append mode and writes a string to it: define append_string_to_file (file, str) { variable fp = fopen (file, "a"); if (fp == NULL) throw OpenError, "$file could not be opened"$; () = fputs (string, fp); () = fclose (fp); } Note that the return values from `fputs' and `fclose' were ignored. NOTES There is no need to explicitly close a file opened with `fopen'. If the returned File_Type object goes out of scope, the interpreter will automatically close the file. However, explicitly closing a file with `fclose' and checking its return value is recommended. SEE ALSO fclose, fgets, fputs, popen -------------------------------------------------------------- fprintf SYNOPSIS Create and write a formatted string to a file USAGE Int_Type fprintf (File_Type fp, String_Type fmt, ...) DESCRIPTION `fprintf' formats the objects specified by the variable argument list according to the format `fmt' and write the result to the open file pointer `fp'. The format string obeys the same syntax and semantics as the `sprintf' format string. See the description of the `sprintf' function for more information. `fprintf' returns the number of bytes written to the file, or -1 upon error. SEE ALSO fputs, printf, fwrite, message -------------------------------------------------------------- fputs SYNOPSIS Write a string to an open stream USAGE Integer_Type fputs (String_Type s, File_Type fp) DESCRIPTION The `fputs' function writes the string `s' to the open file pointer `fp'. It returns -1 upon failure and sets `errno', otherwise it returns the length of the string. EXAMPLE The following function opens a file in append mode and uses the `fputs' function to write to it. define append_string_to_file (str, file) { variable fp; fp = fopen (file, "a"); if (fp == NULL) throw OpenError, "Unable to open $file"$; if ((-1 == fputs (s, fp)) or (-1 == fclose (fp))) throw WriteError, "Error writing to $file"; } NOTES One must not disregard the return value from the `fputs' function. Doing so may lead to a stack overflow error. To write an object that contains embedded null characters, use the `fwrite' function. SEE ALSO fclose, fopen, fgets, fwrite -------------------------------------------------------------- fputslines SYNOPSIS Write an array of strings to an open file USAGE Int_Type fputslines (String_Type[]a, File_Type fp) DESCRIPTION The `fputslines' function writes an array of strings to the specified file pointer. It returns the number of elements successfully written. Any NULL elements in the array will be skipped. EXAMPLE if (length (lines) != fputslines (fp, lines)) throw WriteError; SEE ALSO fputs, fgetslines, fopen -------------------------------------------------------------- fread SYNOPSIS Read binary data from a file USAGE UInt_Type fread (Ref_Type b, DataType_Type t, UInt_Type n, File_Type fp) DESCRIPTION The `fread' function may be used to read `n' objects of type `t' from an open file pointer `fp'. Upon success, it returns the number of objects read from the file and places the objects in variable specified by `b'. Upon error or end-of-file, it returns -1 and sets `errno' accordingly. If more than one object is read from the file, those objects will be placed in an array of the appropriate size. EXAMPLE The following example illustrates how to read 50 integers from a file: define read_50_ints_from_a_file (file) { variable fp, n, buf; fp = fopen (file, "rb"); if (fp == NULL) throw OpenError; n = fread (&buf, Int_Type, 50, fp); if (n == -1) throw ReadError, "fread failed"; () = fclose (fp); return buf; } NOTES Use the `pack' and `unpack' functions to read data with a specific byte-ordering. The `fread_bytes' function may be used to read a specified number of bytes in the form of a binary string (`BString_Type'). If an attempt is made to read at the end of a file, the function will return -1. To distinguish this condition from a system error, the `feof' function should be used. This distinction is particularly important when reading from a socket or pipe. SEE ALSO fread_bytes, fwrite, fgets, feof, ferror, fopen, pack, unpack -------------------------------------------------------------- fread_bytes SYNOPSIS Read bytes from a file as a binary-string USAGE UInt_Type fread_bytes (Ref_Type b, UInt_Type n, File_Type fp) DESCRIPTION The `fread_bytes' function may be used to read `n' bytes from from an open file pointer `fp'. Upon success, it returns the number of bytes read from the file and assigns to the variable attached to the reference `b' a binary string formed from the bytes read. Upon error or end of file, the function returns -1 and sets `errno' accordingly. NOTES Use the `pack' and `unpack' functions to read data with a specific byte-ordering. SEE ALSO fread, fwrite, fgets, fopen, pack, unpack -------------------------------------------------------------- fseek SYNOPSIS Reposition a stdio stream USAGE Integer_Type fseek (File_Type fp, LLong_Type ofs, Integer_Type whence DESCRIPTION The `fseek' function may be used to reposition the file position pointer associated with the open file stream `fp'. Specifically, it moves the pointer `ofs' bytes relative to the position indicated by `whence'. If `whence' is set to one of the symbolic constants SEEK_SET, SEEK_CUR, or SEEK_END, the offset is relative to the start of the file, the current position indicator, or end-of-file, respectively. The function returns 0 upon success, or -1 upon failure and sets `errno' accordingly. EXAMPLE define rewind (fp) { if (0 == fseek (fp, 0, SEEK_SET)) return; vmessage ("rewind failed, reason: %s", errno_string (errno)); } SEE ALSO ftell, fopen -------------------------------------------------------------- ftell SYNOPSIS Obtain the current position in an open stream USAGE LLong_Type ftell (File_Type fp) DESCRIPTION The ftell function may be used to obtain the current position in the stream associated with the open file pointer `fp'. It returns the position of the pointer measured in bytes from the beginning of the file. Upon error, it returns `-1' and sets `errno' accordingly. SEE ALSO fseek, fopen -------------------------------------------------------------- fwrite SYNOPSIS Write binary data to a file USAGE UInt_Type fwrite (b, File_Type fp) DESCRIPTION The `fwrite' function may be used to write the object represented by `b' to an open file. If `b' is a string or an array, the function will attempt to write all elements of the object to the file. It returns the number of elements successfully written, otherwise it returns -1 upon error and sets `errno' accordingly. EXAMPLE The following example illustrates how to write an integer array to a file. In this example, `fp' is an open file descriptor: variable a = [1:50]; % 50 element integer array if (50 != fwrite (a, fp)) throw WriteError; Here is how to write the array one element at a time: variable ai, a = [1:50]; foreach ai (a) { if (1 != fwrite(ai, fp)) throw WriteError; } NOTES Not all data types may be supported the `fwrite' function. It is supported by all vector, scalar, and string objects. SEE ALSO fread, fputs, fopen, pack, unpack -------------------------------------------------------------- pclose SYNOPSIS Close a process pipe USAGE Integer_Type pclose (File_Type fp) DESCRIPTION The `pclose' function waits for the process associated with `fp' to exit and the returns the exit status of the command. SEE ALSO pclose, fclose -------------------------------------------------------------- popen SYNOPSIS Open a pipe to a process USAGE File_Type popen (String_Type cmd, String_Type mode) DESCRIPTION The `popen' function executes a process specified by `cmd' and opens a unidirectional pipe to the newly created process. The `mode' indicates whether or not the pipe is open for reading or writing. Specifically, if `mode' is `"r"', then the pipe is opened for reading, or if `mode' is `"w"', then the pipe will be open for writing. Upon success, a File_Type pointer will be returned, otherwise the function failed and NULL will be returned. NOTES This function is not available on all systems. The `process' module's `new_process' function provides a much more secure and powerful interface to process I/O. SEE ALSO new_process, pclose, fopen -------------------------------------------------------------- printf SYNOPSIS Create and write a formatted string to stdout USAGE Int_Type printf (String_Type fmt, ...) DESCRIPTION `printf' formats the objects specified by the variable argument list according to the format `fmt' and write the result to `stdout'. This function is equivalent to `fprintf' used with the `stdout' file pointer. See `fprintf' for more information. `printf' returns the number of bytes written or -1 upon error. NOTES Many C programmers do not check the return status of the `printf' C library function. Make sure that if you do not care about whether or not the function succeeds, then code it as in the following example: () = printf ("%s laid %d eggs\n", chicken_name, num_egg); SEE ALSO fputs, fprintf, fwrite, message -------------------------------------------------------------- count_char_occurances SYNOPSIS Count the number of occurances of a character in a string USAGE UInt_Type count_char_occurances (str, ch) DESCRIPTION This function returns the number of times the specified character `ch' occurs in the string `str'. NOTES If UTF-8 mode is in effect, then the character may correspond to more than one byte. In such a case, the function returns the number of such byte-sequences in the string. To count actual bytes, use the `count_byte_occurances' function. SEE ALSO count_byte_occurances -------------------------------------------------------------- create_delimited_string SYNOPSIS Concatenate strings using a delimiter USAGE String_Type create_delimited_string (delim, s_1, s_2, ..., s_n, n) String_Type delim, s_1, ..., s_n Int_Type n DESCRIPTION `create_delimited_string' performs a concatenation operation on the `n' strings `s_1', ...,`s_n', using the string `delim' as a delimiter. The resulting string is equivalent to one obtained via s_1 + delim + s_2 + delim + ... + s_n EXAMPLE create_delimited_string ("/", "user", "local", "bin", 3); will produce `"usr/local/bin"'. NOTES New code should use the `strjoin' function, which performs a similar task. SEE ALSO strjoin, is_list_element, extract_element, strchop, strcat -------------------------------------------------------------- extract_element SYNOPSIS Extract the nth element of a string with delimiters USAGE String_Type extract_element (String_Type list, Int_Type nth, Int_Type delim) DESCRIPTION The `extract_element' function may be used to extract the `nth' substring of a string delimited by the character given by the `delim' parameter. If the string contains fewer than the requested substring, the function will return NULL. Substring elements are numbered from 0. EXAMPLE The expression extract_element ("element 0, element 1, element 2", 1, ',') returns the string `" element 1"', whereas extract_element ("element 0, element 1, element 2", 1, ' ') returns `"0,"'. The following function may be used to compute the number of elements in the list: define num_elements (list, delim) { variable nth = 0; while (NULL != extract_element (list, nth, delim)) nth++; return nth; } Alternatively, the `strchop' function may be more useful. In fact, `extract_element' may be expressed in terms of the function `strchop' as define extract_element (list, nth, delim) { list = strchop(list, delim, 0); if (nth >= length (list)) return NULL; else return list[nth]; } and the `num_elements' function used above may be recoded more simply as: define num_elements (list, delim) { return length (strchop (length, delim, 0)); } NOTES New code should make use of the `List_Type' object for lists. SEE ALSO is_list_element, is_substr, strtok, strchop, create_delimited_string -------------------------------------------------------------- glob_to_regexp SYNOPSIS Convert a globbing expression to a regular expression USAGE String_Type glob_to_regexp (String_Type g) DESCRIPTION This function may be used to convert a so-called globbing expression to a regular expression. A globbing expression is frequently used for matching filenames where '?' represents a single character and '*' represents 0 or more characters. NOTES The `slsh' program that is distributed with the S-Lang library includes a function called `glob' that is a wrapper around `glob_to_regexp' and `listdir'. It returns a list of filenames matching a globbing expression. SEE ALSO string_match, listdir -------------------------------------------------------------- is_list_element SYNOPSIS Test whether a delimited string contains a specific element USAGE Int_Type is_list_element (String_Type list, String_Type elem, Int_Type delim) DESCRIPTION The `is_list_element' function may be used to determine whether or not a delimited list of substring, `list', contains the element `elem'. If `elem' is not an element of `list', the function will return zero, otherwise, it returns 1 plus the matching element number. EXAMPLE The expression is_list_element ("element 0, element 1, element 2", "0,", ' '); returns `2' since `"0,"' is element number one of the list (numbered from zero). SEE ALSO extract_element, is_substr, create_delimited_string -------------------------------------------------------------- is_substr SYNOPSIS Test for a specified substring within a string USAGE Int_Type is_substr (String_Type a, String_Type b) DESCRIPTION This function may be used to determine if `a' contains the string `b'. If it does not, the function returns 0; otherwise it returns the position of the first occurrence of `b' in `a' expressed in terms of characters, not bytes. NOTES This function regards the first character of a string to be given by a position value of 1. The distinction between characters and bytes is significant in UTF-8 mode. SEE ALSO substr, string_match, strreplace -------------------------------------------------------------- make_printable_string SYNOPSIS Format a string suitable for parsing USAGE String_Type make_printable_string(String_Type str) DESCRIPTION This function formats a string in such a way that it may be used as an argument to the `eval' function. The resulting string is identical to `str' except that it is enclosed in double quotes and the backslash, newline, control, and double quote characters are expanded. SEE ALSO eval, str_quote_string -------------------------------------------------------------- Sprintf SYNOPSIS Format objects into a string (deprecated) USAGE String_Type Sprintf (String_Type format, ..., Int_Type n) DESCRIPTION This function performs a similar task as the `sprintf' function but requires an additional argument that specifies the number of items to format. For this reason, the `sprintf' function should be used. SEE ALSO sprintf, string, sscanf, vmessage -------------------------------------------------------------- sprintf SYNOPSIS Format objects into a string USAGE String_Type sprintf (String fmt, ...) DESCRIPTION The `sprintf' function formats a string from a variable number of arguments according to according to the format specification string `fmt'. The format string is a C library `sprintf' style format descriptor. Briefly, the format string may consist of ordinary characters (not including the `%' character), which are copied into the output string as-is, and conversion specification sequences introduced by the `%' character. The number of additional arguments passed to the `sprintf' function must be consistent with the number required by the format string. The `%' character in the format string starts a conversion specification that indicates how an object is to be formatted. Usually the percent character is followed immediately by a conversion specification character. However, it may optionally be followed by flag characters, field width characters, and precision modifiers, as described below. The character immediately following the `%' character may be one or more of the following flag characters: - Use left-justification # Use alternate form for formatting. 0 Use 0 padding + Preceed a number by a plus or minus sign. (space) Use a blank instead of a plus sign. The flag characters (if any) may be followed by an optional field width specification string represented by one or more digit characters. If the size of the formatted object is less than the field width, it will be right-justified in the specified field width, unless the `-' flag was given, in which case it will be left justified. If the next character in the control sequence is a period, then it introduces a precision specification sequence. The precision is given by the digit characters following the period. If none are given the precision is taken to be 0. The meaning of the precision specifier depends upon the type of conversion: For integer conversions, it gives the minimum number digits to appear in the output. For `e' and `f' floating point conversions, it gives the number of digits to appear after the decimal point. For the `g' floating point conversion, it gives the maximum number of significant digits to appear. Finally for the `s' and `S' conversions it specifies the maximum number of characters to be copied to the output string. The next character in the sequence may be a modifier that controls the size of object to be formatted. It may consist of the following characters: h This character is ignored in the current implementation. l The integer is be formatted as a long integer, or a character as a wide character. Finally the conversion specification sequence ends with the conversion specification character that describes how the object is to be formatted: s as a string f as a floating point number e as a float using exponential form, e.g., 2.345e08 g format as e or g, depending upon its value c as a character b as a byte % a literal percent character d as a signed decimal integer u as an unsigned decimal integer o as an octal integer X as hexadecimal S convert object to a string and format accordingly The `S' conversion specifier is a S-Lang extension which will cause the corresponding object to be converted to a string using the `string' function, and then converted as `s'. formatted as string. In fact, `sprintf("%S",x)' is equivalent to `sprintf("%s",string(x))'. EXAMPLE sprintf("%s","hello") ===> "hello" sprintf("%s %s","hello", "world") ===> "hello world" sprintf("Agent %.3d",7) ===> "Agent 007" sprintf("%S",PI) ===> "3.14159" sprintf("%g",PI) ===> "3.14159" sprintf("%.2g",PI) ===> "3.1" sprintf("%.2e",PI) ===> "3.14e+00" sprintf("%.2f",PI) ===> "3.14" sprintf("|% 8.2f|",PI) ===> "| 3.14|" sprintf("|%-8.2f|",PI) ===> "|3.14 |" sprintf("|%+8.2f|",PI) ===> "| +3.14|" sprintf("%S",{1,2,3}) ===> "List_Type with 3 elements" sprintf("%S",1+2i) ===> "(1 + 2i)" NOTES The `set_float_format' function controls the format for the `S' conversion of floating point numbers. SEE ALSO string, sscanf, message, pack -------------------------------------------------------------- sscanf SYNOPSIS Parse a formatted string USAGE Int_Type sscanf (s, fmt, r1, ... rN) String_Type s, fmt; Ref_Type r1, ..., rN DESCRIPTION The `sscanf' function parses the string `s' according to the format `fmt' and sets the variables whose references are given by `r1', ..., `rN'. The function returns the number of references assigned, or throws an exception upon error. The format string `fmt' consists of ordinary characters and conversion specifiers. A conversion specifier begins with the special character `%' and is described more fully below. A white space character in the format string matches any amount of whitespace in the input string. Parsing of the format string stops whenever a match fails. The `%' character is used to denote a conversion specifier whose general form is given by `%[*][width][type]format' where the brackets indicate optional items. If `*' is present, then the conversion will be performed but no assignment to a reference will be made. The `width' specifier specifies the maximum field width to use for the conversion. The `type' modifier is used to indicate the size of the object, e.g., a short integer, as follows. If _type_ is given as the character `h', then if the format conversion is for an integer (`dioux'), the object assigned will be a short integer. If _type_ is `l', then the conversion will be to a long integer for integer conversions, or to a double precision floating point number for floating point conversions. The format specifier is a character that specifies the conversion: % Matches a literal percent character. No assignment is performed. d Matches a signed decimal integer. D Matches a long decimal integer (equiv to `ld') u Matches an unsigned decimal integer U Matches an unsigned long decimal integer (equiv to `lu') i Matches either a hexadecimal integer, decimal integer, or octal integer. I Equivalent to `li'. x Matches a hexadecimal integer. X Matches a long hexadecimal integer (same as `lx'). e,f,g Matches a decimal floating point number (Float_Type). E,F,G Matches a double precision floating point number, same as `lf'. s Matches a string of non-whitespace characters (String_Type). c Matches one character. If width is given, width characters are matched. n Assigns the number of characters scanned so far. [...] Matches zero or more characters from the set of characters enclosed by the square brackets. If '^' is given as the first character, then the complement set is matched. EXAMPLE Suppose that `s' is `"Coffee: (3,4,12.4)"'. Then n = sscanf (s, "%[a-zA-Z]: (%d,%d,%lf)", &item, &x, &y, &z); will set `n' to 4, `item' to `"Coffee"', `x' to 3, `y' to 4, and `z' to the double precision number `12.4'. However, n = sscanf (s, "%s: (%d,%d,%lf)", &item, &x, &y, &z); will set `n' to 1, `item' to `"Coffee:"' and the remaining variables will not be assigned. SEE ALSO sprintf, unpack, string, atof, int, integer, string_matches -------------------------------------------------------------- strbytelen SYNOPSIS Get the number of bytes in a string USAGE Int_Type strbytelen (String_Type s) DESCRIPTION This function returns the number of bytes in a string. In UTF-8 mode, this value is generally different from the number of characters in a string. For the latter information, the `strlen' or `strcharlen' functions should be used. SEE ALSO strlen, strcharlen, length -------------------------------------------------------------- strbytesub SYNOPSIS Replace a byte with another in a string. USAGE String_Type strsub (String_Type s, Int_Type pos, UChar_Type b) DESCRIPTION The `strbytesub' function may be be used to substitute the byte `b' for the byte at byte position `pos' of the string `s'. The resulting string is returned. NOTES The first byte in the string `s' is specified by `pos' equal to 1. This function uses byte semantics, not character semantics. SEE ALSO strsub, is_substr, strreplace, strbytelen -------------------------------------------------------------- strcat SYNOPSIS Concatenate strings USAGE String_Type strcat (String_Type a_1, ..., String_Type a_N) DESCRIPTION The `strcat' function concatenates its N string arguments `a_1', ... `a_N' together and returns the result. EXAMPLE strcat ("Hello", " ", "World"); produces the string `"Hello World"'. NOTES This function is equivalent to the binary operation `a_1+...+a_N'. However, `strcat' is much faster making it the preferred method to concatenate strings. SEE ALSO sprintf, strjoin -------------------------------------------------------------- strcharlen SYNOPSIS Get the number of characters in a string including combining characters USAGE Int_Type strcharlen (String_Type s) DESCRIPTION The `strcharlen' function returns the number of characters in a string. If the string contains combining characters, then they are also counted. Use the `strlen' function to obtain the character count ignoring combining characters. SEE ALSO strlen, strbytelen -------------------------------------------------------------- strchop SYNOPSIS Chop or split a string into substrings. USAGE String_Type[] strchop (String_Type str, Int_Type delim, Int_Type quote) DESCRIPTION The `strchop' function may be used to split-up a string `str' that consists of substrings delimited by the character specified by `delim'. If the integer `quote' is non-zero, it will be taken as a quote character for the delimiter. The function returns the substrings as an array. EXAMPLE The following function illustrates how to sort a comma separated list of strings: define sort_string_list (a) { variable i, b, c; b = strchop (a, ',', 0); i = array_sort (b); b = b[i]; % rearrange % Convert array back into comma separated form return strjoin (b, ","); } SEE ALSO strchopr, strjoin, strtok -------------------------------------------------------------- strchopr SYNOPSIS Chop or split a string into substrings. USAGE String_Type[] strchopr (String_Type str, String_Type delim, String_Type quote) DESCRIPTION This routine performs exactly the same function as `strchop' except that it returns the substrings in the reverse order. See the documentation for `strchop' for more information. SEE ALSO strchop, strtok, strjoin -------------------------------------------------------------- strcmp SYNOPSIS Compare two strings USAGE Int_Type strcmp (String_Type a, String_Type b) DESCRIPTION The `strcmp' function may be used to perform a case-sensitive string comparison, in the lexicographic sense, on strings `a' and `b'. It returns 0 if the strings are identical, a negative integer if `a' is less than `b', or a positive integer if `a' is greater than `b'. EXAMPLE The `strup' function may be used to perform a case-insensitive string comparison: define case_insensitive_strcmp (a, b) { return strcmp (strup(a), strup(b)); } NOTES One may also use one of the binary comparison operators, e.g., `a > b'. 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, str_delete_chars -------------------------------------------------------------- string_match SYNOPSIS Match a string against a regular expression USAGE Int_Type string_match(String_Type str, String_Type pat, Int_Type pos) DESCRIPTION The `string_match' function returns zero if `str' does not match regular expression specified by `pat'. This function performs the match starting at byte-offset `pos' in the string `str' (numbered from 1). This function returns the position in bytes (numbered from 1) of the start of the match in `str'. The exact substring matched may be found using `string_match_nth'. NOTES Positions in the string are specified using byte-offsets not character offsets. The value returned by this function is measured from the beginning of the string `str'. The function is not yet UTF-8 aware. If possible, consider using the `pcre' module for better, more sophisticated regular expressions. SEE ALSO string_matches, string_match_nth, strcmp, strncmp -------------------------------------------------------------- string_match_nth SYNOPSIS Get the result of the last call to string_match USAGE (Int_Type pos, Int_Type len) = string_match_nth(Int_Type nth) DESCRIPTION The `string_match_nth' function returns two integers describing the result of the last call to `string_match'. It returns both the zero-based byte-position of the `nth' submatch and the length of the match. By convention, `nth' equal to zero means the entire match. Otherwise, `nth' must be an integer with a value 1 through 9, and refers to the set of characters matched by the `nth' regular expression enclosed by the pairs `\(, \)'. EXAMPLE Consider: variable matched, pos, len; matched = string_match("hello world", "\([a-z]+\) \([a-z]+\)"R, 1); if (matched) (pos, len) = string_match_nth(2); This will set `matched' to 1 since a match will be found at the first byte position, `pos' to 6 since `w' is offset 6 bytes from the beginning of the string, and `len' to 5 since `"world"' is 5 bytes long. NOTES The position offset is _not_ affected by the value of the offset parameter to the `string_match' function. For example, if the value of the last parameter to the `string_match' function had been 3, `pos' would still have been set to 6. The `string_matches' function may be used as an alternative to `string_match_nth'. SEE ALSO string_match, string_matches -------------------------------------------------------------- string_matches SYNOPSIS Match a string against a regular expression and return the matches USAGE String_Type[] string_matches(String_Type str, String_Type pat, Int_Type pos) DESCRIPTION The `string_matches' function combines the functionality of `string_match' and `string_match_nth'. Like `string_match', it matches the test string `str' against the regular expression `pat'. If the string does not match the pattern the function will return NULL. Otherwise, the function will return an array of strings whose `ith' element is the string that corresponds to the return value of the `string_match_nth' function. EXAMPLE strs = string_matches ("p0.5keV_27deg.dat", "p\([0-9.]+\)keV_\([0-9.]+\)deg\.dat"R, 1); % ==> strs[0] = "p0.5keV_27deg.dat" % strs[1] = "0.5" % strs[2] = "27" strs = string_matches ("q0.5keV_27deg.dat", "p\([0-9.]+\)keV_\([0-9.]+\)deg\.dat"R, 1); % ==> strs = NULL NOTES The function is not yet UTF-8 aware. If possible, consider using the `pcre' module for better, more sophisticated regular expressions. SEE ALSO string_match, string_match_nth, strcmp, strncmp -------------------------------------------------------------- strjoin SYNOPSIS Concatenate elements of a string array USAGE String_Type strjoin (Array_Type a, String_Type delim) DESCRIPTION The `strjoin' function operates on an array of strings by joining successive elements together separated with 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 strchop, strcat -------------------------------------------------------------- strlen SYNOPSIS Compute the length of a string USAGE Int_Type strlen (String_Type a) DESCRIPTION The `strlen' function may be used to compute the character length of a string ignoring the presence of combining characters. The `strcharlen' function may be used to count combining characters as distinct characters. For byte-semantics, use the `strbytelen' function. EXAMPLE After execution of variable len = strlen ("hello"); `len' will have a value of `5'. SEE ALSO strbytelen, strcharlen, bstrlen, length, substr -------------------------------------------------------------- strlow SYNOPSIS Convert a string to lowercase USAGE String_Type strlow (String_Type s) DESCRIPTION The `strlow' function takes a string `s' and returns another string identical to `s' except that all upper case characters that are contained in `s' are converted converted to lower case. EXAMPLE The function define Strcmp (a, b) { return strcmp (strlow (a), strlow (b)); } performs a case-insensitive comparison operation of two strings by converting them to lower case first. SEE ALSO strup, tolower, strcmp, strtrim, define_case -------------------------------------------------------------- strnbytecmp SYNOPSIS Compare the first n bytes of two strings USAGE Int_Type strnbytecmp (String_Type a, String_Type b, Int_Type n) DESCRIPTION This function compares the first `n' bytes of the strings `a' and `b'. See the documentation for `strcmp' for information about the return value. SEE ALSO strncmp, strncharcmp, strcmp -------------------------------------------------------------- strncharcmp SYNOPSIS Compare the first n characters of two strings USAGE Int_Type strncharcmp (String_Type a, String_Type b, Int_Type n) DESCRIPTION This function compares the first `n' characters of the strings `a' and `b' counting combining characters as distinct characters. See the documentation for `strcmp' for information about the return value. SEE ALSO strncmp, strnbytecmp, strcmp -------------------------------------------------------------- strncmp SYNOPSIS Compare the first few characters of two strings USAGE Int_Type strncmp (String_Type a, String_Type b, Int_Type n) DESCRIPTION This function behaves like `strcmp' except that it compares only the first `n' characters in the strings `a' and `b'. See the documentation for `strcmp' for information about the return value. In counting characters, combining characters are not counted, although they are used in the comparison. Use the `strncharcmp' function if you want combining characters to be included in the character count. The `strnbytecmp' function should be used to compare bytes. EXAMPLE The expression strcmp ("apple", "appliance", 3); will return zero since the first three characters match. NOTES This function uses character semantics. SEE ALSO strcmp, strlen, strncharcmp, strnbytecmp -------------------------------------------------------------- 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 occurrences of `b' in `a' with `c'. If the integer `max_n' is positive, then the first `max_n' occurrences of `b' in `a' will be replaced. Otherwise, if `max_n' is negative, then the last `abs(max_n)' occurrences will be replaced. The function returns the resulting string and an integer indicating how many replacements were made. EXAMPLE The following function illustrates how `strreplace' may be used to remove all occurrences 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, Int_Type pos, Int_Type ch) DESCRIPTION The `strsub' function may be used to substitute the character `ch' for the character at character position `pos' of the string `s'. The resulting string is returned. EXAMPLE define replace_spaces_with_comma (s) { variable n; while (n = is_substr (s, " "), n) s = strsub (s, n, ','); return s; } For uses such as this, the `strtrans' function is a better choice. NOTES The first character in the string `s' is specified by `pos' equal to 1. This function uses character semantics, not byte semantics. SEE ALSO is_substr, strreplace, strlen -------------------------------------------------------------- strtok SYNOPSIS Extract tokens from a string USAGE String_Type[] strtok (String_Type str [,String_Type white]) DESCRIPTION `strtok' breaks the string `str' into a series of tokens and returns them as an array of strings. If the second parameter `white' is present, then it specifies the set of characters that are to be regarded as whitespace when extracting the tokens, and may consist of the whitespace characters or a range of such characters. If the first character of `white' is `'^'', then the whitespace characters consist of all characters except those in `white'. For example, if `white' is `" \t\n,;."', then those characters specify the whitespace characters. However, if `white' is given by `"^a-zA-Z0-9_"', then any character is a whitespace character except those in the ranges `a-z', `A-Z', `0-9', and the underscore character. To specify the hyphen character as a whitespace character, then it should be the first character of the whitespace string. In addition to ranges, the whitespace specifier may also include character classes: \w matches a unicode "word" character, taken to be alphanumeric. \a alphabetic character, excluding digits \s matches whitespace \l matches lowercase \u matches uppercase \d matches a digit \\ matches a backslash \^ matches a ^ character If the second parameter is not present, then it defaults to `"\s"'. EXAMPLE The following example may be used to count the words in a text file: define count_words (file) { variable fp, line, count; fp = fopen (file, "r"); if (fp == NULL) return -1; count = 0; while (-1 != fgets (&line, fp)) { line = strtok (line, "^\\a"); count += length (line); } () = fclose (fp); return count; } Here a word was assumed to consist only of alphabetic characters. SEE ALSO strchop, strcompress, strjoin -------------------------------------------------------------- strtrans SYNOPSIS Replace characters in a string USAGE String_Type strtrans (str, old_set, new_set) String_Type str, old_set, new_set; DESCRIPTION The `strtrans' function may be used to replace all the characters from the set `old_set' with the corresponding characters from `new_set' in the string `str'. If `new_set' is empty, then the characters in `old_set' will be removed from `str'. If `new_set' is not empty, then `old_set' and `new_set' must be commensurate. Each set may consist of character ranges such as `A-Z' and character classes: \w matches a unicode "word" character, taken to be alphanumeric. \a alphabetic character, excluding digits \s matches whitespace \l matches lowercase \u matches uppercase \d matches a digit \7 matches any 7bit ascii character \\ matches a backslash \^ matches a ^ character If the first character of a set is `^' then the set is taken to be the complement set. EXAMPLE str = strtrans (str, "\\u", "\\l"); % lower-case str str = strtrans (str, "^0-9", " "); % Replace anything but 0-9 by space str = strtrans (str, "\\^0-9", " "); % Replace '^' and 0-9 by a space SEE ALSO strreplace, strtrim, strup, strlow -------------------------------------------------------------- strtrim SYNOPSIS Remove whitespace from the ends of a string USAGE String_Type strtrim (String_Type s [,String_Type w]) DESCRIPTION The `strtrim' function removes all leading and trailing whitespace characters from the string `s' and returns the result. The optional second parameter specifies the set of whitespace characters. If the argument is not present, then the set defaults to `"\s"'. The whitespace specification may consist of character ranges such as `A-Z' and character classes: \w matches a unicode "word" character, taken to be alphanumeric. \a alphabetic character, excluding digits \s matches whitespace \l matches lowercase \u matches uppercase \d matches a digit \\ matches a backslash \^ matches a ^ character If the first character of a set is `^' then the set is taken to be the complement set. SEE ALSO strtrim_beg, strtrim_end, strcompress -------------------------------------------------------------- strtrim_beg SYNOPSIS Remove leading whitespace from a string USAGE String_Type strtrim_beg (String_Type s [,String_Type w]) DESCRIPTION The `strtrim_beg' function removes all leading whitespace characters from the string `s' and returns the result. The optional second parameter specifies the set of whitespace characters. See the documentation for the `strtrim' function form more information about the whitespace parameter. SEE ALSO strtrim, strtrim_end, strcompress -------------------------------------------------------------- strtrim_end SYNOPSIS Remove trailing whitespace from a string USAGE String_Type strtrim_end (String_Type s [,String_Type w]) DESCRIPTION The `strtrim_end' function removes all trailing whitespace characters from the string `s' and returns the result. The optional second parameter specifies the set of whitespace characters. See the documentation for the `strtrim' function form more information about the whitespace parameter. SEE ALSO strtrim, strtrim_beg, strcompress -------------------------------------------------------------- strup SYNOPSIS Convert a string to uppercase USAGE String_Type strup (String_Type s) DESCRIPTION The `strup' function takes a string `s' and returns another string identical to `s' except that all lower case characters that contained in `s' are converted to upper case. EXAMPLE The function define Strcmp (a, b) { return strcmp (strup (a), strup (b)); } performs a case-insensitive comparison operation of two strings by converting them to upper case first. SEE ALSO strlow, toupper, strcmp, strtrim, define_case, strtrans -------------------------------------------------------------- str_delete_chars SYNOPSIS Delete characters from a string USAGE String_Type str_delete_chars (String_Type str, String_Type del_set DESCRIPTION This function may be used to delete the set of characters specified by `del_set' from the string `str'. The result is returned. The set of characters to be deleted may include ranges such as `A-Z' and characters classes: \w matches a unicode "word" character, taken to be alphanumeric. \a alphabetic character, excluding digits \s matches whitespace \l matches lowercase \u matches uppercase \d matches a digit \\ matches a backslash \^ matches a ^ character If the first character of `del_set' is `^', then the set is taken to be the complement of the remaining string. EXAMPLE str = str_delete_chars (str, "^A-Za-z"); will remove all characters except `A-Z' and `a-z' from `str'. Similarly, str = str_delete_chars (str, "^\\a"); will remove all but the alphabetic characters. SEE ALSO strtrans, strreplace, strcompress -------------------------------------------------------------- str_quote_string SYNOPSIS Escape characters in a string. USAGE String_Type str_quote_string(String_Type str, String_Type qlis, Int_Type quote) DESCRIPTION The `str_quote_string' returns a string identical to `str' except that all characters contained in the string `qlis' are escaped with the `quote' character, including the quote character itself. This function is useful for making a string that can be used in a regular expression. EXAMPLE Execution of the statements node = "Is it [the coat] really worth $100?"; tag = str_quote_string (node, "\\^$[]*.+?", '\\'); will result in `tag' having the value: Is it \[the coat\] really worth \$100\? SEE ALSO str_uncomment_string, make_printable_string -------------------------------------------------------------- str_replace SYNOPSIS Replace a substring of a string (deprecated) USAGE Int_Type str_replace (String_Type a, String_Type b, String_Type c) DESCRIPTION The `str_replace' function replaces the first occurrence of `b' in `a' with `c' and returns an integer that indicates whether a replacement was made. If `b' does not occur in `a', zero is returned. However, if `b' occurs in `a', a non-zero integer is returned as well as the new string resulting from the replacement. NOTES This function has been superceded by `strreplace'. It should no longer be used. SEE ALSO strreplace -------------------------------------------------------------- str_uncomment_string SYNOPSIS Remove comments from a string USAGE String_Type str_uncomment_string(String_Type s, String_Type beg, String_Type end) DESCRIPTION This function may be used to remove simple forms of comments from a string `s'. The parameters, `beg' and `end', are strings of equal length whose corresponding characters specify the begin and end comment characters, respectively. It returns the uncommented string. EXAMPLE The expression str_uncomment_string ("Hello (testing) 'example' World", "'(", "')") returns the string `"Hello World"'. NOTES This routine does not handle multicharacter comment delimiters and it assumes that comments are not nested. SEE ALSO str_quote_string, str_delete_chars, strtrans -------------------------------------------------------------- substr SYNOPSIS Extract a substring from a string USAGE String_Type substr (String_Type s, Int_Type n, Int_Type len) DESCRIPTION The `substr' function returns a substring with character length `len' of the string `s' beginning at the character position `n'. If `len' is `-1', the entire length of the string `s' will be used for `len'. The first character of `s' is given by `n' equal to 1. EXAMPLE substr ("To be or not to be", 7, 5); returns `"or no"' NOTES In many cases it is more convenient to use array indexing rather than the `substr' function. In fact, if UTF-8 mode is not in effect, `substr(s,i+1,strlen(s))' is equivalent to `s[[i:]]'. Array indexing uses byte-semantics, not character semantics assumed by the `substr' function. SEE ALSO is_substr, substrbytes, strlen -------------------------------------------------------------- substrbytes SYNOPSIS Extract a byte sequence from a string USAGE String_Type substrbytes (String_Type s, Int_Type n, Int_Type len) DESCRIPTION The `substrbytes' function returns a substring with byte length `len' of the string `s' beginning at the byte position `n', counting from 1. If `len' is `-1', the entire byte-length of the string `s' will be used for `len'. The first byte of `s' is given by `n' equal to 1. EXAMPLE substrbytes ("To be or not to be", 7, 5); returns `"or no"' NOTES In many cases it is more convenient to use array indexing rather than the `substr' function. In fact `substrbytes(s,i+1,-1)' is equivalent to `s[[i:]]'. The function `substr' may be used if character semantics are desired. SEE ALSO substr, strbytelen -------------------------------------------------------------- __add_binary SYNOPSIS Extend a binary operation to a user defined type USAGE __add_binary(op, return_type, binary_funct, lhs_type, rhs_type) String_Type op; Ref_Type binary_funct; DataType_Type return_type, lhs_type, rhs_type; DESCRIPTION The `__add_binary' function is used to specify a function to be called when a binary operation takes place between specified data types. The first parameter indicates the binary operator and must be one of the following: "+", "-", "*", "/", "==", "!=", ">", ">=", "<", "<=", "^", "or", "and", "&", "|", "xor", "shl", "shr", "mod" The second parameter (`binary_funct') specifies the function to be called when the binary function takes place between the types `lhs_type' and `rhs_type'. The `return_type' parameter stipulates the return values of the function and the data type of the result of the binary operation. The data type for `lhs_type' or `rhs_type' may be left unspecified by using Any_Type for either of these values. However, at least one of the parameters must correspond to a user-defined datatype. EXAMPLE This example defines a vector data type and extends the "*" operator to the new type: typedef struct { x, y, z } Vector_Type; define vector (x, y, z) { variable v = @Vector_Type; v.x = x; v.y = y; v.z = z; return v; } static define vector_scalar_mul (v, a) { return vector (a*v.x, a*v.y, a*v.z); } static define scalar_vector_mul (a, v) { return vector_scalar_mul (v, a); } static define dotprod (v1,v2) { return v1.x*v2.x + v1.y*v2.y + v1.z*v2.z; } __add_binary ("*", Vector_Type, &scalar_vector_mul, Any_Type, Vector_Type); __add_binary ("*", Vector_Type, &scalar_vector_mul, Any_Type, Vector_Type); __add_binary ("*", Double_Type, &dotprod, Vector_Type, Vector_Type); SEE ALSO __add_unary, __add_string, __add_destroy -------------------------------------------------------------- __add_string SYNOPSIS Specify a string representation for a user-defined type USAGE __add_string (DataType_Type user_type, Ref_Type func) DESCRIPTION The `__add_string' function specifies a function to be called when a string representation is required for the specified user-defined datatype. EXAMPLE Consider the `Vector_Type' object defined in the example for the `__add_binary' function. static define vector_string (v) { return sprintf ("[%S,%S,%S]", v.x, v.y, v.z); } __add_string (Vector_Type, &vector_string); Then v = vector (3, 4, 5); vmessage ("v=%S", v); will generate the message: v=[3,4,5] SEE ALSO __add_unary, __add_binary, __add_destroy, __add_typecast -------------------------------------------------------------- __add_typecast SYNOPSIS Add a typecast-function for a user-defined type USAGE __add_typecast (DataType_Type user_type, DataType_Type totype, Ref_Type func) DESCRIPTION The `__add_typecast' function specifies a function to be called to typecast the user-defined type to an object of type `totype'. The function must be defined to take a single argument (the user-type to be converted) and must return an object of type `totype'. SEE ALSO __add_unary, __add_binary, __add_destroy, __add_string -------------------------------------------------------------- __add_unary SYNOPSIS Extend a unary operator to a user-defined type USAGE __add_unary (op, return_type, unary_func, user_type) String_Type op; Ref_Type unary_func; DataType_Type return_type, user_type; DESCRIPTION The `__add_unary' function is used to define the action of an unary operation on a user-defined type. The first parameter `op' must be a valid unary operator "-", "not", "~" or one of the following: "++", "--", "abs", "sign", "sqr", "mul2", "_ispos", "_isneg", "_isnonneg", The third parameter, `unary_func' specifies the function to be called to carry out the specified unary operation on the data type `user_type'. The result of the operation is indicated by the value of the `return_type' parameter and must also be the return type of the unary function. EXAMPLE The example for the `__add_binary' function defined a `Vector_Type' object. Here, the unary `"-"' and `"abs"' operators are extended to this type: static define vector_chs (v) { variable v1 = @Vector_Type; v1.x = -v.x; v1.y = -v.y; v1.z = -v.z; return v1; } static define vector_abs (v) { return sqrt (v.x*v.x + v.y*v.y + v.z*v.z); } __add_unary ("-", Vector_Type, &vector_chs, Vector_Type); __add_unary ("abs", Double_Type, &vector_abs, Vector_Type); SEE ALSO __add_binary, __add_string, __add_destroy -------------------------------------------------------------- get_struct_field SYNOPSIS Get the value associated with a structure field USAGE x = get_struct_field (Struct_Type s, String field_name) DESCRIPTION The `get_struct_field' function gets the value of the field whose name is specified by `field_name' of the structure `s'. EXAMPLE The following example illustrates how this function may be used to to print the value of a structure. define print_struct (s) { variable name; foreach (get_struct_field_names (s)) { name = (); value = get_struct_field (s, name); vmessage ("s.%s = %s\n", name, string(value)); } } SEE ALSO set_struct_field, get_struct_field_names, array_info -------------------------------------------------------------- get_struct_field_names SYNOPSIS Retrieve the field names associated with a structure USAGE String_Type[] = get_struct_field_names (Struct_Type s) DESCRIPTION The `get_struct_field_names' function returns an array of strings whose elements specify the names of the fields of the struct `s'. EXAMPLE The following example illustrates how the `get_struct_field_names' function may be used to print the value of a structure. define print_struct (s) { variable name, value; foreach (get_struct_field_names (s)) { name = (); value = get_struct_field (s, name); vmessage ("s.%s = %s\n", name, string (value)); } } SEE ALSO _push_struct_field_values, get_struct_field -------------------------------------------------------------- is_struct_type SYNOPSIS Determine whether or not an object is a structure USAGE Integer_Type is_struct_type (X) DESCRIPTION The `is_struct_type' function returns 1 if the parameter refers to a structure or a user-defined type. If the object is neither, 0 will be returned. SEE ALSO typeof, _typeof, _is_struct_type -------------------------------------------------------------- _push_struct_field_values SYNOPSIS Push the values of a structure's fields onto the stack USAGE Integer_Type num = _push_struct_field_values (Struct_Type s) 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 -------------------------------------------------------------- set_struct_field SYNOPSIS Set the value associated with a structure field USAGE set_struct_field (s, field_name, field_value) Struct_Type s; String_Type field_name; Generic_Type field_value; DESCRIPTION The `set_struct_field' function sets the value of the field whose name is specified by `field_name' of the structure `s' to `field_value'. SEE ALSO get_struct_field, get_struct_field_names, set_struct_fields, array_info -------------------------------------------------------------- set_struct_fields SYNOPSIS Set the fields of a structure USAGE set_struct_fields (Struct_Type s, ...) DESCRIPTION The `set_struct_fields' function may be used to set zero or more fields of a structure. The fields are set in the order in which they were created when the structure was defined. EXAMPLE variable s = struct { name, age, height }; set_struct_fields (s, "Bill", 13, 64); SEE ALSO set_struct_field, get_struct_field_names -------------------------------------------------------------- ctime SYNOPSIS Convert a calendar time to a string USAGE String_Type ctime(Long_Type secs) DESCRIPTION This function returns a string representation of the time as given by `secs' seconds since 00:00:00 UTC, Jan 1, 1970. SEE ALSO time, strftime, _time, localtime, gmtime -------------------------------------------------------------- gmtime SYNOPSIS Break down a time in seconds to the GMT timezone USAGE Struct_Type gmtime (Long_Type secs) DESCRIPTION The `gmtime' function is exactly like `localtime' except that the values in the structure it returns are with respect to GMT instead of the local timezone. See the documentation for `localtime' for more information. NOTES On systems that do not support the `gmtime' C library function, this function is the same as `localtime'. SEE ALSO localtime, _time, mktime -------------------------------------------------------------- localtime SYNOPSIS Break down a time in seconds to the local timezone USAGE Struct_Type localtime (Long_Type secs) DESCRIPTION The `localtime' function takes a parameter `secs' representing the number of seconds since 00:00:00, January 1 1970 UTC and returns a structure containing information about `secs' in the local timezone. The structure contains the following Int_Type fields: `tm_sec' The number of seconds after the minute, normally in the range 0 to 59, but can be up to 61 to allow for leap seconds. `tm_min' The number of minutes after the hour, in the range 0 to 59. `tm_hour' The number of hours past midnight, in the range 0 to 23. `tm_mday' The day of the month, in the range 1 to 31. `tm_mon' The number of months since January, in the range 0 to 11. `tm_year' The number of years since 1900. `tm_wday' The number of days since Sunday, in the range 0 to 6. `tm_yday' The number of days since January 1, in the range 0 to 365. `tm_isdst' A flag that indicates whether daylight saving time is in effect at the time described. The value is positive if daylight saving time is in effect, zero if it is not, and negative if the information is not available. SEE ALSO gmtime, _time, ctime, mktime -------------------------------------------------------------- mktime SYNOPSIS Convert a time-structure to seconds USAGE secs = mktime (Struct_Type tm) DESCRIPTION The `mktime' function is essentially the inverse of the `localtime' function. See the documentation for that function for more details. SEE ALSO localtime, gmtime, _time -------------------------------------------------------------- strftime SYNOPSIS Format a date and time string USAGE str = strftime (String_Type format [,Struct_Type tm]) DESCRIPTION The `strftime' creates a date and time string according to a specified format. If called with a single argument, the current local time will be used as the reference time. If called with two arguments, the second argument specifies the reference time, and must be a structure with the same fields as the structure returned by the `localtime' function. The format string may be composed of one or more of the following format descriptors: %A full weekday name (Monday) %a abbreviated weekday name (Mon) %B full month name (January) %b abbreviated month name (Jan) %c standard date and time representation %d day-of-month (01-31) %H hour (24 hour clock) (00-23) %I hour (12 hour clock) (01-12) %j day-of-year (001-366) %M minute (00-59) %m month (01-12) %p local equivalent of AM or PM %S second (00-59) %U week-of-year, first day sunday (00-53) %W week-of-year, first day monday (00-53) %w weekday (0-6, sunday is 0) %X standard time representation %x standard date representation %Y year with century %y year without century (00-99) %Z timezone name %% percent sign as well as any others provided by the C library. The actual values represented by the format descriptors are locale-dependent. EXAMPLE message (strftime ("Today is %A, day %j of the year")); tm = localtime (0); message (strftime ("Unix time 0 was on a %A", tm)); SEE ALSO localtime, time -------------------------------------------------------------- _tic SYNOPSIS Reset the CPU timer USAGE _tic () DESCRIPTION The `_tic' function resets the internal CPU timer. The `_toc' may be used to read this timer. See the documentation for the `_toc' function for more information. SEE ALSO _toc, times, tic, toc -------------------------------------------------------------- tic SYNOPSIS Reset the interval timer USAGE void tic () DESCRIPTION The `tic' function resets the internal interval timer. The `toc' may be used to read the interval timer. EXAMPLE The tic/toc functions may be used to measure execution times. For example, at the `slsh' prompt, they may be used to measure the speed of a loop: slsh> tic; loop (500000); toc; 0.06558 NOTES On Unix, this timer makes use of the C library `gettimeofday' function. SEE ALSO toc, times -------------------------------------------------------------- _time SYNOPSIS Get the current calendar time in seconds USAGE Long_Type _time () DESCRIPTION The `_time' function returns the number of elapsed seconds since 00:00:00 UTC, January 1, 1970. A number of functions (`ctime', `gmtime', `localtime', etc.) are able to convert such a value to other representations. SEE ALSO ctime, time, localtime, gmtime -------------------------------------------------------------- time SYNOPSIS Return the current date and time as a string USAGE String_Type time () DESCRIPTION This function returns the current time as a string of the form: Sun Apr 21 13:34:17 1996 SEE ALSO strftime, ctime, message, substr -------------------------------------------------------------- times SYNOPSIS Get process times USAGE Struct_Type times () DESCRIPTION The `times' function returns a structure containing the following fields: tms_utime (user time) tms_stime (system time) tms_cutime (user time of child processes) tms_cstime (system time of child processes) NOTES Not all systems support this function. SEE ALSO _tic, _toc, _time -------------------------------------------------------------- _toc SYNOPSIS Get the elapsed CPU time for the current process USAGE Double_Type _toc () DESCRIPTION The `_toc' function returns the elapsed CPU time in seconds since the last call to `_tic'. The CPU time is the amount of time the CPU spent running the code of the current process. NOTES This function may not be available on all systems. The implementation of this function is based upon the `times' system call. The precision of the clock is system dependent and may not be very accurate for small time intervals. For this reason, the tic/toc functions may be more useful for small time-intervals. SEE ALSO _tic, _tic, _toc, times, _time -------------------------------------------------------------- toc SYNOPSIS Read the interval timer USAGE Double_Type toc () DESCRIPTION The `toc' function returns the elapsed time in seconds since the last call to `tic'. See the documentation for the `tic' function for more information. SEE ALSO tic, _tic, _toc, times, _time -------------------------------------------------------------- atof SYNOPSIS Convert a string to a double precision number USAGE Double_Type atof (String_Type s) DESCRIPTION This function converts a string `s' to a double precision value and returns the result. It performs no error checking on the format of the string. The function `_slang_guess_type' may be used to check the syntax of the string. EXAMPLE define error_checked_atof (s) { if (__is_datatype_numeric (_slang_guess_type (s))) return atof (s); throw InvalidParmError, "$s is not a double"$; } SEE ALSO typecast, double, _slang_guess_type -------------------------------------------------------------- atoi SYNOPSIS Convert a string to an integer USAGE Int_Type atoi (String_Type str) DESCRIPTION The `atoi' function converts a string to an `Int_Type' using the standard C library function of the corresponding name. NOTES This function performs no syntax checking upon its argument. SEE ALSO integer, atol, atoll, atof, sscanf -------------------------------------------------------------- atol SYNOPSIS Convert a string to an long integer USAGE Long_Type atol (String_Type str) DESCRIPTION The `atol' function converts a string to a `Long_Type' using the standard C library function of the corresponding name. NOTES This function performs no syntax checking upon its argument. SEE ALSO integer, atoi, atoll, atof, sscanf -------------------------------------------------------------- atoll SYNOPSIS Convert a string to a long long USAGE LLong_Type atoll (String_Type str) DESCRIPTION The `atoll' function converts a string to a `LLong_Type' using the standard C library function of the corresponding name. NOTES This function performs no syntax checking upon its argument. Not all platforms provide support for the long long data type. SEE ALSO integer, atoi, atol, atof, sscanf -------------------------------------------------------------- char SYNOPSIS Convert a character code to a string USAGE String_Type char (Integer_Type c) DESCRIPTION The `char' function converts an integer character code (ascii) value `c' to a string of unit character length such that the first character of the string is `c'. For example, `char('a')' returns the string `"a"'. If UTF-8 mode is in effect (`_slang_utf8_ok' is non-zero), the resulting single character may be represented by several bytes. If the character code `c' is less than 0, then byte-semantics will be used with the resulting string consisting of a single byte whose value is that of `-c&0xFF'. NOTES A better name should have been chosen for this function. SEE ALSO integer, string, typedef, sprintf, pack -------------------------------------------------------------- define_case SYNOPSIS Define upper-lower case conversion USAGE define_case (Integer_Type ch_up, Integer_Type ch_low) DESCRIPTION This function defines an upper and lowercase relationship between two characters specified by the arguments. This relationship is used by routines which perform uppercase and lowercase conversions. The first integer `ch_up' is the ascii value of the uppercase character and the second parameter `ch_low' is the ascii value of its lowercase counterpart. NOTES This function has no effect in UTF-8 mode. SEE ALSO strlow, strup -------------------------------------------------------------- double SYNOPSIS Convert an object to double precision USAGE Double_Type double (x) DESCRIPTION The `double' function typecasts an object `x' to double precision. For example, if `x' is an array of integers, an array of double types will be returned. If an object cannot be converted to `Double_Type', a type-mismatch error will result. NOTES The `double' function is equivalent to the typecast operation typecast (x, Double_Type) To convert a string to a double precision number, use the `atof' function. SEE ALSO typecast, atof, int -------------------------------------------------------------- int SYNOPSIS Typecast an object to an integer USAGE Int_Type int (s) DESCRIPTION This function performs a typecast of an object `s' to an object of Integer_Type. If `s' is a string, it returns returns the ascii value of the first bytes of the string `s'. If `s' is Double_Type, `int' truncates the number to an integer and returns it. EXAMPLE `int' can be used to convert single byte strings to integers. As an example, the intrinsic function `isdigit' may be defined as define isdigit (s) { if ((int (s) >= '0') and (int (s) <= '9')) return 1; return 0; } NOTES This function is equivalent to `typecast (s, Integer_Type)'; SEE ALSO typecast, double, integer, char, isdigit -------------------------------------------------------------- integer SYNOPSIS Convert a string to an integer USAGE Integer_Type integer (String_Type s) DESCRIPTION The `integer' function converts a string representation of an integer back to an integer. If the string does not form a valid integer, a SyntaxError will be thrown. EXAMPLE `integer ("1234")' returns the integer value `1234'. NOTES This function operates only on strings and is not the same as the more general `typecast' operator. SEE ALSO typecast, _slang_guess_type, string, sprintf, char -------------------------------------------------------------- isdigit SYNOPSIS Tests for a decimal digit character USAGE Integer_Type isdigit (s) DESCRIPTION This function returns a non-zero value if the character represented by `s' is a digit; otherwise, it returns zero. If `s' is a string, the first character of `s' will be used for the test. EXAMPLE A simple, user defined implementation of `isdigit' is define isdigit (x) { return ((x <= '9') and (x >= '0')); } However, the intrinsic function `isdigit' executes many times faster than the representation defined above, and works properly when `x' is a Unicode character. SEE ALSO int, integer -------------------------------------------------------------- _slang_guess_type SYNOPSIS Guess the data type that a string represents USAGE DataType_Type _slang_guess_type (String_Type s) DESCRIPTION This function tries to determine whether its argument `s' represents an integer (short, int, long), floating point (float, double), or a complex number. If it appears to be none of these, then a string is assumed. It returns one of the following values depending on the format of the string `s': Short_Type : short integer (e.g., "2h") UShort_Type : unsigned short integer (e.g., "2hu") Integer_Type : integer (e.g., "2") UInteger_Type : unsigned integer (e.g., "2") Long_Type : long integer (e.g., "2l") ULong_Type : unsigned long integer (e.g., "2l") Float_Type : float (e.g., "2.0f") Double_Type : double (e.g., "2.0") Complex_Type : imaginary (e.g., "2i") String_Type : Anything else. (e.g., "2foo") For example, `_slang_guess_type("1e2")' returns Double_Type but `_slang_guess_type("e12")' returns String_Type. SEE ALSO integer, string, double, atof, __is_datatype_numeric -------------------------------------------------------------- string SYNOPSIS Convert an object to a string representation. USAGE String_Type string (obj) DESCRIPTION The `string' function may be used to convert an object `obj' of any type to its string representation. For example, `string(12.34)' returns `"12.34"'. EXAMPLE define print_anything (anything) { message (string (anything)); } NOTES This function is _not_ the same as typecasting to a String_Type using the `typecast' function. SEE ALSO typecast, sprintf, integer, char -------------------------------------------------------------- tolower SYNOPSIS Convert a character to lowercase. USAGE Integer_Type lower (Integer_Type ch) DESCRIPTION This function takes an integer `ch' and returns its lowercase equivalent. SEE ALSO toupper, strup, strlow, int, char, define_case -------------------------------------------------------------- toupper SYNOPSIS Convert a character to uppercase. USAGE Integer_Type toupper (Integer_Type ch) DESCRIPTION This function takes an integer `ch' and returns its uppercase equivalent. SEE ALSO tolower, strup, strlow, int, char, define_case -------------------------------------------------------------- typecast SYNOPSIS Convert an object from one data type to another. USAGE typecast (x, new_type) DESCRIPTION The `typecast' function performs a generic typecast operation on `x' to convert it to `new_type'. If `x' represents an array, the function will attempt to convert all elements of `x' to `new_type'. Not all objects can be converted and a type-mismatch error will result upon failure. EXAMPLE define to_complex (x) { return typecast (x, Complex_Type); } defines a function that converts its argument, `x' to a complex number. SEE ALSO int, double, typeof -------------------------------------------------------------- _typeof SYNOPSIS Get the data type of an object USAGE DataType_Type _typeof (x) DESCRIPTION This function is similar to the `typeof' function except in the case of arrays. If the object `x' is an array, then the data type of the array will be returned. otherwise `_typeof' returns the data type of `x'. EXAMPLE if (Integer_Type == _typeof (x)) message ("x is an integer or an integer array"); SEE ALSO typeof, array_info, _slang_guess_type, typecast -------------------------------------------------------------- typeof SYNOPSIS Get the data type of an object USAGE DataType_Type typeof (x) DESCRIPTION This function returns the data type of `x'. EXAMPLE if (Integer_Type == typeof (x)) message ("x is an integer"); SEE ALSO _typeof, is_struct_type, array_info, _slang_guess_type, typecast --------------------------------------------------------------
Back to File Manager