File: octave_6.html

package info (click to toggle)
octave 2.0.16-2
links: PTS
area: main
in suites: potato
size: 26,276 kB
ctags: 16,450
sloc: cpp: 67,548; fortran: 41,514; ansic: 26,682; sh: 7,361; makefile: 4,077; lex: 2,008; yacc: 1,849; lisp: 1,702; perl: 1,676; exp: 123
file content (694 lines) | stat: -rw-r--r-- 16,330 bytes
<HTML>
<HEAD>
<!-- This HTML file has been created by texi2html 1.51
     from ./octave.texi on 18 June 1999 -->

<TITLE>GNU Octave - Strings</TITLE>
</HEAD>
<BODY>
Go to the <A HREF="octave_1.html">first</A>, <A HREF="octave_5.html">previous</A>, <A HREF="octave_7.html">next</A>, <A HREF="octave_40.html">last</A> section, <A HREF="octave_toc.html">table of contents</A>.
<P><HR><P>


<H1><A NAME="SEC53" HREF="octave_toc.html#TOC53">Strings</A></H1>
<P>
<A NAME="IDX163"></A>
<A NAME="IDX164"></A>
<A NAME="IDX165"></A>
<A NAME="IDX166"></A>

</P>
<P>
A <STRONG>string constant</STRONG> consists of a sequence of characters enclosed in
either double-quote or single-quote marks.  For example, both of the
following expressions

</P>

<PRE>
"parrot"
'parrot'
</PRE>

<P>
represent the string whose contents are <SAMP>`parrot'</SAMP>.  Strings in
Octave can be of any length.

</P>
<P>
Since the single-quote mark is also used for the transpose operator
(see section <A HREF="octave_9.html#SEC69">Arithmetic Operators</A>) but double-quote marks have no other purpose in
Octave, it is best to use double-quote marks to denote strings.

</P>

<P>
<A NAME="IDX167"></A>
Some characters cannot be included literally in a string constant.  You
represent them instead with <STRONG>escape sequences</STRONG>, which are character
sequences beginning with a backslash (<SAMP>`\'</SAMP>).

</P>
<P>
One use of an escape sequence is to include a double-quote
(single-quote) character in a string constant that has been defined
using double-quote (single-quote) marks.  Since a plain double-quote
would end the string, you must use <SAMP>`\"'</SAMP> to represent a single
double-quote character as a part of the string.  The backslash character
itself is another character that cannot be included normally.  You must
write <SAMP>`\\'</SAMP> to put one backslash in the string.  Thus, the string
whose contents are the two characters <SAMP>`"\'</SAMP> may be written
<CODE>"\"\\"</CODE> or <CODE>'"\\'</CODE>.  Similarly, the string whose contents are
the two characters <SAMP>`'\'</SAMP> may be written <CODE>'\'\\'</CODE> or <CODE>"'\\"</CODE>.

</P>
<P>
Another use of backslash is to represent unprintable characters
such as newline.  While there is nothing to stop you from writing most
of these characters directly in a string constant, they may look ugly.

</P>
<P>
Here is a table of all the escape sequences used in Octave.  They are
the same as those used in the C programming language.

</P>
<DL COMPACT>

<DT><CODE>\\</CODE>
<DD>
Represents a literal backslash, <SAMP>`\'</SAMP>.

<DT><CODE>\"</CODE>
<DD>
Represents a literal double-quote character, <SAMP>`"'</SAMP>.

<DT><CODE>\'</CODE>
<DD>
Represents a literal single-quote character, <SAMP>`''</SAMP>.

<DT><CODE>\a</CODE>
<DD>
Represents the "alert" character, control-g, ASCII code 7.

<DT><CODE>\b</CODE>
<DD>
Represents a backspace, control-h, ASCII code 8.

<DT><CODE>\f</CODE>
<DD>
Represents a formfeed, control-l, ASCII code 12.

<DT><CODE>\n</CODE>
<DD>
Represents a newline, control-j, ASCII code 10.

<DT><CODE>\r</CODE>
<DD>
Represents a carriage return, control-m, ASCII code 13.

<DT><CODE>\t</CODE>
<DD>
Represents a horizontal tab, control-i, ASCII code 9.

<DT><CODE>\v</CODE>
<DD>
Represents a vertical tab, control-k, ASCII code 11.

</DL>

<P>
Strings may be concatenated using the notation for defining matrices.
For example, the expression

</P>

<PRE>
[ "foo" , "bar" , "baz" ]
</PRE>

<P>
produces the string whose contents are <SAMP>`foobarbaz'</SAMP>.  See section <A HREF="octave_5.html#SEC48">Numeric Data Types</A> for more information about creating matrices.

