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

@c Copyright (C) 1996, 1997, 1999, 2000, 2002, 2003, 2004, 2005,
@c               2006, 2007, 2008, 2009 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.

Strings can 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
* Escape Sequences in string constants::
* Character Arrays::
* Creating Strings:: 
* Comparing Strings::           
* Manipulating Strings::     
* String Conversions::          
* Character Class Functions::   
@end menu

@node Escape Sequences in string constants
@section Escape Sequences in string constants
@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

Here is a table of all the escape sequences used in Octave (within
double quoted strings).  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

In a single-quoted string there is only one escape sequence: you may insert a
single quote character using two single quote characters in succession.  For
example,

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


@node Character Arrays
@section Character Arrays

The string representation used by Octave is an array of characters, so
internally the string "dddddddddd" is actually a row vector of length 10
containing the value 100 in all places (100 is the ASCII code of "d").  This
lends itself to the obvious generalization 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.

The function @code{ischar} can be used to test if an object is a character
matrix.

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


To test if an object is a string (i.e., a character vector and not a character
matrix) you can use the @code{ischar} function in combination with the
@code{isvector} function as in the following example:

@example
@group
ischar(collection)
     @result{} ans = 1

ischar(collection) && isvector(collection)
     @result{} ans = 0

ischar("my string") && isvector("my string")
     @result{} ans = 1
@end group
@end example

One relevant question is, what happens when a 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.  It is possible to use a different character than the
blank character using the @code{string_fill_char} function.

@c pt-mat.cc
@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


This 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}.

@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).

@c ./strings/blanks.m
@anchor{doc-blanks}
@deftypefn {Function File} {} blanks (@var{n})
Return a string of @var{n} blanks, for example:

@example
@group
blanks(10);
whos ans;
     @result{}
      Attr Name        Size                     Bytes  Class
      ==== ====        ====                     =====  ===== 
           ans         1x10                        10  char
@end group
@end example
@seealso{@ref{doc-repmat,,repmat}}
@end deftypefn


@menu
* Concatenating Strings:: 
* Conversion of Numerical Data to Strings::
@end menu

@node Concatenating Strings
@subsection Concatenating Strings

It has been shown above that strings can be concatenated using matrix notation
(@pxref{Strings}, @ref{Character Arrays}).  Apart from that, there are several
functions to concatenate string objects: @code{char},
@code{strvcat}, @code{strcat} and @code{cstrcat}.  In addition, the general
purpose concatenation functions can be used: see @ref{doc-cat,,cat},
@ref{doc-horzcat,,horzcat} and @ref{doc-vertcat,,vertcat}.

@itemize @bullet
@item All string concatenation functions except @code{cstrcat}
convert numerical input into character data by taking the corresponding ASCII
character for each element, as in the following example:

@example
@group
char([98, 97, 110, 97, 110, 97])
     @result{} ans =
       banana
@end group
@end example

@item
@code{char} and @code{strvcat}
concatenate vertically, while @code{strcat} and @code{cstrcat} concatenate
horizontally.  For example:

@example
@group
char("an apple", "two pears")
     @result{} ans =
       an apple
       two pears
@end group

@group
strcat("oc", "tave", " is", " good", " for you")
     @result{} ans =
       octave is good for you
@end group
@end example

@item @code{char} generates an empty row in the output
for each empty string in the input.  @code{strvcat}, on the other hand,
eliminates empty strings.

@example
@group
char("orange", "green", "", "red")
     @result{} ans =
       orange
       green 
             
       red   
@end group

@group
strvcat("orange", "green", "", "red")
     @result{} ans =
       orange
       green 
       red  
@end group
@end example

@item All string concatenation functions except @code{cstrcat} also accept cell
array data (@pxref{Cell Arrays}).  @code{char} and
@code{strvcat} convert cell arrays into character arrays, while @code{strcat}
concatenates within the cells of the cell arrays:

@example
@group
char(@{"red", "green", "", "blue"@})
     @result{} ans =
       red  
       green

       blue 
@end group

@group
strcat(@{"abc"; "ghi"@}, @{"def"; "jkl"@})
     @result{} ans =
       @{
         [1,1] = abcdef
         [2,1] = ghijkl
       @}
@end group
@end example

