Description: Documentation

## function Sprintf

### Synopsis

Format objects into a string

### Usage

String_Type Sprintf (String_Type format, ..., Integer_Type n)

### Description

Sprintf formats a string from n objects according to format . Unlike sprintf , the Sprintf function requires the number of items to format. The format string is a C library sprintf style format descriptor. Briefly, the format string may consist of ordinary characters (not including the % character), which are copied into the output string as-is, and a conversion specification introduced by the % character. The % character must be followed by at least one other character to specify the conversion:

         s    value is a string
         f    value is a floating point number
         e    print float in exponential form, e.g., 2.345e08
         g    print float as e or g, depending upon its value
         c    value is an ascii character
         %    print the percent character
         d    print a signed decimal integer
         u    print an unsigned decimal integer
         o    print an integer as octal
         X    print an integer as hexadecimal
         S    convert value to a string and format as string

Note that %S is a SLang extension which will cause the value to be formatted as string. In fact, sprintf("%S",x) is equivalent to sprintf("%s",string(x)) .

         s = Sprintf("%f is greater than %f but %s is better than %s\n",
                     PI, E, "Cake" "Pie", 4);

The final argument to Sprintf is the number of items to format; in this case, there are 4 items.

### See also

sprintf , string , sscanf

## function create_delimited_string

### Synopsis

Concatenate strings using a delimiter

### Usage

String_Type create_delimited_string (delim, s_1, s_2, ..., s_n, n)

        String_Type delim, s_1, ..., s_n
        Integer_Type n

### Description

create_delimited_string performs a concatenation operation on the n strings s_1 , ..., s_n , using the string delim as a delimiter. The resulting string is equivalent to one obtained via

          s_1 + delim + s_2 + delim + ... + s_n

### Example

One use for this function is to construct path names, e.g.,

        create_delimited_string ("/", "user", "local", "bin", 3);

will produce "usr/local/bin" .

### Notes

The expression strcat(a,b) is equivalent to create_delimited_string("", a, b, 2) .

### See also

strjoin , is_list_element , extract_element , strchop , strcat

## function extract_element

### Synopsis

Extract the nth element of a string with delimiters

### Usage

String_Type extract_element (String_Type list, Integer_Type nth, Integer_Type delim);

### Description

The extract_element function may be used to extract the nth element of the delim delimited list of strings list . The function will return the nth element of the list, unless nth specifies more elements than the list contains, in which case NULL will be returned. Elements in the list are numbered from 0 .

### Example

The expression

         extract_element ("element 0, element 1, element 2", 1, ',')

returns the string " element 1" , whereas

         extract_element ("element 0, element 1, element 2", 1, ' ')

returns "0," . The following function may be used to compute the number of elements in the list:

         define num_elements (list, delim)
         {
            variable nth = 0;
            while (NULL != extract_element (list, nth, delim))
              nth++;
            return nth;
         }

Alternatively, the strchop function may be more useful. In fact, extract_element may be expressed in terms of the function strchop as

        define extract_element (list, nth, delim)
        {
           list = strchop(list, delim, 0);
           if (nth >= length (list))
             return NULL;
           else
             return list[nth];
        }

and the num_elements function used above may be recoded more simply as:

        define num_elements (list, delim)
        {
           return length (strchop (length, delim, 0));
        }

### See also

is_list_element , is_substr , strtok , strchop , create_delimited_string

## function is_list_element

### Synopsis

Test whether a delimited string contains a specific element

### Usage

Integer_Type is_list_element (String_Type list, String_Type elem, Integer_Type delim)

### Description

The is_list_element function may be used to determine whether or not a delimited list of strings, list , contains the element elem . If elem is not an element of list , the function will return zero, otherwise, it returns 1 plus the matching element number.

### Example

The expression

         is_list_element ("element 0, element 1, element 2", "0,", ' ');

returns 2 since "0," is element number one of the list (numbered from zero).

### See also

extract_element , is_substr , create_delimited_string

## function is_substr

### Synopsis

Test for a specified substring within a string.

### Usage

Integer_Type is_substr (String_Type a, String_Type b)