</P>



<H2><A NAME="SEC54" HREF="octave_toc.html#TOC54">Creating Strings</A></H2>

<P>
<DL>
<DT><U>Function File:</U>  <B>blanks</B> <I>(<VAR>n</VAR>)</I>
<DD><A NAME="IDX168"></A>
Return a string of <VAR>n</VAR> blanks.
</DL>

</P>
<P>
<DL>
<DT><U>Function File:</U>  <B>int2str</B> <I>(<VAR>n</VAR>)</I>
<DD><A NAME="IDX169"></A>
<DT><U>Function File:</U>  <B>num2str</B> <I>(<VAR>x</VAR>)</I>
<DD><A NAME="IDX170"></A>
Convert a number to a string.  These functions are not very flexible,
but are provided for compatibility with MATLAB.  For better control
over the results, use <CODE>sprintf</CODE> (see section <A HREF="octave_14.html#SEC109">Formatted Output</A>).
</DL>

</P>
<P>
<DL>
<DT><U>Built-in Function:</U>  <B>setstr</B> <I>(<VAR>x</VAR>)</I>
<DD><A NAME="IDX171"></A>
Convert a matrix to a string.  Each element of the matrix is converted
to the corresponding ASCII 
character.  For example,

</P>

<PRE>
setstr ([97, 98, 99])
     => "abc"
</PRE>

</DL>

<P>
<DL>
<DT><U>Function File:</U>  <B>strcat</B> <I>(<VAR>s1</VAR>, <VAR>s2</VAR>, ...)</I>
<DD><A NAME="IDX172"></A>
Return a string containing all the arguments concatenated.  For example,

</P>

<PRE>
s = [ "ab"; "cde" ];
strcat (s, s, s)
     => "ab ab ab "
        "cdecdecde"
</PRE>

</DL>

<P>
<DL>
<DT><U>Built-in Variable:</U> <B>string_fill_char</B>
<DD><A NAME="IDX173"></A>
The value of this variable is used to pad all strings in a string matrix
to the same length.  It should be a single character.  The default value
is <CODE>" "</CODE> (a single space).  For example,

</P>

<PRE>
string_fill_char = "X";
[ "these"; "are"; "strings" ]
     => "theseXX"
        "areXXXX"
        "strings"
</PRE>

</DL>

<P>
<DL>
<DT><U>Function File:</U>  <B>str2mat</B> <I>(<VAR>s_1</VAR>, ..., <VAR>s_n</VAR>)</I>
<DD><A NAME="IDX174"></A>
Return a matrix containing the strings <VAR>s_1</VAR>, ..., <VAR>s_n</VAR> as
its rows.  Each string is padded with blanks in order to form a valid
matrix.

</P>
<P>
<STRONG>Note:</STRONG>
This function is modelled after MATLAB.  In Octave, you can create
a matrix of strings by <CODE>[<VAR>s_1</VAR>; ...; <VAR>s_n</VAR>]</CODE> even if
the strings are not all the same length.
</DL>

</P>
<P>
<DL>
<DT><U>Built-in Function:</U>  <B>isstr</B> <I>(<VAR>a</VAR>)</I>
<DD><A NAME="IDX175"></A>
Return 1 if <VAR>a</VAR> is a string.  Otherwise, return 0.
</DL>

</P>


<H2><A NAME="SEC55" HREF="octave_toc.html#TOC55">Searching and Replacing</A></H2>

<P>
<DL>
<DT><U>Function File:</U>  <B>deblank</B> <I>(<VAR>s</VAR>)</I>
<DD><A NAME="IDX176"></A>
Removes the trailing blanks from the string <VAR>s</VAR>. 
</DL>

</P>
<P>
<DL>
<DT><U>Function File:</U>  <B>findstr</B> <I>(<VAR>s</VAR>, <VAR>t</VAR>, <VAR>overlap</VAR>)</I>
<DD><A NAME="IDX177"></A>
Return the vector of all positions in the longer of the two strings
<VAR>s</VAR> and <VAR>t</VAR> where an occurrence of the shorter of the two starts.
If the optional argument <VAR>overlap</VAR> is nonzero, the returned vector
can include overlapping positions (this is the default).  For example,