@item @code{strcat} removes trailing white space in the arguments (except
within cell arrays), while @code{cstrcat} leaves white space untouched.  Both
kinds of behavior can be useful as can be seen in the examples:

@example
@group
strcat(["dir1";"directory2"], ["/";"/"], ["file1";"file2"])
     @result{} ans =
       dir1/file1      
       directory2/file2
@end group
@group

cstrcat(["thirteen apples"; "a banana"], [" 5$";" 1$"])
     @result{} ans =
       thirteen apples 5$
       a banana        1$
@end group
@end example

Note that in the above example for @code{cstrcat}, the white space originates
from the internal representation of the strings in a string array
(@pxref{Character Arrays}).
@end itemize

@c strfns.cc
@anchor{doc-char}
@deftypefn  {Built-in Function} {} char (@var{x})
@deftypefnx {Built-in Function} {} char (@var{x}, @dots{})
@deftypefnx {Built-in Function} {} char (@var{s1}, @var{s2}, @dots{})
@deftypefnx {Built-in Function} {} char (@var{cell_array})
Create a string array from one or more numeric matrices, character
matrices, or cell arrays.  Arguments are concatenated vertically.
The returned values are padded with blanks as needed to make each row
of the string array have the same length.  Empty input strings are
significant and will concatenated in the output.

For numerical input, each element is converted
to the corresponding ASCII character.  A range error results if an input
is outside the ASCII range (0-255).

For cell arrays, each element is concatenated separately.  Cell arrays converted through
@code{char} can mostly be converted back with @code{cellstr}.
For example,

@example
@group
char ([97, 98, 99], "", @{"98", "99", 100@}, "str1", ["ha", "lf"])
     @result{} ["abc    "
         "       "
         "98     "
         "99     "
         "d      "
         "str1   "
         "half   "]
@end group
@end example
@seealso{@ref{doc-strvcat,,strvcat}, @ref{doc-cellstr,,cellstr}}
@end deftypefn


@c strfns.cc
@anchor{doc-strvcat}
@deftypefn  {Built-in Function} {} strvcat (@var{x})
@deftypefnx {Built-in Function} {} strvcat (@var{x}, @dots{})
@deftypefnx {Built-in Function} {} strvcat (@var{s1}, @var{s2}, @dots{})
@deftypefnx {Built-in Function} {} strvcat (@var{cell_array})
Create a character array from one or more numeric matrices, character
matrices, or cell arrays.  Arguments are concatenated vertically.
The returned values are padded with blanks as needed to make each row
of the string array have the same length.  Unlike @code{char}, empty
strings are removed and will not appear in the output.

For numerical input, each element is converted
to the corresponding ASCII character.  A range error results if an input
is outside the ASCII range (0-255).

For cell arrays, each element is concatenated separately.  Cell arrays converted through
@code{strvcat} can mostly be converted back with @code{cellstr}.
For example,

@example
@group
strvcat ([97, 98, 99], "", @{"98", "99", 100@}, "str1", ["ha", "lf"])
     @result{} ["abc    "
         "98     "
         "99     "
         "d      "
         "str1   "
         "half   "]
@end group
@end example
@seealso{@ref{doc-char,,char}, @ref{doc-strcat,,strcat}, @ref{doc-cstrcat,,cstrcat}}
@end deftypefn


@c ./strings/strcat.m
@anchor{doc-strcat}
@deftypefn {Function File} {} strcat (@var{s1}, @var{s2}, @dots{})
Return a string containing all the arguments concatenated
horizontally.  If the arguments are cells strings,  @code{strcat}
returns a cell string with the individual cells concatenated.
For numerical input, each element is converted to the
corresponding ASCII character.  Trailing white space is eliminated.
For example,

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

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

@seealso{@ref{doc-cstrcat,,cstrcat}, @ref{doc-char,,char}, @ref{doc-strvcat,,strvcat}}
@end deftypefn


@c ./strings/cstrcat.m
@anchor{doc-cstrcat}
@deftypefn {Function File} {} cstrcat (@var{s1}, @var{s2}, @dots{})
Return a string containing all the arguments concatenated
horizontally.  Trailing white space is preserved.  For example,

@example
@group
cstrcat ("ab   ", "cd")
     @result{} "ab   cd"
