@c DO NOT EDIT!  Generated automatically by munge-texi.

@c Copyright (C) 1996, 1997, 1999, 2000, 2002, 2003, 2004, 2005,
@c               2006, 2007 John W. Eaton
@c
@c This file is part of Octave.
@c
@c Octave is free software; you can redistribute it and/or modify it
@c under the terms of the GNU General Public License as published by the
@c Free Software Foundation; either version 3 of the License, or (at
@c your option) any later version.
@c 
@c Octave is distributed in the hope that it will be useful, but WITHOUT
@c ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
@c FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
@c for more details.
@c 
@c You should have received a copy of the GNU General Public License
@c along with Octave; see the file COPYING.  If not, see
@c <http://www.gnu.org/licenses/>.

@node Strings
@chapter Strings
@cindex strings
@cindex character strings
@opindex "
@opindex '

A @dfn{string constant} consists of a sequence of characters enclosed in
either double-quote or single-quote marks.  For example, both of the
following expressions

@example
@group
"parrot"
'parrot'
@end group
@end example

@noindent
represent the string whose contents are @samp{parrot}.  Strings in
Octave can be of any length.

Since the single-quote mark is also used for the transpose operator
(@pxref{Arithmetic Ops}) but double-quote marks have no other purpose in
Octave, it is best to use double-quote marks to denote strings.