</P>

<PRE>
findstr ("ababab", "a")
     => [ 1, 3, 5 ]
findstr ("abababa", "aba", 0)
     => [ 1, 5 ]
</PRE>

</DL>

<P>
<DL>
<DT><U>Function File:</U>  <B>index</B> <I>(<VAR>s</VAR>, <VAR>t</VAR>)</I>
<DD><A NAME="IDX178"></A>
Return the position of the first occurrence of the string <VAR>t</VAR> in the
string <VAR>s</VAR>, or 0 if no occurrence is found.  For example,

</P>

<PRE>
index ("Teststring", "t")
     => 4
</PRE>

<P>
<STRONG>Note:</STRONG>  This function does not work for arrays of strings.
</DL>

</P>
<P>
<DL>
<DT><U>Function File:</U>  <B>rindex</B> <I>(<VAR>s</VAR>, <VAR>t</VAR>)</I>
<DD><A NAME="IDX179"></A>
Return the position of the last occurrence of the string <VAR>t</VAR> in the
string <VAR>s</VAR>, or 0 if no occurrence is found.  For example,

</P>

<PRE>
rindex ("Teststring", "t")
     => 6
</PRE>

<P>
<STRONG>Note:</STRONG>  This function does not work for arrays of strings.
</DL>

</P>
<P>
<DL>
<DT><U>Function File:</U>  <B>split</B> <I>(<VAR>s</VAR>, <VAR>t</VAR>)</I>
<DD><A NAME="IDX180"></A>
Divides the string <VAR>s</VAR> into pieces separated by <VAR>t</VAR>, returning
the result in a string array (padded with blanks to form a valid
matrix).  For example,

</P>

<PRE>
split ("Test string", "t")
     => "Tes "
        " s  "
        "ring"
</PRE>

</DL>

<P>
<DL>
<DT><U>Function File:</U>  <B>strcmp</B> <I>(<VAR>s1</VAR>, <VAR>s2</VAR>)</I>
<DD><A NAME="IDX181"></A>
Compares two strings, returning 1 if they are the same, and 0 otherwise.

</P>
<P>
<STRONG>Note:</STRONG>  For compatibility with MATLAB, Octave's strcmp
function returns 1 if the strings are equal, and 0 otherwise.  This is
just the opposite of the corresponding C library function.
</DL>

</P>
<P>
<DL>
<DT><U>Function File:</U>  <B>strrep</B> <I>(<VAR>s</VAR>, <VAR>x</VAR>, <VAR>y</VAR>)</I>
<DD><A NAME="IDX182"></A>
Replaces all occurrences of the substring <VAR>x</VAR> of the string <VAR>s</VAR>
with the string <VAR>y</VAR>.  For example,

</P>

<PRE>
strrep ("This is a test string", "is", "&#38;%$")
     => "Th&#38;%$ &#38;%$ a test string"
</PRE>

</DL>

<P>
<DL>
<DT><U>Function File:</U>  <B>substr</B> <I>(<VAR>s</VAR>, <VAR>beg</VAR>, <VAR>len</VAR>)</I>
<DD><A NAME="IDX183"></A>
Return the substring of <VAR>s</VAR> which starts at character number
<VAR>beg</VAR> and is <VAR>len</VAR> characters long.  For example,

</P>

<PRE>
substr ("This is a test string", 6, 9)
     => "is a test"
</PRE>


<BLOCKQUOTE>
<P>
<STRONG>Note:</STRONG>
This function is patterned after AWK.  You can get the same result by
<CODE><VAR>s</VAR> (<VAR>beg</VAR> : (<VAR>beg</VAR> + <VAR>len</VAR> - 1))</CODE>.  
</BLOCKQUOTE>

</DL>



<H2><A NAME="SEC56" HREF="octave_toc.html#TOC56">String Conversions</A></H2>

<P>
<DL>
<DT><U>Function File:</U>  <B>bin2dec</B> <I>(<VAR>s</VAR>)</I>
<DD><A NAME="IDX184"></A>
Return a decimal number corresponding to the binary number
represented as a string of zeros and ones.  For example,

</P>

<PRE>
bin2dec ("1110")
     => 14
</PRE>

</DL>