@end group
@end example

@example
@group
s = [ "ab"; "cde" ];
cstrcat (s, s, s)
     @result{} ans =
        "ab ab ab "
        "cdecdecde"
@end group
@end example
@seealso{@ref{doc-strcat,,strcat}, @ref{doc-char,,char}, @ref{doc-strvcat,,strvcat}}
@end deftypefn


@node Conversion of Numerical Data to Strings 
@subsection Conversion of Numerical Data to Strings
Apart from the string concatenation functions (@pxref{Concatenating Strings})
which cast numerical data to the corresponding ASCII characters, there are
several functions that format numerical data as strings.  @code{mat2str} and
@code{num2str} convert real or complex matrices, while @code{int2str} converts
integer matrices.  @code{int2str} takes the real part of complex values and
round fractional values to integer.  A more flexible way to format numerical
data as strings is the @code{sprintf} function (@pxref{Formatted Output},
@ref{doc-sprintf}).

@c ./strings/mat2str.m
@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{@ref{doc-sprintf,,sprintf}, @ref{doc-num2str,,num2str}, @ref{doc-int2str,,int2str}}
@end deftypefn


@c ./general/num2str.m
@anchor{doc-num2str}
@deftypefn {Function File} {} num2str (@var{x})
@deftypefnx {Function File} {} num2str (@var{x}, @var{precision})
@deftypefnx {Function File} {} num2str (@var{x}, @var{format})
Convert a number (or array) to a string (or a character array).  The
optional second argument may either give the number of significant
digits (@var{precision}) to be used in the output or a format
template string (@var{format}) as in @code{sprintf} (@pxref{Formatted
Output}).  @code{num2str} can also handle complex numbers.  For
example: 

@example
@group
num2str (123.456)
     @result{} "123.46"

num2str (123.456, 4)
     @result{} "123.5"

s = num2str ([1, 1.34; 3, 3.56], "%5.1f")
     @result{} s =
        1.0  1.3
        3.0  3.6
whos s
     @result{}
      Attr Name        Size                     Bytes  Class
      ==== ====        ====                     =====  ===== 
           s           2x8                         16  char

num2str (1.234 + 27.3i)
     @result{} "1.234+27.3i"
@end group
@end example

The @code{num2str} function is not very flexible.  For better control
over the results, use @code{sprintf} (@pxref{Formatted Output}). 
Note that for complex @var{x}, the format string may only contain one
output conversion specification and nothing else.  Otherwise, you
will get unpredictable results.  
@seealso{@ref{doc-sprintf,,sprintf}, @ref{doc-int2str,,int2str}, @ref{doc-mat2str,,mat2str}}
@end deftypefn


@c ./general/int2str.m
@anchor{doc-int2str}
@deftypefn {Function File} {} int2str (@var{n})
Convert an integer (or array of integers) to a string (or a character
array).

@example
@group

int2str (123)
     @result{} "123"

s = int2str ([1, 2, 3; 4, 5, 6])
     @result{} s = 
        1  2  3
        4  5  6

whos s
     @result{} s = 
      Attr Name        Size                     Bytes  Class
      ==== ====        ====                     =====  ===== 
           s           2x7                         14  char
@end group
@end example

This function is not very flexible.  For better control over the
results, use @code{sprintf} (@pxref{Formatted Output}). 
@seealso{@ref{doc-sprintf,,sprintf}, @ref{doc-num2str,,num2str}, @ref{doc-mat2str,,mat2str}}
@end deftypefn


@node Comparing Strings
@section Comparing Strings

Since a string is a character array, comparisons between strings work
element by element as the following example shows:

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

@noindent To determine if two strings are identical it is necessary to use the
@code{strcmp} function.  It compares complete strings and is case
sensitive.  @code{strncmp} compares only the first @code{N} characters (with
@code{N} given as a parameter).  @code{strcmpi} and @code{strncmpi} are the
corresponding functions for case-insensitive comparison.

@c strfns.cc
@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{@ref{doc-strcmpi,,strcmpi}, @ref{doc-strncmp,,strncmp}, @ref{doc-strncmpi,,strncmpi}}
@end deftypefn


