Format objects into a string
String_Type Sprintf (String_Type format, ..., Integer_Type n)
Sprintf
formats a string from n
objects according to
format
. Unlike sprintf
, the Sprintf
function
requires the number of items to format.
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.
sprintf, string
Concatenate strings using a delimiter
String_Type create_delimited_string (delim, s_1, s_2, ..., s_n, n)
String_Type delim, s_1, ..., s_n
Integer_Type n
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
One use for this function is to construct path names, e.g.,
create_delimited_string ("/", "user", "local", "bin", 3);
will produce "usr/local/bin"
.
The expression strcat(a,b)
is equivalent to
create_delimited_string("", a, b, 2)
.
is_list_element, extract_element, strchop, strcat
Extract the nth element of a string with delimiters
String_Type extract_element (String_Type list, Integer_Type nth, Integer_Type delim);
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
.
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));
}
is_list_element, is_substr, strtok, strchop, create_delimited_string
Test whether a delimited string contains a specific element
Integer_Type is_list_element (String_Type list, String_Type elem, Integer_Type delim)
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.
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).
extract_element, is_substr, create_delimited_string
Test for a specified substring within a string.
Integer_Type is_substr (String_Type a, String_Type b)
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
.
It is important to remember that the first character of a string
corresponds to a position value of 1
.
substr, string_match, str_replace
Format a string suitable for parsing
String_Type make_printable_string(String_Type str)
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.
eval, str_quote_string
Format objects into a string
String sprintf (String format, ...);
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.
Sprintf, string, vmessage
Escape characters in a string.
String_Type str_quote_string(String_Type str, String_Type qlis, Integer_Type quote)
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.
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\?
str_uncomment_string, make_printable_string
Replace a substring of a string
Integer_Type str_replace (String_Type a, String_Type b, String_Type c)
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.
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.
is_substr, strsub, strtrim
Remove comments from a string
String_Type str_uncomment_string(String_Type s, String_Type beg, String_Type end)
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.
The expression
str_uncomment_string ("Hello (testing) 'example' World", "'(", "')")
returns the string "Hello World"
.
This routine does not handle multicharacter comment delimiters and it assumes that comments are not nested.
str_quote_string
Concatenate two strings
String_Type strcat (String_Type a, String_Type b)
The strcat
function takes two string valued quantities, a
and
b
, concatenates them together and returns the result.
strcat ("Hello ", "World");
produces the string "Hello World"
.
This function is equivalent to the binary operation a+b
.
sprintf, create_delimited_string
Chop or split a string into substrings.
String_Type[] strchop (String_Type str, Integer_Type delim, Integer_Type quote)
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.
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
a = b[0];
if (length (b) > 1) foreach (b[[1:]])
{
c = ();
a += "," + c;
}
return a;
}
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.
strchopr, extract_element, create_delimited_string, strtok
Chop or split a string into substrings.
String_Type[] strchopr (String_Type str, String_Type delim, String_Type quote)
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.
strchop, extract_element, strtok
Compare two strings
Interpret strcmp (String_Type a, String_Type b)
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
.
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));
}
One may also use one of the binary comparison operators, e.g.,
a > b
.
strup, strncmp
Remove excess whitespace characters from a string
String_Type strcompress (String_Type s, String_Type white)
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
.
The expression
strcompress (",;apple,,cherry;,banana", ",;");
returns the string "apple,cherry,banana"
.
strtrim
Match a string against a regular expression
Integer_Type string_match(String_Type str, String_Type pat, Integer_Type pos)
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
.
string_match_nth, strcmp, strncmp
Get the result of the last call to string_match
(Integer_Type, Integer_Type) = string_match_nth(Integer_Type nth)
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 \(, \)
.
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.
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.
string_match
Compute the length of a string
Integer_Type strlen (String_Type a)
The strlen
function may be used to compute the length of a string.
After execution of
variable len = strlen ("hello");
len
will have a value of 5
.
bstrlen, length, substr
Convert a string to lowercase
String_Type strlow (String_Type s)
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.
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.
strup, tolower, strcmp, strtrim, define_case
Compare the first few characters of two strings
Integer_Type strncmp (String_Type a, String_Type b, Integer_Type n)
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.
The expression
strcmp ("apple", "appliance", 3);
will return zero since the first three characters match.
strcmp, strlen
Replace a character with another in a string.
String_Type strsub (String_Type s, Integer_Type pos, Integer_Type ch)
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.
define replace_spaces_with_comma (s)
{
variable n;
while (n = is_substr (s, " "), n) s = strsub (s, n, ',');
return s;
}
The first character in the string s
is specified by pos
equal to 1.
is_substr, str_replace, strlen
Extract tokens from a string
String_Type[] strtok (String_Type str, String_Type white)
strtok
breaks the string str
into a series of tokens and
returns them as an array of strings. The second parameter
white
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.
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;
}
strchop, strcompress, extract_element
Remove whitespace from the ends of a string
String_Type strtrim (String_Type s [,String_Type w])
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"
.
strtrim_beg, strtrim_end, strcompress
Remove leading whitespace from a string
String_Type strtrim_beg (String_Type s [,String_Type w])
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"
.
strtrim, strtrim_end, strcompress
Remove trailing whitespace from a string
String_Type strtrim_end (String_Type s [,String_Type w])
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"
.
strtrim, strtrim_beg, strcompress
Convert a string to uppercase
String_Type strup (String_Type s)
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.
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.
strlow, toupper, strcmp, strtrim, define_case
Extract a substring from a string
String_Type substr (String_Type s, Integer_Type n, Integer_Type len)
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.
substr ("To be or not to be", 7, 5);
returns "or no"
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:]]
.
is_substr, strlen