<P>
<DL>
<DT><U>Function File:</U>  <B>dec2bin</B> <I>(<VAR>n</VAR>)</I>
<DD><A NAME="IDX185"></A>
Return a binary number corresponding the nonnegative decimal number
<VAR>n</VAR>, as a string of ones and zeros.  For example,

</P>

<PRE>
dec2bin (14)
     => "1110"
</PRE>

</DL>

<P>
<DL>
<DT><U>Function File:</U>  <B>dec2hex</B> <I>(<VAR>n</VAR>)</I>
<DD><A NAME="IDX186"></A>
Return the hexadecimal number corresponding to the nonnegative decimal
number <VAR>n</VAR>, as a string.  For example,

</P>

<PRE>
dec2hex (2748)
     => "abc"
</PRE>

</DL>

<P>
<DL>
<DT><U>Function File:</U>  <B>hex2dec</B> <I>(<VAR>s</VAR>)</I>
<DD><A NAME="IDX187"></A>
Return the decimal number corresponding to the hexadecimal number stored
in the string <VAR>s</VAR>.  For example,

</P>

<PRE>
hex2dec ("12B")
     => 299
hex2dec ("12b")
     => 299
</PRE>

</DL>

<P>
<DL>
<DT><U>Function File:</U>  <B>str2num</B> <I>(<VAR>s</VAR>)</I>
<DD><A NAME="IDX188"></A>
Convert the string <VAR>s</VAR> to a number.
</DL>

</P>
<P>
<DL>
<DT><U>Function File:</U>  <B>toascii</B> <I>(<VAR>s</VAR>)</I>
<DD><A NAME="IDX189"></A>
Return ASCII representation of <VAR>s</VAR> in a matrix.  For example,

</P>

<PRE>
toascii ("ASCII")
     => [ 65, 83, 67, 73, 73 ]

</PRE>

</DL>

<P>
<DL>
<DT><U>Function File:</U>  <B>tolower</B> <I>(<VAR>s</VAR>)</I>
<DD><A NAME="IDX190"></A>
Return a copy of the string <VAR>s</VAR>, with each upper-case character
replaced by the corresponding lower-case one; nonalphabetic characters
are left unchanged.  For example,

</P>

<PRE>
tolower ("MiXeD cAsE 123")
     => "mixed case 123"
</PRE>

</DL>

<P>
<DL>
<DT><U>Function File:</U>  <B>toupper</B> <I>(<VAR>s</VAR>)</I>
<DD><A NAME="IDX191"></A>
Return a copy of the string <VAR>s</VAR>, with each  lower-case character
replaced by the corresponding upper-case one; nonalphabetic characters
are left unchanged.  For example,

</P>

<PRE>
toupper ("MiXeD cAsE 123")
     => "MIXED CASE 123"
</PRE>

</DL>

<P>
<DL>
<DT><U>Built-in Function:</U>  <B>undo_string_escapes</B> <I>(<VAR>s</VAR>)</I>
<DD><A NAME="IDX192"></A>
Converts special characters in strings back to their escaped forms.  For
example, the expression

</P>

<PRE>
bell = "\a";
</PRE>

<P>
assigns the value of the alert character (control-g, ASCII code 7) to
the string variable <CODE>bell</CODE>.  If this string is printed, the
system will ring the terminal bell (if it is possible).  This is
normally the desired outcome.  However, sometimes it is useful to be
able to print the original representation of the string, with the
special characters replaced by their escape sequences.  For example,

</P>

<PRE>
octave:13&#62; undo_string_escapes (bell)
ans = \a
</PRE>

<P>
replaces the unprintable alert character with its printable
representation.
</DL>

</P>
<P>
<DL>
<DT><U>Built-in Variable:</U> <B>implicit_num_to_str_ok</B>
<DD><A NAME="IDX193"></A>
If the value of <CODE>implicit_num_to_str_ok</CODE> is nonzero, implicit
conversions of numbers to their ASCII character equivalents are
allowed when strings are constructed using a mixture of strings and
numbers in matrix notation.  Otherwise, an error message is printed and
control is returned to the top level. The default value is 0.  For
example,

</P>

<PRE>
[ "f", 111, 111 ]
     => "foo"
</PRE>

</DL>

<P>
<DL>
<DT><U>Built-in Variable:</U> <B>implicit_str_to_num_ok</B>
<DD><A NAME="IDX194"></A>
If the value of <CODE>implicit_str_to_num_ok</CODE> is nonzero, implicit
conversions of strings to their numeric ASCII equivalents are allowed.
Otherwise, an error message is printed and control is returned to the
top level.  The default value is 0.
</DL>