@c strfns.cc
@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{@ref{doc-strncmpi,,strncmpi}, @ref{doc-strcmp,,strcmp}, @ref{doc-strcmpi,,strcmpi}}
@end deftypefn


@c ./strings/strcmpi.m
@anchor{doc-strcmpi}
@deftypefn {Function File} {} strcmpi (@var{s1}, @var{s2})
Ignoring case, return 1 if the character strings (or character
arrays) @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{@ref{doc-strcmp,,strcmp}, @ref{doc-strncmp,,strncmp}, @ref{doc-strncmpi,,strncmpi}}
@end deftypefn


@c ./strings/strncmpi.m
@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 (or character arrays) @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{@ref{doc-strcmp,,strcmp}, @ref{doc-strcmpi,,strcmpi}, @ref{doc-strncmp,,strncmp}}
@end deftypefn


@c ./strings/validatestring.m
@anchor{doc-validatestring}
@deftypefn {Function File} {@var{validstr} =} validatestring (@var{str}, @var{strarray})
@deftypefnx {Function File} {@var{validstr} =} validatestring (@var{str}, @var{strarray}, @var{funcname})
@deftypefnx {Function File} {@var{validstr} =} validatestring (@var{str}, @var{strarray}, @var{funcname}, @var{varname})
@deftypefnx {Function File} {@var{validstr} =} validatestring (@dots{}, @var{position})
Verify that @var{str} is a string or substring of an element of
@var{strarray}.

@var{str} is a character string to be tested, and @var{strarray} is a
cellstr of valid values.  @var{validstr} will be the validated form
of @var{str} where validation is defined as @var{str} being a member
or substring of @var{validstr}.  If @var{str} is a substring of
@var{validstr} and there are multiple matches, the shortest match
will be returned if all matches are substrings of each other, and an
error will be raised if the matches are not substrings of each other.

All comparisons are case insensitive.
@seealso{@ref{doc-strcmp,,strcmp}, @ref{doc-strcmpi,,strcmpi}}
@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
@group
quote = ...
  "First things first, but not necessarily in that order";
quote( quote == " " ) = "_"
@result{} quote = 
    First_things_first,_but_not_necessarily_in_that_order
@end group
@end example

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

@c ./strings/deblank.m
@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


@c ./strings/strtrim.m
@anchor{doc-strtrim}
@deftypefn {Function File} {} strtrim (@var{s})
Remove leading and trailing blanks and nulls from @var{s}.  If
@var{s} is a matrix, @var{strtrim} 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.  For example:

@example
@group
strtrim ("    abc  ")
     @result{} "abc"

strtrim ([" abc   "; "   def   "])
     @result{} ["abc  "; "  def"]
@end group
@end example
@end deftypefn


@c ./strings/strtrunc.m
@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 is 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


@c ./strings/findstr.m
@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
@group
findstr ("ababab", "a")
     @result{} [1, 3, 5]
findstr ("abababa", "aba", 0)
     @result{} [1, 5]
@end group
@end example
@seealso{@ref{doc-strfind,,strfind}, @ref{doc-strmatch,,strmatch}, @ref{doc-strcmp,,strcmp}, @ref{doc-strncmp,,strncmp}, @ref{doc-strcmpi,,strcmpi}, @ref{doc-strncmpi,,strncmpi}, @ref{doc-find,,find}}
@end deftypefn


@c ./strings/strchr.m
@anchor{doc-strchr}
@deftypefn {Function File} {@var{idx} =} strchr (@var{str}, @var{chars})
@deftypefnx {Function File} {@var{idx} =} strchr (@var{str}, @var{chars}, @var{n})
@deftypefnx {Function File} {@var{idx} =} strchr (@var{str}, @var{chars}, @var{n}, @var{direction})
Search for the string @var{str} for occurrences of characters from the set @var{chars}.
The return value, as well as the @var{n} and @var{direction} arguments behave
identically as in @code{find}.

This will be faster than using regexp in most cases.

@seealso{@ref{doc-find,,find}}
@end deftypefn


@c ./strings/index.m
@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
@group
index ("Teststring", "t")
     @result{} 4
@end group
@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{@ref{doc-find,,find}, @ref{doc-rindex,,rindex}}
@end deftypefn


@c ./strings/rindex.m
@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
@group
rindex ("Teststring", "t")
     @result{} 6
