S-Lang Run-Time Library Reference: Version 1.4.0: Functions that Operate on Strings

Next Previous Contents

## 3. Functions that Operate on Strings

## 3.1 Sprintf

Synopsis

  Format objects into a string

Usage

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

Description

  `Sprintf` formats a string from `n` objects according to `format`. Unlike `sprintf`, the `Sprintf` function requires the number of items to format.

  The format string is a C library `sprintf` style format descriptor. Briefly, the format string may consist of ordinary characters (not including the `%` character), which are copied into the output string as-is, and a conversion specification introduced by the `%` character. The `%` character must be followed by at least one other character to specify the conversion:

  > `

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

  > `

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

  > `

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

  > `

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

  `sprintf, string, sscanf`

## 3.2 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`

## 3.3 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`

## 3.4 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`

## 3.5 is_substr

Synopsis

  Test for a specified substring within a string.

Usage

  `Integer_Type is_substr (String_Type a, String_Type b)`

Description

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

Notes

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

See Also

  `substr, string_match, strreplace`

## 3.6 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`

## 3.7 sprintf

Synopsis

  Format objects into a string

Usage

  `String sprintf (String format, ...);`

Description

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

See Also

  `Sprintf, string, sscanf, vmessage`

## 3.8 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`

## 3.9 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`.

## 3.10 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`

## 3.11 str_replace

Synopsis

  Replace a substring of a string

Usage

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

Description

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

Notes

  This function has been superceded by `strreplace`.

See Also

  `strreplace`

## 3.12 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`

## 3.13 strcat

Synopsis

  Concatenate strings

Usage

  `String_Type strcat (String_Type a_1, ..., String_Type a_N)`

Description

  The `strcat` function concatenates its N `String_Type` arguments `a_1`, ... `a_N` together and returns the result.

Example

  > `

  >         strcat ("Hello", " ", "World");

  > `

  produces the string `"Hello World"`.
Notes

  This function is equivalent to the binary operation `a_1+...+a_N`. However, `strcat` is much faster making it the preferred method to concatenate string.

See Also

  `sprintf, create_delimited_string`

## 3.14 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`

## 3.15 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`

## 3.16 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`

## 3.17 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`

## 3.18 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`

## 3.19 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`

## 3.20 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`

## 3.21 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`

## 3.22 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`

## 3.23 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`

## 3.24 strreplace

Synopsis

  Replace one or more substrings

Usage

  `(new, n) = strreplace (a, b, c, max_n)`

  > `

  >        String_Type a, b, c, rep;
  >        Int_Type n, max_n;

  > `

Description

  The `strreplace` function may be used to replace one or more occurances of `b` in `a` with `c`. If the integer `max_n` is positive, then the first `max_n` occurances of `b` in `a` will be replaced. Otherwise, if `max_n` is negative, then the last `abs(max_n)` occurances will be replaced.

  The function returns the resulting string and an integer indicating how many replacements were made.

Example

  The following function illustrates how `strreplace` may be used to remove all occurances of a specified substring

  > `

  >       define delete_substrings (a, b)
  >       {
  >          (a, ) = strreplace (a, b, "", strlen (a));
  >          return a;
  >       }

  > `

See Also

  `is_substr, strsub, strtrim, strtrans, str_delete_chars`

## 3.25 strsub

Synopsis

  Replace a character with another in a string.

Usage

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

Description

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

Example

  > `

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

  > `

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

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

See Also

  `is_substr, strreplace, strlen`

## 3.26 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`

## 3.27 strtrans

Synopsis

  Replace characters in a string

Usage

  `String_Type strtrans (str, old_set, new_set)`

  > `

  >        String_Type str, old_set, new_set;

  > `

Description

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

Example

  > `

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

  > `

See Also

  `strreplace, strtrim, strup, strlow`

## 3.28 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`

## 3.29 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`

## 3.30 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`

## 3.31 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`

## 3.32 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`

Next Previous Contents