### Description

This function may be used to determine if a contains the string b . If it does not, the function returns 0; otherwise it returns the position of the first occurance of b in a .

### Notes

It is important to remember that the first character of a string corresponds to a position value of 1 .

### See also

substr , string_match , str_replace

## function make_printable_string

### Synopsis

Format a string suitable for parsing

### Usage

String_Type make_printable_string(String_Type str)

### Description

This function formats a string in such a way that it may be used as an argument to the eval function. The resulting string is identical to str except that it is enclosed in double quotes and the backslash, newline, and double quote characters are expanded.

### See also

eval , str_quote_string

## function sprintf

### Synopsis

Format objects into a string

### Usage

String sprintf (String format, ...);

### Description

This function performs a similar task as the C function with the same name. It differs from the SLang function Sprintf in that it does not require the number of items to format. See the documentation for Sprintf for more information.

### See also

Sprintf , string , sscanf , vmessage

## function sscanf

### Synopsis

Parse a formatted string

### Usage

Int_Type sscanf (s, fmt, r1, ... rN)

        String_Type s, fmt;
        Ref_Type r1, ..., rN

### Description

The sscanf function parses the string s according to the format fmt and sets the variables whose references are given by r1 , ..., rN . The function returns the number of references assigned, or -1 upon error. The format string fmt consists of ordinary characters and conversion specifiers. A conversion specifier begins with the special character % and is described more fully below. A white space character in the format string matches any amount of whitespace in the input string. Parsing of the format string stops whenever a match fails. The % is used to denote a conversion specifier whose general form is given by %[*][width][type]format where the brackets indicate optional items. If * is present, then the conversion will be performed by no assignment to a reference will be made. The width specifier specifies the maximum field width to use for the conversion. The type modifier is used to indicate size of the object, e.g., a short integer, as follows. If type is given as the character h , then if the format conversion is for an integer ( dioux ), the object assigned will be a short integer. If type is l , then the conversion will be to a long integer for integer conversions, or to a double precession floating point number for floating point conversions. The format specifier is a character that specifies the conversion:

           %     Matches a literal percent character.  No assigment is
                 performed.
           d     Matches a signed decimal integer.
           D     Matches a long decimal integer (equiv to `ld')
           u     Matches an unsigned decimal integer
           U     Matches an unsigned long decimal integer (equiv to `lu')
           i     Matches either a hexidecimal integer, decimal integer, or
                 octal integer.
           I     Equivalent to `li'.
           x     Matches a hexidecimal integer.
           X     Matches a long hexidecimal integer (same as `lx').
           e,f,g Matches a decimal floating point number (Float_Type).
           E,F,G Matches a double precision floating point number, same as `lf'.
           s     Matches a string of non-whitespace characters (String_Type).
           c     Matches one character.  If width is given, width
                 characters are matched.
           n     Assigns the number of characters scanned so far.
           [...] Matches zero or more characters from the set of characters
                 enclosed by the square brackets.  If '^' is given as the
                 first character, then the complement set is matched.

### Example

Suppose that s is "Coffee: (3,4,12.4)" . Then

        n = sscanf (s, "%[a-zA-Z]: (%d,%d,%lf)", &item, &x, &y, &z);

will set n to 4, item to "Coffee" , x to 3, y to 4, and z to the double precision number 12.4 . However,

        n = sscanf (s, "%s: (%d,%d,%lf)", &item, &x, &y, &z);

will set n to 1, item to "Coffee:" and the remaining variables will not be assigned.

### See also

sprintf , unpack , string , atof , int , integer , string_match

## function str_delete_chars

### Synopsis

Delete characters from a string

### Usage

String_Type str_delete_chars (String_Type str, String_Type del_set

### Description

This function may be used to delete the set of characters specified by del_set from the string str . The result is returned.

### Example

        str = str_delete_chars (str, "^A-Za-z");

will remove all characters except A-Z and a-z from str .

## function str_quote_string

### Synopsis

Escape characters in a string.

### Usage

String_Type str_quote_string(String_Type str, String_Type qlis, Integer_Type quote)

### Description

The str_quote_string returns a string identical to str except that all characters in the set specified by the string qlis are escaped with the quote character, including the quote character itself. This function is useful for making a string that can be used in a regular expression.

### Example

Execution of the statements

       node = "Is it [the coat] really worth $100?";
       tag = str_quote_string (node, "\\^$[]*.+?", '\\');

will result in tag having the value:

        Is it \[the coat\] really worth \$100\?

### See also

str_uncomment_string , make_printable_string

## function str_replace

### Synopsis

Replace a substring of a string

### Usage

Integer_Type str_replace (String_Type a, String_Type b, String_Type c)

### Description

The str_replace function replaces the first occurance of b in a with c and returns an integer that indicates whether a replacement was made or not. If b does not occur in a , zero is returned. However, if b occurs in a , a non-zero integer is returned as well as the new string resulting from the replacement.

### Example

      define str_replace_all (orig, match, replacement)
      {
         while (str_replace (orig, match, replacement))
            orig = ();
         return orig;
      }

is a function that replaces all occurances in a string.

### See also

is_substr , strsub , strtrim , strtrans , str_delete_chars

## function str_uncomment_string

### Synopsis

Remove comments from a string

### Usage

String_Type str_uncomment_string(String_Type s, String_Type beg, String_Type end)

### Description

This function may be used to remove comments from a string s . The parameters, beg and end , are strings of equal length whose corresponding characters specify the begin and end comment characters, respectively. It returns the uncommented string.

### Example

The expression

         str_uncomment_string ("Hello (testing) 'example' World", "'(", "')")

returns the string "Hello World" .

### Notes

This routine does not handle multicharacter comment delimiters and it assumes that comments are not nested.

### See also

str_quote_string

## function strcat

### Synopsis

Concatenate two strings

### Usage

String_Type strcat (String_Type a, String_Type b)

### Description

The strcat function takes two string valued quantities, a and b , concatenates them together and returns the result.

### Example

        strcat ("Hello ", "World");

produces the string "Hello World" .

### Notes

This function is equivalent to the binary operation a+b .

### See also

sprintf , create_delimited_string

## function strchop

### Synopsis

Chop or split a string into substrings.

### Usage

String_Type[] strchop (String_Type str, Integer_Type delim, Integer_Type quote)

### Description

The strchop function may be used to split-up a string str that consists of substrings delimited by the character specified by delim . If the integer quote is non-zero, it will be taken as a quote character for the delimiter. The function returns the substrings as an array.

### Example

The following function illustrates how to sort a comma separated list of strings:

         define sort_string_list (a)
         {
            variable i, b, c;
            b = strchop (a, ',', 0);

            i = array_sort (b, &strcmp);
            b = b[i];   % rearrange

            % Convert array back into comma separated form
            return strjoin (b, ",");
         }

### Notes

The semantics of this strchop and strchopr have been changed since version 1.2.x of the interpreter. Old versions of these functions returned the values on the stack, which meant that one could not chop up arbitrarily long strings that consist of many substrings. The function strchopr should be used if it is desired to have the string chopped-up in the reverse order.

### See also

strchopr , extract_element , strjoin , strtok

## function strchopr

### Synopsis

Chop or split a string into substrings.

### Usage

String_Type[] strchopr (String_Type str, String_Type delim, String_Type quote)

### Description

This routine performs exactly the same function as strchop except that it returns the substrings in the reverse order. See the documentation for strchop for more information.

### See also

strchop , extract_element , strtok , strjoin

## function strcmp

### Synopsis

Compare two strings

### Usage

Interpret strcmp (String_Type a, String_Type b)

### Description

The strcmp function may be used to perform a case-sensitive string comparison, in the lexicongraphic sense, on strings a and b . It returns 0 if the strings are identical, a negative integer if a is less than b , or a positive integer if a is greater than b .

### Example

The strup function may be used to perform a case-insensitive string comparison:

        define case_insensitive_strcmp (a, b)
        {
          return strcmp (strup(a), strup(b));
        }

### Notes

One may also use one of the binary comparison operators, e.g., a > b .

### See also

strup , strncmp

## function 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

## function string_match

### Synopsis

Match a string against a regular expression

### Usage

Integer_Type string_match(String_Type str, String_Type pat, Integer_Type pos)

### Description

The string_match function returns zero if str does not match regular expression specified by pat . This function performs the match starting at position pos (numbered from 1) in str . This function returns the position of the start of the match. To find the exact substring actually matched, use string_match_nth .

### See also

string_match_nth , strcmp , strncmp

## function string_match_nth

### Synopsis

Get the result of the last call to string_match

### Usage

(Integer_Type, Integer_Type) = string_match_nth(Integer_Type nth)

### Description

The string_match_nth function returns two integers describing the result of the last call to string_match . It returns both the offset into the string and the length of characters matches by the nth submatch. By convention, nth equal to zero means the entire match. Otherwise, nth must be an integer with a value 1 through 9, and refers to the set of characters matched by the nth regular expression enclosed by the pairs \(, \) .

### Example

Consider:

         variable matched, pos, len;
         matched = string_match("hello world", "\\([a-z]+\\) \\([a-z]+\\)", 1);
         if (matched) (pos, len) = string_match_nth(2);

This will set matched to 1 since a match will be found at the first position, pos to 6 since w is offset 6 characters from the beginning of the string, and len to 5 since "world" is 5 characters long.

### Notes

The position offset is not affected by the value of the offset parameter to the string_match function. For example, if the value of the last parameter to the string_match function had been 3, pos would still have been set to 6. Note also that string_match_nth returns the offset from the beginning of the string and not the position of the match.

### See also

string_match

## function strjoin

### Synopsis

Concatenate elements of a string array

### Usage

String_Type strjoin (Array_Type a, String_Type delim)

### Description

The strjoin function operates on an array of strings by joining successive elements together separated with a delimiter delim . If delim is the empty string "" , then the result will simply be the concatenation of the elements.

### Example

Suppose that

          days = ["Sun","Mon","Tue","Wed","Thu","Fri","Sat","Sun"];

Then strjoin (days,"+") will produce "Sun+Mon+Tue+Wed+Thu+Fri+Sat+Sun" . Similarly, strjoin (["","",""], "X") will produce "XX" .

### See also

create_delimited_string , strchop , strcat

## function strlen

### Synopsis

Compute the length of a string

### Usage

Integer_Type strlen (String_Type a)

### Description

The strlen function may be used to compute the length of a string.

### Example

After execution of

       variable len = strlen ("hello");

len will have a value of 5 .

### See also

bstrlen , length , substr

## function strlow

### Synopsis

Convert a string to lowercase

### Usage

String_Type strlow (String_Type s)

### Description

The strlow function takes a string s and returns another string identical to s except that all upper case characters that comprise s will be converted to lower case.

### Example

The function

        define Strcmp (a, b)
        {
          return strcmp (strlow (a), strlow (b));
        }

performs a case-insensitive comparison operation of two strings by converting them to lower case first.

### See also

strup , tolower , strcmp , strtrim , define_case

## function strncmp

### Synopsis

Compare the first few characters of two strings

### Usage

Integer_Type strncmp (String_Type a, String_Type b, Integer_Type n)

### Description

This function behaves like strcmp except that it compares only the first n characters in the strings a and b . See the documentation for strcmp for information about the return value.

### Example

The expression

         strcmp ("apple", "appliance", 3);

will return zero since the first three characters match.

### See also

strcmp , strlen

## function strsub

### Synopsis

Replace a character with another in a string.

### Usage

String_Type strsub (String_Type s, Integer_Type pos, Integer_Type ch)

### Description

The strsub character may be used to substitute the character ch for the character at position pos of the string s . The resulting string is returned.

### Example

        define replace_spaces_with_comma (s)
        {
          variable n;
          while (n = is_substr (s, " "), n) s = strsub (s, n, ',');
          return s;
        }

For uses such as this, the strtrans function is a better choice.

### Notes

The first character in the string s is specified by pos equal to 1.

### See also

is_substr , str_replace , strlen

## function strtok

### Synopsis

Extract tokens from a string

### Usage

String_Type[] strtok (String_Type str [,String_Type white])

### Description

strtok breaks the string str into a series of tokens and returns them as an array of strings. If the second parameter white is present, then it specifies the set of characters that are to be regarded as whitespace when extracting the tokens, and may consist of the whitespace characters or a range of such characters. If the first character of white is '^' , then the whitespace characters consist of all characters except those in white . For example, if white is " \t\n,;." , then those characters specifiy the whitespace characters. However, if white is given by "^a-zA-Z0-9_" , then any character is a whitespace character except those in the ranges a-z , A-Z , 0-9 , and the underscore character. If the second parameter is not present, then it defaults to " \t\r\n\f" .

### Example

The following example may be used to count the words in a text file:

        define count_words (file)
        {
           variable fp, line, count;

           fp = fopen (file, "r");
           if (fp == NULL) return -1;

           count = 0;
           while (-1 != fgets (&line, fp))
             {
               line = strtok (line, "^a-zA-Z");
               count += length (line);
             }
           () = fclose (fp);
           return count;
        }

### See also

strchop , strcompress , extract_element , strjoin

## function strtrans

### Synopsis

Replace characters in a string

### Usage

String_Type strtrans (str, old_set, new_set)

       String_Type str, old_set, new_set;

### Description

The strtrans function may be used to replace all the characters from the set old_set with the corresponding characters from new_set in the string str . If new_set is empty, then the characters in new_set will be removed from str . This function returns the result.

### Example

        str = strtrans (str, "A-Z", "a-z");   % lower-case str
        str = strtrans (str, "^0-9", " ");    % Replace anything but 0-9 by space

### See also

str_replace , strtrim , strup , strlow

## function strtrim

### Synopsis

Remove whitespace from the ends of a string

### Usage

String_Type strtrim (String_Type s [,String_Type w])

### Description

The strtrim function removes all leading and trailing whitespace characters from the string s and returns the result. The optional second parameter specifies the set of whitespace characters. If the argument is not present, then the set defaults to " \t\r\n" .

### See also

strtrim_beg , strtrim_end , strcompress

## function strtrim_beg

### Synopsis

Remove leading whitespace from a string

### Usage

String_Type strtrim_beg (String_Type s [,String_Type w])

### Description

The strtrim_beg function removes all leading whitespace characters from the string s and returns the result. The optional second parameter specifies the set of whitespace characters. If the argument is not present, then the set defaults to " \t\r\n" .

### See also

strtrim , strtrim_end , strcompress

## function strtrim_end

### Synopsis

Remove trailing whitespace from a string

### Usage

String_Type strtrim_end (String_Type s [,String_Type w])

### Description

The strtrim_end function removes all trailing whitespace characters from the string s and returns the result. The optional second parameter specifies the set of whitespace characters. If the argument is not present, then the set defaults to " \t\r\n" .

### See also

strtrim , strtrim_beg , strcompress

## function strup

### Synopsis

Convert a string to uppercase

### Usage

String_Type strup (String_Type s)

### Description

The strup function takes a string s and returns another string identical to s except that all lower case characters that comprise s will be converted to upper case.

### Example

The function

        define Strcmp (a, b)
        {
          return strcmp (strup (a), strup (b));
        }

performs a case-insensitive comparison operation of two strings by converting them to upper case first.

### See also

strlow , toupper , strcmp , strtrim , define_case , strtrans

## function substr

### Synopsis

Extract a substring from a string

### Usage

String_Type substr (String_Type s, Integer_Type n, Integer_Type len)

### Description

The substr function returns a substring with length len of the string s beginning at position n . If len is -1 , the entire length of the string s will be used for len . The first character of s is given by n equal to 1.

### Example

         substr ("To be or not to be", 7, 5);

returns "or no"

### Notes

In many cases it is more convenient to use array indexing rather than the substr function. In fact, substr(s,i+1,strlen(s)) is equivalent to s[[i:]] .

### See also

is_substr , strlen