@end group
@end example

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


@c ./strings/strfind.m
@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.  Examples:

@example
@group
strfind ("abababa", "aba")
     @result{} [1, 3, 5]

strfind (@{"abababa", "bebebe", "ab"@}, "aba")
     @result{} ans =
        @{
          [1,1] =

             1   3   5

          [1,2] = [](1x0)
          [1,3] = [](1x0)
        @}
@end group
@end example
@seealso{@ref{doc-findstr,,findstr}, @ref{doc-strmatch,,strmatch}, @ref{doc-strcmp,,strcmp}, @ref{doc-strncmp,,strncmp}, @ref{doc-strcmpi,,strcmpi}, @ref{doc-strncmpi,,strncmpi}, @ref{doc-find,,find}}
@end deftypefn


@c ./strings/strmatch.m
@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. 
For example:

@example
@group
strmatch ("apple", "apple juice")
     @result{} 1

strmatch ("apple", ["apple pie"; "apple juice"; "an apple"])
     @result{} [1; 2]

strmatch ("apple", @{"apple pie"; "apple juice"; "tomato"@})
     @result{} [1; 2]
@end group
@end example
@seealso{@ref{doc-strfind,,strfind}, @ref{doc-findstr,,findstr}, @ref{doc-strcmp,,strcmp}, @ref{doc-strncmp,,strncmp}, @ref{doc-strcmpi,,strcmpi}, @ref{doc-strncmpi,,strncmpi}, @ref{doc-find,,find}}
@end deftypefn


@c ./strings/strtok.m
@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 delimiter.  Leading
delimiters are ignored.  If @var{delim} is not specified, space is
assumed.  For example: 

@example
@group
strtok ("this is the life")
     @result{} "this"

[tok, rem] = strtok ("14*27+31", "+-*/")
     @result{}
        tok = 14
        rem = *27+31
@end group
@end example
@seealso{@ref{doc-index,,index}, @ref{doc-strsplit,,strsplit}}
@end deftypefn


@c ./strings/strsplit.m
@anchor{doc-strsplit}
@deftypefn {Function File} {[@var{s}] =} strsplit (@var{p}, @var{sep}, @var{strip_empty})
Split a single string using one or more delimiters and return a cell
array of strings.  Consecutive delimiters and delimiters at
boundaries result in empty strings, unless @var{strip_empty} is true.
The default value of @var{strip_empty} is false.
@seealso{@ref{doc-strtok,,strtok}}
@end deftypefn


@c ./strings/strrep.m
@anchor{doc-strrep}
@deftypefn {Function File} {} strrep (@var{s}, @var{x}, @var{y})
Replace all occurrences of the substring @var{x} of the string @var{s}
with the string @var{y} and return the result.  For example,

@example
@group
strrep ("This is a test string", "is", "&%$")
     @result{} "Th&%$ &%$ a test string"
@end group
@end example
@seealso{@ref{doc-regexprep,,regexprep}, @ref{doc-strfind,,strfind}, @ref{doc-findstr,,findstr}}
@end deftypefn


@c ./strings/substr.m
@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
@group
substr ("This is a test string", 6, 9)
     @result{} "is a test"
@end group
@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


@c ./DLD-FUNCTIONS/regexp.cc
@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
@seealso{@ref{doc-regexpi,,regexpi}, @ref{doc-regexprep,,regexprep}}
@end deftypefn


@c ./DLD-FUNCTIONS/regexp.cc
@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.  @xref{doc-regexp,,regexp}, for more details
@end deftypefn


@c ./DLD-FUNCTIONS/regexp.cc
@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
@group

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

@end group
@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{@ref{doc-regexp,,regexp}, @ref{doc-regexpi,,regexpi}, @ref{doc-strrep,,strrep}}
@end deftypefn


@c ./strings/regexptranslate.m
@anchor{doc-regexptranslate}
@deftypefn {Function File} {} regexptranslate (@var{op}, @var{s})
Translate a string for use in a regular expression.  This might
include either wildcard replacement or special character escaping.
The behavior can be controlled by the @var{op} that can have the
values

@table @asis
@item "wildcard"
The wildcard characters @code{.}, @code{*} and @code{?} are replaced
with wildcards that are appropriate for a regular expression. 
For example:
@example
@group
regexptranslate ("wildcard", "*.m")
     @result{} ".*\.m"