</P>


<H2><A NAME="SEC57" HREF="octave_toc.html#TOC57">Character Class Functions</A></H2>

<P>
Octave also provides the following character class test functions
patterned after the functions in the standard C library.  They all
operate on string arrays and return matrices of zeros and ones.
Elements that are nonzero indicate that the condition was true for the
corresponding character in the string array.  For example,

</P>

<PRE>
isalpha ("!Q@WERT^Y&#38;")
     => [ 0, 1, 0, 1, 1, 1, 1, 0, 1, 0 ]
</PRE>

<P>
<DL>
<DT><U>Mapping Function:</U>  <B>isalnum</B> <I>(<VAR>s</VAR>)</I>
<DD><A NAME="IDX195"></A>
Return 1 for characters that are letters or digits (<CODE>isalpha
(<VAR>a</VAR>)</CODE> or <CODE>isdigit (<VAR></CODE>)</VAR> is true).
</DL>

</P>
<P>
<DL>
<DT><U>Mapping Function:</U>  <B>isalpha</B> <I>(<VAR>s</VAR>)</I>
<DD><A NAME="IDX196"></A>
Return true for characters that are letters (<CODE>isupper (<VAR>a</VAR>)</CODE>
or <CODE>islower (<VAR></CODE>)</VAR> is true). 
</DL>

</P>
<P>
<DL>
<DT><U>Mapping Function:</U>  <B>isascii</B> <I>(<VAR>s</VAR>)</I>
<DD><A NAME="IDX197"></A>
Return 1 for characters that are ASCII (in the range 0 to 127 decimal).
</DL>

</P>
<P>
<DL>
<DT><U>Mapping Function:</U>  <B>iscntrl</B> <I>(<VAR>s</VAR>)</I>
<DD><A NAME="IDX198"></A>
Return 1 for control characters.
</DL>

</P>
<P>
<DL>
<DT><U>Mapping Function:</U>  <B>isdigit</B> <I>(<VAR>s</VAR>)</I>
<DD><A NAME="IDX199"></A>
Return 1 for characters that are decimal digits.
</DL>

</P>
<P>
<DL>
<DT><U>Mapping Function:</U>  <B>isgraph</B> <I>(<VAR>s</VAR>)</I>
<DD><A NAME="IDX200"></A>
Return 1 for printable characters (but not the space character).
</DL>

</P>
<P>
<DL>
<DT><U>Mapping Function:</U>  <B>islower</B> <I>(<VAR>s</VAR>)</I>
<DD><A NAME="IDX201"></A>
Return 1 for characters that are lower case letters.
</DL>

</P>
<P>
<DL>
<DT><U>Mapping Function:</U>  <B>isprint</B> <I>(<VAR>s</VAR>)</I>
<DD><A NAME="IDX202"></A>
Return 1 for printable characters (including the space character).
</DL>

</P>
<P>
<DL>
<DT><U>Mapping Function:</U>  <B>ispunct</B> <I>(<VAR>s</VAR>)</I>
<DD><A NAME="IDX203"></A>
Return 1 for punctuation characters.
</DL>

</P>
<P>
<DL>
<DT><U>Mapping Function:</U>  <B>isspace</B> <I>(<VAR>s</VAR>)</I>
<DD><A NAME="IDX204"></A>
Return 1 for whitespace characters (space, formfeed, newline,
carriage return, tab, and vertical tab).
</DL>

</P>
<P>
<DL>
<DT><U>Mapping Function:</U>  <B>isupper</B> <I>(<VAR>s</VAR>)</I>
<DD><A NAME="IDX205"></A>
Return 1 for upper case letters.
</DL>

</P>
<P>
<DL>
<DT><U>Mapping Function:</U>  <B>isxdigit</B> <I>(<VAR>s</VAR>)</I>
<DD><A NAME="IDX206"></A>
Return 1 for characters that are hexadecimal digits.
</DL>

</P>
<P><HR><P>
Go to the <A HREF="octave_1.html">first</A>, <A HREF="octave_5.html">previous</A>, <A HREF="octave_7.html">next</A>, <A HREF="octave_40.html">last</A> section, <A HREF="octave_toc.html">table of contents</A>.
</BODY>
</HTML>