<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
<HTML>
<HEAD>
<META NAME="GENERATOR" CONTENT="SGML-Tools 1.0.9">
<TITLE> S-Lang Run-Time Library Reference: Version 1.4.0: Functions that Operate on Strings</TITLE>
<LINK HREF="slangfun-4.html" REL=next>
<LINK HREF="slangfun-2.html" REL=previous>
<LINK HREF="slangfun.html#toc3" REL=contents>
</HEAD>
<BODY>
<A HREF="slangfun-4.html">Next</A>
<A HREF="slangfun-2.html">Previous</A>
<A HREF="slangfun.html#toc3">Contents</A>
<HR>
<H2><A NAME="s3">3. Functions that Operate on Strings</A></H2>
<P>
<H2><A NAME="Sprintf"></A> <A NAME="ss3.1">3.1 <B>Sprintf</B></A>
</H2>
<P>
<DL>
<DT><B> Synopsis </B><DD><P>Format objects into a string
<DT><B> Usage </B><DD><P><CODE>String_Type Sprintf (String_Type format, ..., Integer_Type n)</CODE>
<DT><B> Description </B><DD><P><CODE>Sprintf</CODE> formats a string from <CODE>n</CODE> objects according to
<CODE>format</CODE>. Unlike <CODE>sprintf</CODE>, the <CODE>Sprintf</CODE> function
requires the number of items to format.
<P>The format string is a C library <CODE>sprintf</CODE> style format
descriptor. Briefly, the format string may consist of ordinary
characters (not including the <CODE>%</CODE> character), which are copied
into the output string as-is, and a conversion specification
introduced by the <CODE>%</CODE> character. The <CODE>%</CODE> character must be
followed by at least one other character to specify the conversion:
<BLOCKQUOTE><CODE>
<PRE>
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
</PRE>
</CODE></BLOCKQUOTE>
Note that <CODE>%S</CODE> is a <B>S-lang</B> extension which will cause the value
to be formatted as string. In fact, <CODE>sprintf("%S",x)</CODE> is
equivalent to <CODE>sprintf("%s",string(x))</CODE>.
<BLOCKQUOTE><CODE>
<PRE>
s = Sprintf("%f is greater than %f but %s is better than %s\n",
PI, E, "Cake" "Pie", 4);
</PRE>
</CODE></BLOCKQUOTE>
The final argument to <CODE>Sprintf</CODE> is the number of items to format; in
this case, there are 4 items.
<DT><B> See Also </B><DD><P><CODE>sprintf, string, sscanf</CODE>
</DL>
<P>
<P>
<H2><A NAME="create_delimited_string"></A> <A NAME="ss3.2">3.2 <B>create_delimited_string</B></A>
</H2>
<P>
<DL>
<DT><B> Synopsis </B><DD><P>Concatenate strings using a delimiter
<DT><B> Usage </B><DD><P><CODE>String_Type create_delimited_string (delim, s_1, s_2, ..., s_n, n)</CODE>
<BLOCKQUOTE><CODE>
<PRE>
String_Type delim, s_1, ..., s_n
Integer_Type n
</PRE>
</CODE></BLOCKQUOTE>
<DT><B> Description </B><DD><P><CODE>create_delimited_string</CODE> performs a concatenation operation on
the <CODE>n</CODE> strings <CODE>s_1</CODE>, ...,<CODE>s_n</CODE>, using the string
<CODE>delim</CODE> as a delimiter. The resulting string is equivalent to
one obtained via
<BLOCKQUOTE><CODE>
<PRE>
s_1 + delim + s_2 + delim + ... + s_n
</PRE>
</CODE></BLOCKQUOTE>
<DT><B> Example </B><DD><P>One use for this function is to construct path names, e.g.,
<BLOCKQUOTE><CODE>
<PRE>
create_delimited_string ("/", "user", "local", "bin", 3);
</PRE>
</CODE></BLOCKQUOTE>
will produce <CODE>"usr/local/bin"</CODE>.
<DT><B> Notes </B><DD><P>The expression <CODE>strcat(a,b)</CODE> is equivalent to
<CODE>create_delimited_string("", a, b, 2)</CODE>.
<DT><B> See Also </B><DD><P><CODE>strjoin, is_list_element, extract_element, strchop, strcat</CODE>
</DL>
<P>
<P>
<H2><A NAME="extract_element"></A> <A NAME="ss3.3">3.3 <B>extract_element</B></A>
</H2>
<P>
<DL>
<DT><B> Synopsis </B><DD><P>Extract the nth element of a string with delimiters
<DT><B> Usage </B><DD><P><CODE>String_Type extract_element (String_Type list, Integer_Type nth, Integer_Type delim);</CODE>
<DT><B> Description </B><DD><P>The <CODE>extract_element</CODE> function may be used to extract the
<CODE>nth</CODE> element of the <CODE>delim</CODE> delimited list of strings
<CODE>list</CODE>. The function will return the <CODE>nth</CODE> element of the
list, unless <CODE>nth</CODE> specifies more elements than the list
contains, in which case <CODE>NULL</CODE> will be returned.
Elements in the list are numbered from <CODE>0</CODE>.
<DT><B> Example </B><DD><P>The expression
<BLOCKQUOTE><CODE>
<PRE>
extract_element ("element 0, element 1, element 2", 1, ',')
</PRE>
</CODE></BLOCKQUOTE>
returns the string <CODE>" element 1"</CODE>, whereas
<BLOCKQUOTE><CODE>
<PRE>
extract_element ("element 0, element 1, element 2", 1, ' ')
</PRE>
</CODE></BLOCKQUOTE>
returns <CODE>"0,"</CODE>.
<P>The following function may be used to compute the number of elements
in the list:
<BLOCKQUOTE><CODE>
<PRE>
define num_elements (list, delim)
{
variable nth = 0;
while (NULL != extract_element (list, nth, delim))
nth++;
return nth;
}
</PRE>
</CODE></BLOCKQUOTE>
<P>Alternatively, the <CODE>strchop</CODE> function may be more useful. In
fact, <CODE>extract_element</CODE> may be expressed in terms of the
function <CODE>strchop</CODE> as
<BLOCKQUOTE><CODE>
<PRE>
define extract_element (list, nth, delim)
{
list = strchop(list, delim, 0);
if (nth >= length (list))
return NULL;
else
return list[nth];
}
</PRE>
</CODE></BLOCKQUOTE>
and the <CODE>num_elements</CODE> function used above may be recoded more
simply as:
<BLOCKQUOTE><CODE>
<PRE>
define num_elements (list, delim)
{
return length (strchop (length, delim, 0));
}
</PRE>
</CODE></BLOCKQUOTE>
<DT><B> See Also </B><DD><P><CODE>is_list_element, is_substr, strtok, strchop, create_delimited_string</CODE>
</DL>
<P>
<P>
<H2><A NAME="is_list_element"></A> <A NAME="ss3.4">3.4 <B>is_list_element</B></A>
</H2>
<P>
<DL>
<DT><B> Synopsis </B><DD><P>Test whether a delimited string contains a specific element
<DT><B> Usage </B><DD><P><CODE>Integer_Type is_list_element (String_Type list, String_Type elem, Integer_Type delim)</CODE>
<DT><B> Description </B><DD><P>The <CODE>is_list_element</CODE> function may be used to determine whether
or not a delimited list of strings, <CODE>list</CODE>, contains the element
<CODE>elem</CODE>. If <CODE>elem</CODE> is not an element of <CODE>list</CODE>, the function
will return zero, otherwise, it returns 1 plus the matching element
number.
<DT><B> Example </B><DD><P>The expression
<BLOCKQUOTE><CODE>
<PRE>
is_list_element ("element 0, element 1, element 2", "0,", ' ');
</PRE>
</CODE></BLOCKQUOTE>
returns <CODE>2</CODE> since <CODE>"0,"</CODE> is element number one of the list
(numbered from zero).
<DT><B> See Also </B><DD><P><CODE>extract_element, is_substr, create_delimited_string</CODE>
</DL>
<P>
<P>
<H2><A NAME="is_substr"></A> <A NAME="ss3.5">3.5 <B>is_substr</B></A>
</H2>
<P>
<DL>
<DT><B> Synopsis </B><DD><P>Test for a specified substring within a string.
<DT><B> Usage </B><DD><P><CODE>Integer_Type is_substr (String_Type a, String_Type b)</CODE>
<DT><B> Description </B><DD><P>This function may be used to determine if <CODE>a</CODE> contains the
string <CODE>b</CODE>. If it does not, the function returns 0; otherwise it
returns the position of the first occurance of <CODE>b</CODE> in <CODE>a</CODE>.
<DT><B> Notes </B><DD><P>It is important to remember that the first character of a string
corresponds to a position value of <CODE>1</CODE>.
<DT><B> See Also </B><DD><P><CODE>substr, string_match, strreplace</CODE>
</DL>
<P>
<P>
<H2><A NAME="make_printable_string"></A> <A NAME="ss3.6">3.6 <B>make_printable_string</B></A>
</H2>
<P>
<DL>
<DT><B> Synopsis </B><DD><P>Format a string suitable for parsing
<DT><B> Usage </B><DD><P><CODE>String_Type make_printable_string(String_Type str)</CODE>
<DT><B> Description </B><DD><P>This function formats a string in such a way that it may be used as
an argument to the <CODE>eval</CODE> function. The resulting string is
identical to <CODE>str</CODE> except that it is enclosed in double quotes and the
backslash, newline, and double quote characters are expanded.
<DT><B> See Also </B><DD><P><CODE>eval, str_quote_string</CODE>
</DL>
<P>
<P>
<H2><A NAME="sprintf"></A> <A NAME="ss3.7">3.7 <B>sprintf</B></A>
</H2>
<P>
<DL>
<DT><B> Synopsis </B><DD><P>Format objects into a string
<DT><B> Usage </B><DD><P><CODE>String sprintf (String format, ...);</CODE>
<DT><B> Description </B><DD><P>This function performs a similar task as the C function with the same
name. It differs from the <B>S-lang</B> function <CODE>Sprintf</CODE> in that it
does not require the number of items to format.
See the documentation for <CODE>Sprintf</CODE> for more information.
<DT><B> See Also </B><DD><P><CODE>Sprintf, string, sscanf, vmessage</CODE>
</DL>
<P>
<P>
<H2><A NAME="sscanf"></A> <A NAME="ss3.8">3.8 <B>sscanf</B></A>
</H2>
<P>
<DL>
<DT><B> Synopsis </B><DD><P>Parse a formatted string
<DT><B> Usage </B><DD><P><CODE>Int_Type sscanf (s, fmt, r1, ... rN)</CODE>
<BLOCKQUOTE><CODE>
<PRE>
String_Type s, fmt;
Ref_Type r1, ..., rN
</PRE>
</CODE></BLOCKQUOTE>
<DT><B> Description </B><DD><P>The <CODE>sscanf</CODE> function parses the string <CODE>s</CODE> according to the
format <CODE>fmt</CODE> and sets the variables whose references are given by
<CODE>r1</CODE>, ..., <CODE>rN</CODE>. The function returns the number of
references assigned, or <CODE>-1</CODE> upon error.
<P>The format string <CODE>fmt</CODE> consists of ordinary characters and
conversion specifiers. A conversion specifier begins with the
special character <CODE>%</CODE> 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.
<P>The <CODE>%</CODE> is used to denote a conversion specifier whose general
form is given by <CODE>%[*][width][type]format</CODE> where the brackets
indicate optional items. If <CODE>*</CODE> is present, then the conversion
will be performed by no assignment to a reference will be made. The
<CODE>width</CODE> specifier specifies the maximum field width to use for
the conversion. The <CODE>type</CODE> modifier is used to indicate size of
the object, e.g., a short integer, as follows.
<P>If <EM>type</EM> is given as the character <CODE>h</CODE>, then if the format
conversion is for an integer (<CODE>dioux</CODE>), the object assigned will
be a short integer. If <EM>type</EM> is <CODE>l</CODE>, then the conversion
will be to a long integer for integer conversions, or to a double
precession floating point number for floating point conversions.
<P>The format specifier is a character that specifies the conversion:
<BLOCKQUOTE><CODE>
<PRE>
% 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.
</PRE>
</CODE></BLOCKQUOTE>
<DT><B> Example </B><DD><P>Suppose that <CODE>s</CODE> is <CODE>"Coffee: (3,4,12.4)"</CODE>. Then
<BLOCKQUOTE><CODE>
<PRE>
n = sscanf (s, "%[a-zA-Z]: (%d,%d,%lf)", &item, &x, &y, &z);
</PRE>
</CODE></BLOCKQUOTE>
will set <CODE>n</CODE> to <CODE>4</CODE>, <CODE>item</CODE> to <CODE>"Coffee"</CODE>, <CODE>x</CODE> to <CODE>3</CODE>,
<CODE>y</CODE> to <CODE>4</CODE>, and <CODE>z</CODE> to the double precision number
<CODE>12.4</CODE>. However,
<BLOCKQUOTE><CODE>
<PRE>
n = sscanf (s, "%s: (%d,%d,%lf)", &item, &x, &y, &z);
</PRE>
</CODE></BLOCKQUOTE>
will set <CODE>n</CODE> to <CODE>1</CODE>, <CODE>item</CODE> to <CODE>"Coffee:"</CODE> and the
remaining variables will not be assigned.
<DT><B> See Also </B><DD><P><CODE>sprintf, unpack, string, atof, int, integer, string_match</CODE>
</DL>
<P>
<P>
<H2><A NAME="str_delete_chars"></A> <A NAME="ss3.9">3.9 <B>str_delete_chars</B></A>
</H2>
<P>
<DL>
<DT><B> Synopsis </B><DD><P>Delete characters from a string
<DT><B> Usage </B><DD><P><CODE>String_Type str_delete_chars (String_Type str, String_Type del_set</CODE>
<DT><B> Description </B><DD><P>This function may be used to delete the set of characters specified
by <CODE>del_set</CODE> from the string <CODE>str</CODE>. The result is returned.
<DT><B> Example </B><DD><P>
<BLOCKQUOTE><CODE>
<PRE>
str = str_delete_chars (str, "^A-Za-z");
</PRE>
</CODE></BLOCKQUOTE>
will remove all characters except <CODE>A-Z</CODE> and <CODE>a-z</CODE> from
<CODE>str</CODE>.
</DL>
<P>
<P>
<H2><A NAME="str_quote_string"></A> <A NAME="ss3.10">3.10 <B>str_quote_string</B></A>
</H2>
<P>
<DL>
<DT><B> Synopsis </B><DD><P>Escape characters in a string.
<DT><B> Usage </B><DD><P><CODE>String_Type str_quote_string(String_Type str, String_Type qlis, Integer_Type quote)</CODE>
<DT><B> Description </B><DD><P>The <CODE>str_quote_string</CODE> returns a string identical to <CODE>str</CODE>
except that all characters in the set specified by the string
<CODE>qlis</CODE> are escaped with the <CODE>quote</CODE> character, including the
quote character itself. This function is useful for making a
string that can be used in a regular expression.
<DT><B> Example </B><DD><P>Execution of the statements
<BLOCKQUOTE><CODE>
<PRE>
node = "Is it [the coat] really worth $100?";
tag = str_quote_string (node, "\\^$[]*.+?", '\\');
</PRE>
</CODE></BLOCKQUOTE>
will result in <CODE>tag</CODE> having the value:
<BLOCKQUOTE><CODE>
<PRE>
Is it \[the coat\] really worth \$100\?
</PRE>
</CODE></BLOCKQUOTE>
<DT><B> See Also </B><DD><P><CODE>str_uncomment_string, make_printable_string</CODE>
</DL>
<P>
<P>
<H2><A NAME="str_replace"></A> <A NAME="ss3.11">3.11 <B>str_replace</B></A>
</H2>
<P>
<DL>
<DT><B> Synopsis </B><DD><P>Replace a substring of a string
<DT><B> Usage </B><DD><P><CODE>Integer_Type str_replace (String_Type a, String_Type b, String_Type c)</CODE>
<DT><B> Description </B><DD><P>The <CODE>str_replace</CODE> function replaces the first occurance of <CODE>b</CODE> in
<CODE>a</CODE> with <CODE>c</CODE> and returns an integer that indicates whether a
replacement was made or not. If <CODE>b</CODE> does not occur in <CODE>a</CODE>, zero is
returned. However, if <CODE>b</CODE> occurs in <CODE>a</CODE>, a non-zero integer is
returned as well as the new string resulting from the replacement.
<DT><B> Notes </B><DD><P>This function has been superceded by <CODE>strreplace</CODE>.
<DT><B> See Also </B><DD><P><CODE>strreplace</CODE>
</DL>
<P>
<P>
<H2><A NAME="str_uncomment_string"></A> <A NAME="ss3.12">3.12 <B>str_uncomment_string</B></A>
</H2>
<P>
<DL>
<DT><B> Synopsis </B><DD><P>Remove comments from a string
<DT><B> Usage </B><DD><P><CODE>String_Type str_uncomment_string(String_Type s, String_Type beg, String_Type end)</CODE>
<DT><B> Description </B><DD><P>This function may be used to remove comments from a string <CODE>s</CODE>.
The parameters, <CODE>beg</CODE> and <CODE>end</CODE>, are strings of equal length
whose corresponding characters specify the begin and end comment
characters, respectively. It returns the uncommented string.
<DT><B> Example </B><DD><P>The expression
<BLOCKQUOTE><CODE>
<PRE>
str_uncomment_string ("Hello (testing) 'example' World", "'(", "')")
</PRE>
</CODE></BLOCKQUOTE>
returns the string <CODE>"Hello World"</CODE>.
<DT><B> Notes </B><DD><P>This routine does not handle multicharacter comment delimiters and it
assumes that comments are not nested.
<DT><B> See Also </B><DD><P><CODE>str_quote_string</CODE>
</DL>
<P>
<P>
<H2><A NAME="strcat"></A> <A NAME="ss3.13">3.13 <B>strcat</B></A>
</H2>
<P>
<DL>
<DT><B> Synopsis </B><DD><P>Concatenate strings
<DT><B> Usage </B><DD><P><CODE>String_Type strcat (String_Type a_1, ..., String_Type a_N)</CODE>
<DT><B> Description </B><DD><P>The <CODE>strcat</CODE> function concatenates its N <CODE>String_Type</CODE>
arguments <CODE>a_1</CODE>, ... <CODE>a_N</CODE> together and returns the result.
<DT><B> Example </B><DD><P>
<BLOCKQUOTE><CODE>
<PRE>
strcat ("Hello", " ", "World");
</PRE>
</CODE></BLOCKQUOTE>
produces the string <CODE>"Hello World"</CODE>.
<DT><B> Notes </B><DD><P>This function is equivalent to the binary operation <CODE>a_1+...+a_N</CODE>.
However, <CODE>strcat</CODE> is much faster making it the preferred method
to concatenate string.
<DT><B> See Also </B><DD><P><CODE>sprintf, create_delimited_string</CODE>
</DL>
<P>
<P>
<H2><A NAME="strchop"></A> <A NAME="ss3.14">3.14 <B>strchop</B></A>
</H2>
<P>
<DL>
<DT><B> Synopsis </B><DD><P>Chop or split a string into substrings.
<DT><B> Usage </B><DD><P><CODE>String_Type[] strchop (String_Type str, Integer_Type delim, Integer_Type quote)</CODE>
<DT><B> Description </B><DD><P>The <CODE>strchop</CODE> function may be used to split-up a string
<CODE>str</CODE> that consists of substrings delimited by the character
specified by <CODE>delim</CODE>. If the integer <CODE>quote</CODE> is non-zero,
it will be taken as a quote character for the delimiter. The
function returns the substrings as an array.
<DT><B> Example </B><DD><P>The following function illustrates how to sort a comma separated
list of strings:
<BLOCKQUOTE><CODE>
<PRE>
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, ",");
}
</PRE>
</CODE></BLOCKQUOTE>
<DT><B> Notes </B><DD><P>The semantics of this <CODE>strchop</CODE> and <CODE>strchopr</CODE> 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.
<P>The function <CODE>strchopr</CODE> should be used if it is desired to have
the string chopped-up in the reverse order.
<DT><B> See Also </B><DD><P><CODE>strchopr, extract_element, strjoin, strtok</CODE>
</DL>
<P>
<P>
<H2><A NAME="strchopr"></A> <A NAME="ss3.15">3.15 <B>strchopr</B></A>
</H2>
<P>
<DL>
<DT><B> Synopsis </B><DD><P>Chop or split a string into substrings.
<DT><B> Usage </B><DD><P><CODE>String_Type[] strchopr (String_Type str, String_Type delim, String_Type quote)</CODE>
<DT><B> Description </B><DD><P>This routine performs exactly the same function as <CODE>strchop</CODE> except
that it returns the substrings in the reverse order. See the
documentation for <CODE>strchop</CODE> for more information.
<DT><B> See Also </B><DD><P><CODE>strchop, extract_element, strtok, strjoin</CODE>
</DL>
<P>
<P>
<H2><A NAME="strcmp"></A> <A NAME="ss3.16">3.16 <B>strcmp</B></A>
</H2>
<P>
<DL>
<DT><B> Synopsis </B><DD><P>Compare two strings
<DT><B> Usage </B><DD><P><CODE>Interpret strcmp (String_Type a, String_Type b)</CODE>
<DT><B> Description </B><DD><P>The <CODE>strcmp</CODE> function may be used to perform a case-sensitive
string comparison, in the lexicongraphic sense, on strings <CODE>a</CODE> and
<CODE>b</CODE>. It returns 0 if the strings are identical, a negative integer
if <CODE>a</CODE> is less than <CODE>b</CODE>, or a positive integer if <CODE>a</CODE> is greater
than <CODE>b</CODE>.
<DT><B> Example </B><DD><P>The <CODE>strup</CODE> function may be used to perform a case-insensitive
string comparison:
<BLOCKQUOTE><CODE>
<PRE>
define case_insensitive_strcmp (a, b)
{
return strcmp (strup(a), strup(b));
}
</PRE>
</CODE></BLOCKQUOTE>
<DT><B> Notes </B><DD><P>One may also use one of the binary comparison operators, e.g.,
<CODE>a > b</CODE>.
<DT><B> See Also </B><DD><P><CODE>strup, strncmp</CODE>
</DL>
<P>
<P>
<H2><A NAME="strcompress"></A> <A NAME="ss3.17">3.17 <B>strcompress</B></A>
</H2>
<P>
<DL>
<DT><B> Synopsis </B><DD><P>Remove excess whitespace characters from a string
<DT><B> Usage </B><DD><P><CODE>String_Type strcompress (String_Type s, String_Type white)</CODE>
<DT><B> Description </B><DD><P>The <CODE>strcompress</CODE> function compresses the string <CODE>s</CODE> by
replacing a sequence of one or more characters from the set
<CODE>white</CODE> by the first character of <CODE>white</CODE>. In addition, it
also removes all leading and trailing characters from <CODE>s</CODE> that
are part of <CODE>white</CODE>.
<DT><B> Example </B><DD><P>The expression
<BLOCKQUOTE><CODE>
<PRE>
strcompress (",;apple,,cherry;,banana", ",;");
</PRE>
</CODE></BLOCKQUOTE>
returns the string <CODE>"apple,cherry,banana"</CODE>.
<DT><B> See Also </B><DD><P><CODE>strtrim, strtrans</CODE>
</DL>
<P>
<P>
<H2><A NAME="string_match"></A> <A NAME="ss3.18">3.18 <B>string_match</B></A>
</H2>
<P>
<DL>
<DT><B> Synopsis </B><DD><P>Match a string against a regular expression
<DT><B> Usage </B><DD><P><CODE>Integer_Type string_match(String_Type str, String_Type pat, Integer_Type pos)</CODE>
<DT><B> Description </B><DD><P>The <CODE>string_match</CODE> function returns zero if <CODE>str</CODE> does not
match regular expression specified by <CODE>pat</CODE>. This function
performs the match starting at position <CODE>pos</CODE> (numbered from 1) in
<CODE>str</CODE>. This function returns the position of the start of the
match. To find the exact substring actually matched, use
<CODE>string_match_nth</CODE>.
<DT><B> See Also </B><DD><P><CODE>string_match_nth, strcmp, strncmp</CODE>
</DL>
<P>
<P>
<H2><A NAME="string_match_nth"></A> <A NAME="ss3.19">3.19 <B>string_match_nth</B></A>
</H2>
<P>
<DL>
<DT><B> Synopsis </B><DD><P>Get the result of the last call to string_match
<DT><B> Usage </B><DD><P><CODE>(Integer_Type, Integer_Type) = string_match_nth(Integer_Type nth)</CODE>
<DT><B> Description </B><DD><P>The <CODE>string_match_nth</CODE> function returns two integers describing
the result of the last call to <CODE>string_match</CODE>. It returns both
the offset into the string and the length of characters matches by
the <CODE>nth</CODE> submatch.
<P>By convention, <CODE>nth</CODE> equal to zero means the entire match.
Otherwise, <CODE>nth</CODE> must be an integer with a value 1 through 9,
and refers to the set of characters matched by the <CODE>nth</CODE> regular
expression enclosed by the pairs <CODE>\(, \)</CODE>.
<DT><B> Example </B><DD><P>Consider:
<BLOCKQUOTE><CODE>
<PRE>
variable matched, pos, len;
matched = string_match("hello world", "\\([a-z]+\\) \\([a-z]+\\)", 1);
if (matched) (pos, len) = string_match_nth(2);
</PRE>
</CODE></BLOCKQUOTE>
This will set <CODE>matched</CODE> to 1 since a match will be found at the
first position, <CODE>pos</CODE> to 6 since <CODE>w</CODE> is offset 6 characters
from the beginning of the string, and <CODE>len</CODE> to 5 since
<CODE>"world"</CODE> is 5 characters long.
<DT><B> Notes </B><DD><P>The position offset is <EM>not</EM> affected by the value of the offset
parameter to the <CODE>string_match</CODE> function. For example, if the
value of the last parameter to the <CODE>string_match</CODE> function had
been 3, <CODE>pos</CODE> would still have been set to 6.
<P>Note also that <CODE>string_match_nth</CODE> returns the <EM>offset</EM> from
the beginning of the string and not the position of the match.
<DT><B> See Also </B><DD><P><CODE>string_match</CODE>
</DL>
<P>
<P>
<H2><A NAME="strjoin"></A> <A NAME="ss3.20">3.20 <B>strjoin</B></A>
</H2>
<P>
<DL>
<DT><B> Synopsis </B><DD><P>Concatenate elements of a string array
<DT><B> Usage </B><DD><P><CODE>String_Type strjoin (Array_Type a, String_Type delim)</CODE>
<DT><B> Description </B><DD><P>The <CODE>strjoin</CODE> function operates on an array of strings by joining
successive elements together separated with a delimiter <CODE>delim</CODE>.
If <CODE>delim</CODE> is the empty string <CODE>""</CODE>, then the result will
simply be the concatenation of the elements.
<DT><B> Example </B><DD><P>Suppose that
<BLOCKQUOTE><CODE>
<PRE>
days = ["Sun","Mon","Tue","Wed","Thu","Fri","Sat","Sun"];
</PRE>
</CODE></BLOCKQUOTE>
Then <CODE>strjoin (days,"+")</CODE> will produce
<CODE>"Sun+Mon+Tue+Wed+Thu+Fri+Sat+Sun"</CODE>. Similarly,
<CODE>strjoin (["","",""], "X")</CODE> will produce <CODE>"XX"</CODE>.
<DT><B> See Also </B><DD><P><CODE>create_delimited_string, strchop, strcat</CODE>
</DL>
<P>
<P>
<H2><A NAME="strlen"></A> <A NAME="ss3.21">3.21 <B>strlen</B></A>
</H2>
<P>
<DL>
<DT><B> Synopsis </B><DD><P>Compute the length of a string
<DT><B> Usage </B><DD><P><CODE>Integer_Type strlen (String_Type a)</CODE>
<DT><B> Description </B><DD><P>The <CODE>strlen</CODE> function may be used to compute the length of a string.
<DT><B> Example </B><DD><P>After execution of
<BLOCKQUOTE><CODE>
<PRE>
variable len = strlen ("hello");
</PRE>
</CODE></BLOCKQUOTE>
<CODE>len</CODE> will have a value of <CODE>5</CODE>.
<DT><B> See Also </B><DD><P><CODE>bstrlen, length, substr</CODE>
</DL>
<P>
<P>
<H2><A NAME="strlow"></A> <A NAME="ss3.22">3.22 <B>strlow</B></A>
</H2>
<P>
<DL>
<DT><B> Synopsis </B><DD><P>Convert a string to lowercase
<DT><B> Usage </B><DD><P><CODE>String_Type strlow (String_Type s)</CODE>
<DT><B> Description </B><DD><P>The <CODE>strlow</CODE> function takes a string <CODE>s</CODE> and returns another
string identical to <CODE>s</CODE> except that all upper case characters
that comprise <CODE>s</CODE> will be converted to lower case.
<DT><B> Example </B><DD><P>The function
<BLOCKQUOTE><CODE>
<PRE>
define Strcmp (a, b)
{
return strcmp (strlow (a), strlow (b));
}
</PRE>
</CODE></BLOCKQUOTE>
performs a case-insensitive comparison operation of two strings by
converting them to lower case first.
<DT><B> See Also </B><DD><P><CODE>strup, tolower, strcmp, strtrim, define_case</CODE>
</DL>
<P>
<P>
<H2><A NAME="strncmp"></A> <A NAME="ss3.23">3.23 <B>strncmp</B></A>
</H2>
<P>
<DL>
<DT><B> Synopsis </B><DD><P>Compare the first few characters of two strings
<DT><B> Usage </B><DD><P><CODE>Integer_Type strncmp (String_Type a, String_Type b, Integer_Type n)</CODE>
<DT><B> Description </B><DD><P>This function behaves like <CODE>strcmp</CODE> except that it compares only the
first <CODE>n</CODE> characters in the strings <CODE>a</CODE> and <CODE>b</CODE>. See
the documentation for <CODE>strcmp</CODE> for information about the return
value.
<DT><B> Example </B><DD><P>The expression
<BLOCKQUOTE><CODE>
<PRE>
strcmp ("apple", "appliance", 3);
</PRE>
</CODE></BLOCKQUOTE>
will return zero since the first three characters match.
<DT><B> See Also </B><DD><P><CODE>strcmp, strlen</CODE>
</DL>
<P>
<P>
<H2><A NAME="strreplace"></A> <A NAME="ss3.24">3.24 <B>strreplace</B></A>
</H2>
<P>
<DL>
<DT><B> Synopsis </B><DD><P>Replace one or more substrings
<DT><B> Usage </B><DD><P><CODE>(new, n) = strreplace (a, b, c, max_n)</CODE>
<BLOCKQUOTE><CODE>
<PRE>
String_Type a, b, c, rep;
Int_Type n, max_n;
</PRE>
</CODE></BLOCKQUOTE>
<DT><B> Description </B><DD><P>The <CODE>strreplace</CODE> function may be used to replace one or more
occurances of <CODE>b</CODE> in <CODE>a</CODE> with <CODE>c</CODE>. If the integer
<CODE>max_n</CODE> is positive, then the first <CODE>max_n</CODE> occurances of
<CODE>b</CODE> in <CODE>a</CODE> will be replaced. Otherwise, if <CODE>max_n</CODE> is
negative, then the last <CODE>abs(max_n)</CODE> occurances will be replaced.
<P>The function returns the resulting string and an integer indicating
how many replacements were made.
<DT><B> Example </B><DD><P>The following function illustrates how <CODE>strreplace</CODE> may be used
to remove all occurances of a specified substring
<BLOCKQUOTE><CODE>
<PRE>
define delete_substrings (a, b)
{
(a, ) = strreplace (a, b, "", strlen (a));
return a;
}
</PRE>
</CODE></BLOCKQUOTE>
<DT><B> See Also </B><DD><P><CODE>is_substr, strsub, strtrim, strtrans, str_delete_chars</CODE>
</DL>
<P>
<P>
<H2><A NAME="strsub"></A> <A NAME="ss3.25">3.25 <B>strsub</B></A>
</H2>
<P>
<DL>
<DT><B> Synopsis </B><DD><P>Replace a character with another in a string.
<DT><B> Usage </B><DD><P><CODE>String_Type strsub (String_Type s, Integer_Type pos, Integer_Type ch)</CODE>
<DT><B> Description </B><DD><P>The <CODE>strsub</CODE> character may be used to substitute the character
<CODE>ch</CODE> for the character at position <CODE>pos</CODE> of the string
<CODE>s</CODE>. The resulting string is returned.
<DT><B> Example </B><DD><P>
<BLOCKQUOTE><CODE>
<PRE>
define replace_spaces_with_comma (s)
{
variable n;
while (n = is_substr (s, " "), n) s = strsub (s, n, ',');
return s;
}
</PRE>
</CODE></BLOCKQUOTE>
For uses such as this, the <CODE>strtrans</CODE> function is a better choice.
<DT><B> Notes </B><DD><P>The first character in the string <CODE>s</CODE> is specified by <CODE>pos</CODE>
equal to 1.
<DT><B> See Also </B><DD><P><CODE>is_substr, strreplace, strlen</CODE>
</DL>
<P>
<P>
<H2><A NAME="strtok"></A> <A NAME="ss3.26">3.26 <B>strtok</B></A>
</H2>
<P>
<DL>
<DT><B> Synopsis </B><DD><P>Extract tokens from a string
<DT><B> Usage </B><DD><P><CODE>String_Type[] strtok (String_Type str [,String_Type white])</CODE>
<DT><B> Description </B><DD><P><CODE>strtok</CODE> breaks the string <CODE>str</CODE> into a series of tokens and
returns them as an array of strings. If the second parameter
<CODE>white</CODE> 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 <CODE>white</CODE> is <CODE>'^'</CODE>, then the
whitespace characters consist of all characters except those in
<CODE>white</CODE>. For example, if <CODE>white</CODE> is <CODE>" \t\n,;."</CODE>,
then those characters specifiy the whitespace characters. However,
if <CODE>white</CODE> is given by <CODE>"^a-zA-Z0-9_"</CODE>, then any character
is a whitespace character except those in the ranges <CODE>a-z</CODE>,
<CODE>A-Z</CODE>, <CODE>0-9</CODE>, and the underscore character.
<P>If the second parameter is not present, then it defaults to
<CODE>" \t\r\n\f"</CODE>.
<DT><B> Example </B><DD><P>The following example may be used to count the words in a text file:
<BLOCKQUOTE><CODE>
<PRE>
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;
}
</PRE>
</CODE></BLOCKQUOTE>
<DT><B> See Also </B><DD><P><CODE>strchop, strcompress, extract_element, strjoin</CODE>
</DL>
<P>
<P>
<H2><A NAME="strtrans"></A> <A NAME="ss3.27">3.27 <B>strtrans</B></A>
</H2>
<P>
<DL>
<DT><B> Synopsis </B><DD><P>Replace characters in a string
<DT><B> Usage </B><DD><P><CODE>String_Type strtrans (str, old_set, new_set)</CODE>
<BLOCKQUOTE><CODE>
<PRE>
String_Type str, old_set, new_set;
</PRE>
</CODE></BLOCKQUOTE>
<DT><B> Description </B><DD><P>The <CODE>strtrans</CODE> function may be used to replace all the characters
from the set <CODE>old_set</CODE> with the corresponding characters from
<CODE>new_set</CODE> in the string <CODE>str</CODE>. If <CODE>new_set</CODE> is empty,
then the characters in <CODE>new_set</CODE> will be removed from <CODE>str</CODE>.
This function returns the result.
<DT><B> Example </B><DD><P>
<BLOCKQUOTE><CODE>
<PRE>
str = strtrans (str, "A-Z", "a-z"); % lower-case str
str = strtrans (str, "^0-9", " "); % Replace anything but 0-9 by space
</PRE>
</CODE></BLOCKQUOTE>
<DT><B> See Also </B><DD><P><CODE>strreplace, strtrim, strup, strlow</CODE>
</DL>
<P>
<P>
<H2><A NAME="strtrim"></A> <A NAME="ss3.28">3.28 <B>strtrim</B></A>
</H2>
<P>
<DL>
<DT><B> Synopsis </B><DD><P>Remove whitespace from the ends of a string
<DT><B> Usage </B><DD><P><CODE>String_Type strtrim (String_Type s [,String_Type w])</CODE>
<DT><B> Description </B><DD><P>The <CODE>strtrim</CODE> function removes all leading and trailing whitespace
characters from the string <CODE>s</CODE> 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 <CODE>" \t\r\n"</CODE>.
<DT><B> See Also </B><DD><P><CODE>strtrim_beg, strtrim_end, strcompress</CODE>
</DL>
<P>
<P>
<H2><A NAME="strtrim_beg"></A> <A NAME="ss3.29">3.29 <B>strtrim_beg</B></A>
</H2>
<P>
<DL>
<DT><B> Synopsis </B><DD><P>Remove leading whitespace from a string
<DT><B> Usage </B><DD><P><CODE>String_Type strtrim_beg (String_Type s [,String_Type w])</CODE>
<DT><B> Description </B><DD><P>The <CODE>strtrim_beg</CODE> function removes all leading whitespace
characters from the string <CODE>s</CODE> 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 <CODE>" \t\r\n"</CODE>.
<DT><B> See Also </B><DD><P><CODE>strtrim, strtrim_end, strcompress</CODE>
</DL>
<P>
<P>
<H2><A NAME="strtrim_end"></A> <A NAME="ss3.30">3.30 <B>strtrim_end</B></A>
</H2>
<P>
<DL>
<DT><B> Synopsis </B><DD><P>Remove trailing whitespace from a string
<DT><B> Usage </B><DD><P><CODE>String_Type strtrim_end (String_Type s [,String_Type w])</CODE>
<DT><B> Description </B><DD><P>The <CODE>strtrim_end</CODE> function removes all trailing whitespace
characters from the string <CODE>s</CODE> 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 <CODE>" \t\r\n"</CODE>.
<DT><B> See Also </B><DD><P><CODE>strtrim, strtrim_beg, strcompress</CODE>
</DL>
<P>
<P>
<H2><A NAME="strup"></A> <A NAME="ss3.31">3.31 <B>strup</B></A>
</H2>
<P>
<DL>
<DT><B> Synopsis </B><DD><P>Convert a string to uppercase
<DT><B> Usage </B><DD><P><CODE>String_Type strup (String_Type s)</CODE>
<DT><B> Description </B><DD><P>The <CODE>strup</CODE> function takes a string <CODE>s</CODE> and returns another
string identical to <CODE>s</CODE> except that all lower case characters
that comprise <CODE>s</CODE> will be converted to upper case.
<DT><B> Example </B><DD><P>The function
<BLOCKQUOTE><CODE>
<PRE>
define Strcmp (a, b)
{
return strcmp (strup (a), strup (b));
}
</PRE>
</CODE></BLOCKQUOTE>
performs a case-insensitive comparison operation of two strings by
converting them to upper case first.
<DT><B> See Also </B><DD><P><CODE>strlow, toupper, strcmp, strtrim, define_case, strtrans</CODE>
</DL>
<P>
<P>
<H2><A NAME="substr"></A> <A NAME="ss3.32">3.32 <B>substr</B></A>
</H2>
<P>
<DL>
<DT><B> Synopsis </B><DD><P>Extract a substring from a string
<DT><B> Usage </B><DD><P><CODE>String_Type substr (String_Type s, Integer_Type n, Integer_Type len)</CODE>
<DT><B> Description </B><DD><P>The <CODE>substr</CODE> function returns a substring with length <CODE>len</CODE>
of the string <CODE>s</CODE> beginning at position <CODE>n</CODE>. If <CODE>len</CODE> is
<CODE>-1</CODE>, the entire length of the string <CODE>s</CODE> will be used for
<CODE>len</CODE>. The first character of <CODE>s</CODE> is given by <CODE>n</CODE> equal
to 1.
<DT><B> Example </B><DD><P>
<BLOCKQUOTE><CODE>
<PRE>
substr ("To be or not to be", 7, 5);
</PRE>
</CODE></BLOCKQUOTE>
returns <CODE>"or no"</CODE>
<DT><B> Notes </B><DD><P>In many cases it is more convenient to use array indexing rather
than the <CODE>substr</CODE> function. In fact, <CODE>substr(s,i+1,strlen(s))</CODE> is
equivalent to <CODE>s[[i:]]</CODE>.
<DT><B> See Also </B><DD><P><CODE>is_substr, strlen</CODE>
</DL>
<P>
<P>
<P>
<HR>
<A HREF="slangfun-4.html">Next</A>
<A HREF="slangfun-2.html">Previous</A>
<A HREF="slangfun.html#toc3">Contents</A>
</BODY>
</HTML>