@end group
@end example

@item "escape"
The characters @code{$.?[]}, that have special meaning for regular
expressions are escaped so that they are treated literally.  For example:
@example
@group
regexptranslate ("escape", "12.5")
     @result{} "12\.5"
@end group
@end example
@end table
@seealso{@ref{doc-regexp,,regexp}, @ref{doc-regexpi,,regexpi}, @ref{doc-regexprep,,regexprep}}
@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
@group
hex2dec ("FF")
     @result{} ans = 255
@end group
@end example

@c ./strings/bin2dec.m
@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
@group
bin2dec ("1110")
     @result{} 14
@end group
@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{@ref{doc-dec2hex,,dec2hex}, @ref{doc-base2dec,,base2dec}, @ref{doc-dec2base,,dec2base}, @ref{doc-hex2dec,,hex2dec}, @ref{doc-dec2bin,,dec2bin}}
@end deftypefn


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

@example
@group
dec2bin (14)
     @result{} "1110"
@end group
@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{@ref{doc-bin2dec,,bin2dec}, @ref{doc-dec2base,,dec2base}, @ref{doc-base2dec,,base2dec}, @ref{doc-hex2dec,,hex2dec}, @ref{doc-dec2hex,,dec2hex}}
@end deftypefn


@c ./strings/dec2hex.m
@anchor{doc-dec2hex}
@deftypefn {Function File} {} dec2hex (@var{n}, @var{len})
Return the hexadecimal string corresponding to the non-negative 
integer @var{n}.  For example,

@example
@group
dec2hex (2748)
     @result{} "ABC"
@end group
@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{@ref{doc-hex2dec,,hex2dec}, @ref{doc-dec2base,,dec2base}, @ref{doc-base2dec,,base2dec}, @ref{doc-bin2dec,,bin2dec}, @ref{doc-dec2bin,,dec2bin}}
@end deftypefn


@c ./strings/hex2dec.m
@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
@group
hex2dec ("12B")
     @result{} 299
hex2dec ("12b")
     @result{} 299
@end group
@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{@ref{doc-dec2hex,,dec2hex}, @ref{doc-base2dec,,base2dec}, @ref{doc-dec2base,,dec2base}, @ref{doc-bin2dec,,bin2dec}, @ref{doc-dec2bin,,dec2bin}}
@end deftypefn


@c ./strings/dec2base.m
@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 non-negative integer @var{n}.

@example
@group
dec2base (123, 3)
     @result{} "11120"
@end group
@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
@group
dec2base (123, "aei")
     @result{} "eeeia"
@end group
@end example

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


@c ./strings/base2dec.m
@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
@group
base2dec ("11120", 3)
     @result{} 123
@end group
@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
@group
base2dec ("yyyzx", "xyz")
     @result{} 123
@end group
@end example
@seealso{@ref{doc-dec2base,,dec2base}, @ref{doc-dec2bin,,dec2bin}, @ref{doc-bin2dec,,bin2dec}, @ref{doc-hex2dec,,hex2dec}, @ref{doc-dec2hex,,dec2hex}}
@end deftypefn


@c ./DLD-FUNCTIONS/hex2num.cc
@anchor{doc-num2hex}
@deftypefn {Loadable Function} {@var{s} =} num2hex (@var{n})
Typecast a double precision number or vector to a 16 character hexadecimal
string of the IEEE 754 representation of the number.  For example

@example
@group
num2hex ([-1, 1, e, Inf, NaN, NA]);
@result{} "bff0000000000000
    3ff0000000000000
    4005bf0a8b145769
    7ff0000000000000
    fff8000000000000
    7ff00000000007a2"
@end group
@end example
@seealso{@ref{doc-hex2num,,hex2num}, @ref{doc-hex2dec,,hex2dec}, @ref{doc-dec2hex,,dec2hex}}
@end deftypefn


@c ./DLD-FUNCTIONS/hex2num.cc
@anchor{doc-hex2num}
@deftypefn {Loadable Function} {@var{n} =} hex2num (@var{s})
Typecast the 16 character hexadecimal character matrix to an IEEE 754
double precision number.  If fewer than 16 characters are given the
strings are right padded with '0' characters.