@cindex escape sequence notation
In double-quoted strings, the backslash character is used to introduce
@dfn{escape sequences} that represent other characters.  For example,
@samp{\n} embeds a newline character in a double-quoted string and
@samp{\"} embeds a double quote character.

In single-quoted strings, backslash is not a special character.

Here is an example showing the difference

@example
@group
toascii ("\n")
    @result{} 10
toascii ('\n')
    @result{} [ 92 110 ]
@end group
@end example

You may also insert a single quote character in a single-quoted string
by using two single quote characters in succession.  For example,

@example
'I can''t escape'
    @result{} I can't escape
@end example

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

@table @code
@item \\
Represents a literal backslash, @samp{\}.

@item \"
Represents a literal double-quote character, @samp{"}.

@item \'
Represents a literal single-quote character, @samp{'}.

@item \0
Represents the ``nul'' character, control-@@, ASCII code 0.

@item \a
Represents the ``alert'' character, control-g, ASCII code 7.

@item \b
Represents a backspace, control-h, ASCII code 8.

@item \f
Represents a formfeed, control-l, ASCII code 12.

@item \n
Represents a newline, control-j, ASCII code 10.

@item \r
Represents a carriage return, control-m, ASCII code 13.

@item \t
Represents a horizontal tab, control-i, ASCII code 9.

@item \v
Represents a vertical tab, control-k, ASCII code 11.

@c We don't do octal or hex this way yet.
@c
@c @item \@var{nnn}
@c Represents the octal value @var{nnn}, where @var{nnn} are one to three
@c digits between 0 and 7.  For example, the code for the ASCII ESC
@c (escape) character is @samp{\033}.@refill
@c 
@c @item \x@var{hh}@dots{}
@c Represents the hexadecimal value @var{hh}, where @var{hh} are hexadecimal
@c digits (@samp{0} through @samp{9} and either @samp{A} through @samp{F} or
@c @samp{a} through @samp{f}).  Like the same construct in @sc{ansi} C,
@c the escape 
@c sequence continues until the first non-hexadecimal digit is seen.  However,
@c using more than two hexadecimal digits produces undefined results.  (The
@c @samp{\x} escape sequence is not allowed in @sc{posix} @code{awk}.)@refill
@end table

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

@example
[ "foo" , "bar" , "baz" ]
@end example

@noindent
produces the string whose contents are @samp{foobarbaz}.  @xref{Numeric
Data Types}, for more information about creating matrices.

@menu
* Creating Strings:: 
* Comparing Strings::           
* Manipulating Strings::     
* String Conversions::          
* Character Class Functions::   
@end menu

@node Creating Strings
@section Creating Strings

The easiest way to create a string is, as illustrated in the introduction,
to enclose a text in double-quotes or single-quotes. It is however
possible to create a string without actually writing a text. The
function @code{blanks} creates a string of a given length consisting
only of blank characters (ASCII code 32).

@anchor{doc-blanks}
@deftypefn {Function File} {} blanks (@var{n})
Return a string of @var{n} blanks.
@seealso{repmat}
@end deftypefn


The string representation used by Octave is an array of characters, so
the result of @code{blanks(10)} is actually a row vector of length 10
containing the value 32 in all places. This lends itself to the obvious
generalisation to character matrices. Using a matrix of characters, it
is possible to represent a collection of same-length strings in one
variable. The convention used in Octave is that each row in a
character matrix is a separate string, but letting each column represent
a string is equally possible.

The easiest way to create a character matrix is to put several strings
together into a matrix.

@example
collection = [ "String #1"; "String #2" ];
@end example

@noindent
This creates a 2-by-9 character matrix.

One relevant question is, what happens when character matrix is
created from strings of different length. The answer is that Octave
puts blank characters at the end of strings shorter than the longest
string. While it is possible to use a different character than the
blank character using the @code{string_fill_char} function, it shows
a problem with character matrices. It simply isn't possible to
represent strings of different lengths. The solution is to use a cell
array of strings, which is described in @ref{Cell Arrays of Strings}.

@anchor{doc-char}
@deftypefn {Built-in Function} {} char (@var{x})
@deftypefnx {Built-in Function} {} char (@var{cell_array})
@deftypefnx {Built-in Function} {} char (@var{s1}, @var{s2}, @dots{})
Create a string array from a numeric matrix, cell array, or list of

If the argument is a numeric matrix, each element of the matrix is
converted to the corresponding ASCII character.  For example,

@example
@group
char ([97, 98, 99])
     @result{} "abc"
@end group
@end example

If the argument is a cell array of strings, the result is a string array
with each element corresponding to one element of the cell array.

For multiple string arguments, the result is a string array with each
element corresponding to the arguments.

The returned values are padded with blanks as needed to make each row
of the string array have the same length.
@end deftypefn


@anchor{doc-strcat}
@deftypefn {Function File} {} strcat (@var{s1}, @var{s2}, @dots{})
Return a string containing all the arguments concatenated.  For example,

@example
@group
s = [ "ab"; "cde" ];
strcat (s, s, s)
@result{} "ab ab ab "
        "cdecdecde"
@end group
@end example
@end deftypefn


@anchor{doc-strvcat}
@deftypefn {Function File} {} strvcat (@var{s_1}, @dots{}, @var{s_n})
Return a matrix containing the strings (and cell-strings) 
@var{s_1}, @dots{}, @var{s_n} as
its rows.  Each string is padded with blanks in order to form a valid
matrix.  Unlike @var{str2mat}, empty strings are ignored.
@seealso{strcat, str2mat}
@end deftypefn


@anchor{doc-strtrunc}
@deftypefn {Function File} {} strtrunc (@var{s}, @var{n})
Truncate the character string @var{s} to length @var{n}. If @var{s}
is a char matrix, then the number of columns are adjusted.

If @var{s} is a cell array of strings, then the operation is performed
on its members and the new cell array is returned.
@end deftypefn


@anchor{doc-string_fill_char}
@deftypefn {Built-in Function} {@var{val} =} string_fill_char ()
@deftypefnx {Built-in Function} {@var{old_val} =} string_fill_char (@var{new_val})
Query or set the internal variable used to pad all rows of a character
matrix to the same length.  It must be a single character.  The default
value is @code{" "} (a single space).  For example,

@example
@group
string_fill_char ("X");
[ "these"; "are"; "strings" ]
     @result{} "theseXX"
        "areXXXX"
        "strings"
@end group
@end example
@end deftypefn


@anchor{doc-str2mat}
@deftypefn {Function File} {} str2mat (@var{s_1}, @dots{}, @var{s_n})
Return a matrix containing the strings @var{s_1}, @dots{}, @var{s_n} as
its rows.  Each string is padded with blanks in order to form a valid
matrix.

This function is modelled after @sc{Matlab}.  In Octave, you can create
a matrix of strings by @code{[@var{s_1}; @dots{}; @var{s_n}]} even if
the strings are not all the same length.
@end deftypefn


@anchor{doc-ischar}
@deftypefn {Built-in Function} {} ischar (@var{a})
Return 1 if @var{a} is a string.  Otherwise, return 0.
@end deftypefn


@anchor{doc-mat2str}
@deftypefn {Function File} {@var{s} =} mat2str (@var{x}, @var{n})
@deftypefnx {Function File} {@var{s} =} mat2str (@dots{}, 'class')

Format real/complex numerical matrices as strings. This function
returns values that are suitable for the use of the @code{eval}
function.

The precision of the values is given by @var{n}. If @var{n} is a
scalar then both real and imaginary parts of the matrix are printed
to the same precision. Otherwise @code{@var{n} (1)} defines the
precision of the real part and @code{@var{n} (2)} defines the
precision of the imaginary part. The default for @var{n} is 17.

If the argument 'class' is given, then the class of @var{x} is
included in the string in such a way that the eval will result in the
construction of a matrix of the same class.

@example
@group
   mat2str( [ -1/3 + i/7; 1/3 - i/7 ], [4 2] )
@result{} '[-0.3333+0.14i;0.3333-0.14i]'
   mat2str( [ -1/3 +i/7; 1/3 -i/7 ], [4 2] )
@result{} '[-0.3333+0i,0+0.14i;0.3333+0i,-0-0.14i]'
   mat2str( int16([1 -1]), 'class')
@result{} 'int16([1,-1])'
@end group
@end example

@seealso{sprintf, int2str}
@end deftypefn


@anchor{doc-num2str}
@deftypefn {Function File} {} num2str (@var{n})
@deftypefnx {Function File} {} num2str (@var{x}, @var{precision})
@deftypefnx {Function File} {} num2str (@var{x}, @var{format})
Convert a number to a string.  This function is not very flexible.
For better control over the results, use @code{sprintf}
(@pxref{Formatted Output}).
@seealso{sprintf, int2str}
@end deftypefn


@anchor{doc-int2str}
@deftypefn {Function File} {} int2str (@var{n})
Convert an integer to a string.  This function is not very flexible.
For better control over the results, use @code{sprintf}
(@pxref{Formatted Output}). 
@seealso{sprintf, num2str}
@end deftypefn


@node Comparing Strings
@section Comparing Strings

Since a string is a character array comparison between strings work
element by element as the following example shows.

@example
GNU = "GNU's Not UNIX";
spaces = (GNU == " ")
@result{} spaces =
      0   0   0   0   0   1   0   0   0   1   0   0   0   0
@end example

@noindent
To determine if two functions are identical it is therefore necessary
to use the @code{strcmp} or @code{strncpm} functions. Similar 
functions exist for doing case-insensitive comparisons.

@anchor{doc-strcmp}
@deftypefn {Built-in Function} {} strcmp (@var{s1}, @var{s2})
Return 1 if the character strings @var{s1} and @var{s2} are the same,
and 0 otherwise.

If either @var{s1} or @var{s2} is a cell array of strings, then an array
of the same size is returned, containing the values described above for
every member of the cell array. The other argument may also be a cell
array of strings (of the same size or with only one element), char matrix
or character string.

@strong{Caution:} For compatibility with @sc{Matlab}, Octave's strcmp
function returns 1 if the character strings are equal, and 0 otherwise.
This is just the opposite of the corresponding C library function.
@seealso{strcmpi, strncmp, strncmpi}
@end deftypefn


@anchor{doc-strcmpi}
@deftypefn {Function File} {} strcmpi (@var{s1}, @var{s2})
Ignoring case, return 1 if the character strings @var{s1} and @var{s2}
are the same, and 0 otherwise.

If either @var{s1} or @var{s2} is a cell array of strings, then an array
of the same size is returned, containing the values described above for
every member of the cell array. The other argument may also be a cell
array of strings (of the same size or with only one element), char matrix
or character string.

@strong{Caution:} For compatibility with @sc{Matlab}, Octave's strcmpi
function returns 1 if the character strings are equal, and 0 otherwise.
This is just the opposite of the corresponding C library function.
@seealso{strcmp, strncmp, strncmpi}
@end deftypefn


@anchor{doc-strncmp}
@deftypefn {Built-in Function} {} strncmp (@var{s1}, @var{s2}, @var{n})
Return 1 if the first @var{n} characters of strings @var{s1} and @var{s2} are the same,
and 0 otherwise.

@example
@group
strncmp ("abce", "abcd", 3)
     @result{} 1
@end group
@end example

If either @var{s1} or @var{s2} is a cell array of strings, then an array
of the same size is returned, containing the values described above for
every member of the cell array. The other argument may also be a cell
array of strings (of the same size or with only one element), char matrix
or character string.

@example
@group
strncmp ("abce", @{"abcd", "bca", "abc"@}, 3)
     @result{} [1, 0, 1]
@end group
@end example

@strong{Caution:} For compatibility with @sc{Matlab}, Octave's strncmp
function returns 1 if the character strings are equal, and 0 otherwise.
This is just the opposite of the corresponding C library function.
@seealso{strncmpi, strcmp, strcmpi}
@end deftypefn


@anchor{doc-strncmpi}
@deftypefn {Function File} {} strncmpi (@var{s1}, @var{s2}, @var{n})
Ignoring case, return 1 if the first @var{n} characters of character
strings @var{s1} and @var{s2} are the same, and 0 otherwise.

If either @var{s1} or @var{s2} is a cell array of strings, then an array
of the same size is returned, containing the values described above for
every member of the cell array. The other argument may also be a cell
array of strings (of the same size or with only one element), char matrix
or character string.

@strong{Caution:} For compatibility with @sc{Matlab}, Octave's strncmpi
function returns 1 if the character strings are equal, and 0 otherwise.
This is just the opposite of the corresponding C library function.
@seealso{strcmp, strcmpi, strncmp}
@end deftypefn


@node Manipulating Strings
@section Manipulating Strings

Octave supports a wide range of functions for manipulating strings.
Since a string is just a matrix, simple manipulations can be accomplished
using standard operators. The following example shows how to replace
all blank characters with underscores.

@example
quote = ...
  "First things first, but not necessarily in that order";
quote( quote == " " ) = "_"
@result{} quote = 
    First_things_first,_but_not_necessarily_in_that_order
@end example

For more complex manipulations, such as searching, replacing, and
general regular expressions, the following functions come with Octave.

@anchor{doc-deblank}
@deftypefn {Function File} {} deblank (@var{s})
Remove trailing blanks and nulls from @var{s}.  If @var{s}
is a matrix, @var{deblank} trims each row to the length of longest
string.  If @var{s} is a cell array, operate recursively on each
element of the cell array.
@end deftypefn


@anchor{doc-findstr}
@deftypefn {Function File} {} findstr (@var{s}, @var{t}, @var{overlap})
Return the vector of all positions in the longer of the two strings
@var{s} and @var{t} where an occurrence of the shorter of the two starts.
If the optional argument @var{overlap} is nonzero, the returned vector
can include overlapping positions (this is the default).  For example,

@example
findstr ("ababab", "a")
@result{} [ 1, 3, 5 ]
findstr ("abababa", "aba", 0)
@result{} [ 1, 5 ]
@end example
@end deftypefn


@anchor{doc-index}
@deftypefn {Function File} {} index (@var{s}, @var{t})
@deftypefnx {Function File} {} index (@var{s}, @var{t}, @var{direction})
Return the position of the first occurrence of the string @var{t} in the
string @var{s}, or 0 if no occurrence is found.  For example,

@example
index ("Teststring", "t")
@result{} 4
@end example

If @var{direction} is @samp{"first"}, return the first element found.
If @var{direction} is @samp{"last"}, return the last element found.
The @code{rindex} function is equivalent to @code{index} with
@var{direction} set to @samp{"last"}.

@strong{Caution:}  This function does not work for arrays of
character strings.
@seealso{find, rindex}
@end deftypefn


@anchor{doc-rindex}
@deftypefn {Function File} {} rindex (@var{s}, @var{t})
Return the position of the last occurrence of the character string
@var{t} in the character string @var{s}, or 0 if no occurrence is
found.  For example,

@example
rindex ("Teststring", "t")
@result{} 6
@end example

@strong{Caution:}  This function does not work for arrays of
character strings.
@seealso{find, index}
@end deftypefn


@anchor{doc-strfind}
@deftypefn {Function File} {@var{idx} =} strfind (@var{str}, @var{pattern})
@deftypefnx {Function File} {@var{idx} =} strfind (@var{cellstr}, @var{pattern})
Search for @var{pattern} in the string @var{str} and return the
starting index of every such occurrence in the vector @var{idx}.
If there is no such occurrence, or if @var{pattern} is longer
than @var{str}, then @var{idx} is the empty array @code{[]}.

If the cell array of strings @var{cellstr} is specified instead of the
string @var{str}, then @var{idx} is a cell array of vectors, as specified
above.
@seealso{findstr, strmatch, strcmp, strncmp, strcmpi, strncmpi}
@end deftypefn


@anchor{doc-strmatch}
@deftypefn {Function File} {} strmatch (@var{s}, @var{a}, "exact")
Return indices of entries of @var{a} that match the string @var{s}.
The second argument @var{a} may be a string matrix or a cell array of
strings.  If the third argument @code{"exact"} is not given, then
@var{s} only needs to match @var{a} up to the length of @var{s}.  Nul
characters match blanks.  Results are returned as a column vector.
@end deftypefn


@anchor{doc-strtok}
@deftypefn {Function File} {[@var{tok}, @var{rem}] =} strtok (@var{str}, @var{delim})

Find all characters up to but not including the first character which
is in the string delim.  If @var{rem} is requested, it contains the
remainder of the string, starting at the first deliminator. Leading
delimiters are ignored.  If @var{delim} is not specified, space is assumed.

@end deftypefn


@anchor{doc-split}
@deftypefn {Function File} {} split (@var{s}, @var{t}, @var{n})
Divides the string @var{s} into pieces separated by @var{t}, returning
the result in a string array (padded with blanks to form a valid
matrix).  If the optional input @var{n} is supplied, split @var{s}
into at most @var{n} different pieces.

For example,

@example
split ("Test string", "t")
@result{} "Tes "
        " s  "
        "ring"
@end example

@example
split ("Test string", "t", 2)
@result{} "Tes    "
        " string"
@end example
@end deftypefn


@anchor{doc-strrep}
@deftypefn {Function File} {} strrep (@var{s}, @var{x}, @var{y})
Replaces all occurrences of the substring @var{x} of the string @var{s}
with the string @var{y} and returns the result.  For example,

@example
strrep ("This is a test string", "is", "&%$")
@result{} "Th&%$ &%$ a test string"
@end example
@end deftypefn


@anchor{doc-substr}
@deftypefn {Function File} {} substr (@var{s}, @var{offset}, @var{len})
Return the substring of @var{s} which starts at character number
@var{offset} and is @var{len} characters long.

If @var{offset} is negative, extraction starts that far from the end of
the string.  If @var{len} is omitted, the substring extends to the end
of S.

For example,

@example
substr ("This is a test string", 6, 9)
@result{} "is a test"
@end example

This function is patterned after AWK.  You can get the same result by
@code{@var{s} (@var{offset} : (@var{offset} + @var{len} - 1))}.
@end deftypefn


@anchor{doc-regexp}
@deftypefn {Loadable Function} {[@var{s}, @var{e}, @var{te}, @var{m}, @var{t}, @var{nm}] =} regexp (@var{str}, @var{pat})
@deftypefnx {Loadable Function} {[@dots{}] =} regexp (@var{str}, @var{pat}, @var{opts}, @dots{})

Regular expression string matching. Matches @var{pat} in @var{str} and
returns the position and matching substrings or empty values if there are
none.

The matched pattern @var{pat} can include any of the standard regex
operators, including:

@table @code
@item .
Match any character
@item * + ? @{@}
Repetition operators, representing
@table @code
@item *
Match zero or more times
@item +
Match one or more times
@item ?
Match zero or one times
@item @{@}
Match range operator, which is of the form @code{@{@var{n}@}} to match exactly
@var{n} times, @code{@{@var{m},@}} to match @var{m} or more times,
@code{@{@var{m},@var{n}@}} to match between @var{m} and @var{n} times.
@end table
@item [@dots{}] [^@dots{}]
List operators, where for example @code{[ab]c} matches @code{ac} and @code{bc}
@item ()
Grouping operator
@item |
Alternation operator. Match one of a choice of regular expressions. The
alternatives must be delimited by the grouping operator @code{()} above
@item ^ $
Anchoring operator. @code{^} matches the start of the string @var{str} and
@code{$} the end
@end table

In addition the following escaped characters have special meaning. It should
be noted that it is recommended to quote @var{pat} in single quotes rather
than double quotes, to avoid the escape sequences being interpreted by octave
before being passed to @code{regexp}.

@table @code
@item \b
Match a word boundary
@item \B
Match within a word
@item \w
Matches any word character
@item \W
Matches any non word character
@item \<
Matches the beginning of a word
@item \>
Matches the end of a word
@item \s
Matches any whitespace character
@item \S
Matches any non whitespace character
@item \d
Matches any digit
@item \D
Matches any non-digit
@end table

The outputs of @code{regexp} by default are in the order as given below

@table @asis
@item @var{s}
The start indices of each of the matching substrings

@item @var{e}
The end indices of each matching substring

@item @var{te}
The extents of each of the matched token surrounded by @code{(@dots{})} in
@var{pat}.

@item @var{m}
A cell array of the text of each match.

@item @var{t}
A cell array of the text of each token matched.

@item @var{nm}
A structure containing the text of each matched named token, with the name
being used as the fieldname. A named token is denoted as
@code{(?<name>@dots{})}
@end table

Particular output arguments or the order of the output arguments can be
selected by additional @var{opts} arguments. These are strings and the
correspondence between the output arguments and the optional argument
are

@multitable @columnfractions 0.2 0.3 0.3 0.2
@item @tab 'start'        @tab @var{s}  @tab
@item @tab 'end'          @tab @var{e}  @tab
@item @tab 'tokenExtents' @tab @var{te} @tab
@item @tab 'match'        @tab @var{m}  @tab
@item @tab 'tokens'       @tab @var{t}  @tab
@item @tab 'names'        @tab @var{nm}  @tab
@end multitable

A further optional argument is 'once', that limits the number of returned
matches to the first match. Additional arguments are

@table @asis
@item matchcase
Make the matching case sensitive.
@item ignorecase
Make the matching case insensitive.
@item stringanchors
Match the anchor characters at the beginning and end of the string.
@item lineanchors
Match the anchor characters at the beginning and end of the line.
@item dotall
The character @code{.} matches the newline character.
@item dotexceptnewline
The character @code{.} matches all but the newline character.
@item freespacing
The pattern can include arbitrary whitespace and comments starting with
@code{#}.
@item literalspacing
The pattern is taken literally.
@end table
@end deftypefn


@anchor{doc-regexpi}
@deftypefn {Loadable Function} {[@var{s}, @var{e}, @var{te}, @var{m}, @var{t}, @var{nm}] =} regexpi (@var{str}, @var{pat})
@deftypefnx {Loadable Function} {[@dots{}] =} regexpi (@var{str}, @var{pat}, @var{opts}, @dots{})

Case insensitive regular expression string matching. Matches @var{pat} in
@var{str} and returns the position and matching substrings or empty values
if there are none. See @code{regexp} for more details
@end deftypefn


@anchor{doc-regexprep}
@deftypefn {Loadable Function}  {@var{string} =} regexprep (@var{string}, @var{pat}, @var{repstr}, @var{options})
Replace matches of @var{pat} in  @var{string} with @var{repstr}.


The replacement can contain @code{$i}, which substitutes
for the ith set of parentheses in the match string.  E.g.,
@example

   regexprep("Bill Dunn",'(\w+) (\w+)','$2, $1')

@end example
returns "Dunn, Bill"

@var{options} may be zero or more of
@table @samp

@item once
Replace only the first occurrence of @var{pat} in the result.

@item warnings
This option is present for compatibility but is ignored.

@item ignorecase or matchcase
Ignore case for the pattern matching (see @code{regexpi}).
Alternatively, use (?i) or (?-i) in the pattern.

@item lineanchors and stringanchors
Whether characters ^ and $ match the beginning and ending of lines.
Alternatively, use (?m) or (?-m) in the pattern.

@item dotexceptnewline and dotall
Whether . matches newlines in the string.
Alternatively, use (?s) or (?-s) in the pattern.

@item freespacing or literalspacing
Whether whitespace and # comments can be used to make the regular expression more readable.
Alternatively, use (?x) or (?-x) in the pattern.

@end table
@seealso{regexp,regexpi}
@end deftypefn


@node String Conversions
@section String Conversions

Octave supports various kinds of conversions between strings and
numbers. As an example, it is possible to convert a string containing
a hexadecimal number to a floating point number.

@example
hex2dec ("FF")
     @result{} ans = 255
@end example

@anchor{doc-bin2dec}
@deftypefn {Function File} {} bin2dec (@var{s})
Return the decimal number corresponding to the binary number stored
in the string @var{s}.  For example,

@example
bin2dec ("1110")
@result{} 14
@end example

If @var{s} is a string matrix, returns a column vector of converted
numbers, one per row of @var{s}.  Invalid rows evaluate to NaN.
@seealso{dec2hex, base2dec, dec2base, hex2dec, dec2bin}
@end deftypefn


@anchor{doc-dec2bin}
@deftypefn {Function File} {} dec2bin (@var{n}, @var{len})
Return a binary number corresponding the nonnegative decimal number
@var{n}, as a string of ones and zeros.  For example,

@example
dec2bin (14)
@result{} "1110"
@end example

If @var{n} is a vector, returns a string matrix, one row per value,
padded with leading zeros to the width of the largest value.

The optional second argument, @var{len}, specifies the minimum
number of digits in the result.
@seealso{bin2dec, dec2base, base2dec, hex2dec, dec2hex}
@end deftypefn


@anchor{doc-dec2hex}
@deftypefn {Function File} {} dec2hex (@var{n}, @var{len})
Return the hexadecimal string corresponding to the nonnegative 
integer @var{n}.  For example,

@example
dec2hex (2748)
@result{} "ABC"
@end example

If @var{n} is a vector, returns a string matrix, one row per value,
padded with leading zeros to the width of the largest value.

The optional second argument, @var{len}, specifies the minimum
number of digits in the result.
@seealso{hex2dec, dec2base, base2dec, bin2dec, dec2bin}
@end deftypefn


@anchor{doc-hex2dec}
@deftypefn {Function File} {} hex2dec (@var{s})
Return the integer corresponding to the hexadecimal number stored
in the string @var{s}.  For example,

@example
hex2dec ("12B")
@result{} 299
hex2dec ("12b")
@result{} 299
@end example

If @var{s} is a string matrix, returns a column vector of converted
numbers, one per row of @var{s}.  Invalid rows evaluate to NaN.
@seealso{dec2hex, base2dec, dec2base, bin2dec, dec2bin}
@end deftypefn


@anchor{doc-dec2base}
@deftypefn {Function File} {} dec2base (@var{n}, @var{b}, @var{len})
Return a string of symbols in base @var{b} corresponding to
the nonnegative integer @var{n}.

@example
dec2base (123, 3)
@result{} "11120"
@end example

If @var{n} is a vector, return a string matrix with one row per value,
padded with leading zeros to the width of the largest value.

If @var{b} is a string then the characters of @var{b} are used as
the symbols for the digits of @var{n}.  Space (' ') may not be used
as a symbol.

@example
dec2base (123, "aei")
@result{} "eeeia"
@end example

The optional third argument, @var{len}, specifies the minimum
number of digits in the result.
@seealso{base2dec, dec2bin, bin2dec, hex2dec, dec2hex}
@end deftypefn


@anchor{doc-base2dec}
@deftypefn {Function File} {} base2dec (@var{s}, @var{b})
Convert @var{s} from a string of digits of base @var{b} into an
integer.

@example
base2dec ("11120", 3)
@result{} 123
@end example

If @var{s} is a matrix, returns a column vector with one value per
row of @var{s}.  If a row contains invalid symbols then the
corresponding value will be NaN.  Rows are right-justified before
converting so that trailing spaces are ignored.

If @var{b} is a string, the characters of @var{b} are used as the
symbols for the digits of @var{s}. Space (' ') may not be used as a
symbol.

@example
base2dec ("yyyzx", "xyz")
@result{} 123
@end example
@seealso{dec2base, dec2bin, bin2dec, hex2dec, dec2hex}
@end deftypefn


@anchor{doc-str2double}
@deftypefn {Function File} {[@var{num}, @var{status}, @var{strarray}] =} str2double (@var{str}, @var{cdelim}, @var{rdelim}, @var{ddelim})
Convert strings into numeric values.

@code{str2double} can replace @code{str2num}, but avoids the use of
@code{eval} on unknown data.

@var{str} can be the form @samp{[+-]d[.]dd[[eE][+-]ddd]} in which
@samp{d} can be any of digit from 0 to 9, and @samp{[]} indicate
optional elements.

@var{num} is the corresponding numeric value.  If the conversion
fails, status is -1 and @var{num} is NaN.

@var{status} is 0 if the conversion was successful and -1 otherwise.

@var{strarray} is a cell array of strings.

Elements which are not defined or not valid return NaN and the
@var{status} becomes -1.

If @var{str} is a character array or a cell array of strings, then
@var{num} and @var{status} return matrices of appropriate size. 

@var{str} can also contain multiple elements separated by row and
column delimiters (@var{cdelim} and @var{rdelim}).

The parameters @var{cdelim}, @var{rdelim}, and @var{ddelim} are
optional column, row, and decimal delimiters.

The default row-delimiters are newline, carriage return and semicolon
(ASCII 10, 13 and 59).  The default column-delimiters are tab, space
and comma (ASCII 9, 32, and 44).  The default decimal delimiter is
@samp{.} (ASCII 46).

@var{cdelim}, @var{rdelim}, and @var{ddelim} must contain only nul,
newline, carriage return, semicolon, colon, slash, tab, space, comma,
or @samp{()[]@{@}} (ASCII 0, 9, 10, 11, 12, 13, 14, 32, 33, 34, 40,
41, 44, 47, 58, 59, 91, 93, 123, 124, 125).

Examples:

@example
str2double ("-.1e-5")
@result{} -1.0000e-006

str2double (".314e1, 44.44e-1, .7; -1e+1")
@result{}
   3.1400    4.4440    0.7000
 -10.0000       NaN       NaN

line = "200, 300, NaN, -inf, yes, no, 999, maybe, NaN";
[x, status] = str2double (line)
@result{} x =
    200   300   NaN  -Inf   NaN   NaN   999   NaN   NaN
@result{} status =
      0     0     0     0    -1    -1     0    -1     0
@end example
@end deftypefn


@anchor{doc-strjust}
@deftypefn {Function File} {} strjust (@var{s}, ["left"|"right"|"center"])
Shift the non-blank text of @var{s} to the left, right or center of
the string.  If @var{s} is a string array, justify each string in the
array.  Null characters are replaced by blanks.  If no justification
is specified, then all rows are right-justified.
@end deftypefn


@anchor{doc-str2num}
@deftypefn {Function File} {} str2num (@var{s})
Convert the string @var{s} to a number.
@end deftypefn


@anchor{doc-toascii}
@deftypefn {Mapping Function} {} toascii (@var{s})
Return ASCII representation of @var{s} in a matrix.  For example,

@example
@group
toascii ("ASCII")
     @result{} [ 65, 83, 67, 73, 73 ]
@end group

@end example
@end deftypefn


@anchor{doc-tolower}
@deftypefn {Mapping Function} {} tolower (@var{s})
Return a copy of the string @var{s}, with each upper-case character
replaced by the corresponding lower-case one; nonalphabetic characters
are left unchanged.  For example,

@example
tolower ("MiXeD cAsE 123")
     @result{} "mixed case 123"
@end example
@end deftypefn


@anchor{doc-toupper}
@deftypefn {Built-in Function} {} toupper (@var{s})
Return a copy of the string @var{s}, with each  lower-case character
replaced by the corresponding upper-case one; nonalphabetic characters
are left unchanged.  For example,

@example
@group
toupper ("MiXeD cAsE 123")
     @result{} "MIXED CASE 123"
@end group
@end example
@end deftypefn


@anchor{doc-do_string_escapes}
@deftypefn {Built-in Function} {} do_string_escapes (@var{string})
Convert special characters in @var{string} to their escaped forms.
@end deftypefn


@anchor{doc-undo_string_escapes}
@deftypefn {Built-in Function} {} undo_string_escapes (@var{s})
Converts special characters in strings back to their escaped forms.  For
example, the expression

@example
bell = "\a";
@end example

@noindent
assigns the value of the alert character (control-g, ASCII code 7) to
the string variable @code{bell}.  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,

@example
octave:13> undo_string_escapes (bell)
ans = \a
@end example

@noindent
replaces the unprintable alert character with its printable
representation.
@end deftypefn


@node Character Class Functions
@section Character Class Functions

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,

@example
@group
isalpha ("!Q@@WERT^Y&")
     @result{} [ 0, 1, 0, 1, 1, 1, 1, 0, 1, 0 ]
@end group
@end example

@anchor{doc-isalnum}
@deftypefn {Mapping Function} {} isalnum (@var{s})
Return 1 for characters that are letters or digits (@code{isalpha
(@var{s})} or @code{isdigit (@var{s})} is true).
@end deftypefn


@anchor{doc-isalpha}
@deftypefn {Mapping Function} {} isalpha (@var{s})
@deftypefnx {Mapping Function} {} isletter (@var{s})
Return true for characters that are letters (@code{isupper (@var{s})}
or @code{islower (@var{s})} is true).
@end deftypefn


@anchor{doc-isascii}
@deftypefn {Mapping Function} {} isascii (@var{s})
Return 1 for characters that are ASCII (in the range 0 to 127 decimal).
@end deftypefn


@anchor{doc-iscntrl}
@deftypefn {Mapping Function} {} iscntrl (@var{s})
Return 1 for control characters.
@end deftypefn


@anchor{doc-isdigit}
@deftypefn {Mapping Function} {} isdigit (@var{s})
Return 1 for characters that are decimal digits.
@end deftypefn


@anchor{doc-isgraph}
@deftypefn {Mapping Function} {} isgraph (@var{s})
Return 1 for printable characters (but not the space character).
@end deftypefn


@anchor{doc-isletter}
@deftypefn {Function File} {} isletter (@var{s})
Returns true if @var{s} is a letter false otherwise.
@seealso{isalpha}
@end deftypefn


@anchor{doc-islower}
@deftypefn {Mapping Function} {} islower (@var{s})
Return 1 for characters that are lower case letters.
@end deftypefn


@anchor{doc-isprint}
@deftypefn {Mapping Function} {} isprint (@var{s})
Return 1 for printable characters (including the space character).
@end deftypefn


@anchor{doc-ispunct}
@deftypefn {Mapping Function} {} ispunct (@var{s})
Return 1 for punctuation characters.
@end deftypefn


@anchor{doc-isspace}
@deftypefn {Mapping Function} {} isspace (@var{s})
Return 1 for whitespace characters (space, formfeed, newline,
carriage return, tab, and vertical tab).
@end deftypefn


@anchor{doc-isupper}
@deftypefn {Mapping Function} {} isupper (@var{s})
Return 1 for upper case letters.
@end deftypefn


@anchor{doc-isxdigit}
@deftypefn {Mapping Function} {} isxdigit (@var{s})
Return 1 for characters that are hexadecimal digits.
@end deftypefn