Given a string matrix, @code{hex2num} treats each row as a separate
number.

@example
@group
hex2num (["4005bf0a8b145769";"4024000000000000"])
@result{} [2.7183; 10.000]
@end group
@end example
@seealso{@ref{doc-num2hex,,num2hex}, @ref{doc-hex2dec,,hex2dec}, @ref{doc-dec2hex,,dec2hex}}
@end deftypefn


@c ./strings/str2double.m
@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
@group
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 group
@end example
@seealso{@ref{doc-str2num,,str2num}}
@end deftypefn


@c ./strings/strjust.m
@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.  For example:

@example
@group
strjust (["a"; "ab"; "abc"; "abcd"])
     @result{} ans =
           a
          ab
         abc
        abcd
@end group
@end example
@end deftypefn


@c ./strings/str2num.m
@anchor{doc-str2num}
@deftypefn {Function File} {} str2num (@var{s})
Convert the string (or character array) @var{s} to a number (or an
array).  Examples:  

@example
@group
str2num("3.141596")
     @result{} 3.141596

str2num(["1, 2, 3"; "4, 5, 6"]);
     @result{} ans =
        1  2  3
        4  5  6
@end group
@end example

@strong{Caution:} As @code{str2num} uses the @code{eval} function
to do the conversion, @code{str2num} will execute any code contained
in the string @var{s}.  Use @code{str2double} instead if you want to
avoid the use of @code{eval}. 
@seealso{@ref{doc-str2double,,str2double}, @ref{doc-eval,,eval}}
@end deftypefn


@c mappers.cc
@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
@seealso{@ref{doc-char,,char}}
@end deftypefn


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

@example
@group
tolower ("MiXeD cAsE 123")
     @result{} "mixed case 123"
@end group
@end example
@seealso{@ref{doc-toupper,,toupper}}
@end deftypefn


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

@example
@group
toupper ("MiXeD cAsE 123")
     @result{} "MIXED CASE 123"
@end group
@end example
@seealso{@ref{doc-tolower,,tolower}}
@end deftypefn


@c utils.cc
@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


@c utils.cc
@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
@group
octave:13> undo_string_escapes (bell)
ans = \a
@end group
@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

@c mappers.cc
@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


@c mappers.cc
@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


@c mappers.cc
@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


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


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


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


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


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


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


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


@c mappers.cc
@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


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


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


@c ./strings/isstrprop.m
@anchor{doc-isstrprop}
@deftypefn {Function File} {} isstrprop (@var{str}, @var{pred})
Test character string properties.  For example,

@example
@group
isstrprop ("abc123", "alpha")
@result{} [1, 1, 1, 0, 0, 0]
@end group
@end example

If @var{str} is a cell array, @code{isstrpop} is applied recursively
to each element of the cell array.

Numeric arrays are converted to character strings.

The second argument @var{pred} may be one of

@table @code
@item "alpha"
True for characters that are alphabetic

@item "alnum"
@itemx "alphanum"
True for characters that are alphabetic or digits.

@item "ascii"
True for characters that are in the range of ASCII encoding.

@item "cntrl"
True for control characters.

@item "digit"
True for decimal digits.

@item "graph"
@itemx "graphic"
True for printing characters except space.

@item "lower"
True for lower-case letters.

@item "print"
True for printing characters including space.

@item "punct"
True for printing characters except space or letter or digit.

@item "space"
@itemx "wspace"
True for whitespace characters (space, formfeed, newline, carriage
return, tab, vertical tab).

@item "upper"
True for upper-case letters.

@item "xdigit"
True for hexadecimal digits.
@end table

@seealso{@ref{doc-isalnum,,isalnum}, @ref{doc-isalpha,,isalpha}, @ref{doc-isascii,,isascii}, @ref{doc-iscntrl,,iscntrl}, @ref{doc-isdigit,,isdigit}, @ref{doc-isgraph,,isgraph}, @ref{doc-islower,,islower}, @ref{doc-isprint,,isprint}, @ref{doc-ispunct,,ispunct}, @ref{doc-isspace,,isspace}, @ref{doc-isupper,,isupper}, @ref{doc-isxdigit,,isxdigit}}
@end deftypefn