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

@c Copyright (C) 1996-2013 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 null 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.

@item \@var{nnn}
Represents the octal value @var{nnn}, where @var{nnn} are one to three
digits between 0 and 7.  For example, the code for the ASCII ESC
(escape) character is @samp{\033}.

@item \x@var{hh}@dots{}
Represents the hexadecimal value @var{hh}, where @var{hh} are hexadecimal
digits (@samp{0} through @samp{9} and either @samp{A} through @samp{F} or
@samp{a} through @samp{f}).  Like the same construct in @sc{ansi} C,
the escape sequence continues until the first non-hexadecimal digit is seen.
However, using more than two hexadecimal digits produces undefined results.
@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

In scripts the two different string types can be distinguished if necessary
by using @code{is_dq_string} and @code{is_sq_string}.

@c is_dq_string libinterp/octave-value/ov.cc
@anchor{XREFis_dq_string}
@deftypefn {Built-in Function} {} is_dq_string (@var{x})
Return true if @var{x} is a double-quoted character string.
@seealso{@ref{XREFis_sq_string,,is_sq_string}, @ref{XREFischar,,ischar}}
@end deftypefn


@c is_sq_string libinterp/octave-value/ov.cc
@anchor{XREFis_sq_string}
@deftypefn {Built-in Function} {} is_sq_string (@var{x})
Return true if @var{x} is a single-quoted character string.
@seealso{@ref{XREFis_dq_string,,is_dq_string}, @ref{XREFischar,,ischar}}
@end deftypefn


@node Character Arrays
@section Character Arrays

The string representation used by Octave is an array of characters, so
internally the string @nospell{@qcode{"dddddddddd"}} is actually a row vector
of length 10 containing the value 100 in all places (100 is the ASCII code of
@qcode{"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 ischar libinterp/corefcn/strfns.cc
@anchor{XREFischar}
@deftypefn {Built-in Function} {} ischar (@var{x})
Return true if @var{x} is a character array.
@seealso{@ref{XREFisfloat,,isfloat}, @ref{XREFisinteger,,isinteger}, @ref{XREFislogical,,islogical}, @ref{XREFisnumeric,,isnumeric}, @ref{XREFiscellstr,,iscellstr}, @ref{XREFisa,,isa}}
@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{} 1

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

ischar ("my string") && isvector ("my string")
     @result{} 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 string_fill_char libinterp/parse-tree/pt-mat.cc
@anchor{XREFstring_fill_char}
@deftypefn  {Built-in Function} {@var{val} =} string_fill_char ()
@deftypefnx {Built-in Function} {@var{old_val} =} string_fill_char (@var{new_val})
@deftypefnx {Built-in Function} {} string_fill_char (@var{new_val}, "local")
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 @qcode{" "} (a single space).  For example:

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

When called from inside a function with the @qcode{"local"} option, the
variable is changed locally for the function and any subroutines it calls.  
The original variable value is restored when exiting the function.
@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 blanks scripts/strings/blanks.m
@anchor{XREFblanks}
@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{XREFrepmat,,repmat}}
@end deftypefn


@menu
* Concatenating Strings::
* Converting Numerical Data to Strings::
@end menu

@node Concatenating Strings
@subsection Concatenating Strings

Strings can be concatenated using matrix notation
(@pxref{Strings}, @ref{Character Arrays}) which is often the most natural
method.  For example:

@example
@group
fullname = [fname ".txt"];
email = ["<" user "@@" domain ">"];
@end group
@end example

@noindent
In each case it is easy to see what the final string will look like.  This
method is also the most efficient.  When using matrix concatenation the parser
immediately begins joining the strings without having to process
the overhead of a function call and the input validation of the associated
function.

Nevertheless, there are several other functions for concatenating string
objects which can be useful in specific circumstances: @code{char},
@code{strvcat}, @code{strcat}, and @code{cstrcat}.  Finally, the general
purpose concatenation functions can be used: see @ref{XREFcat,,cat},
@ref{XREFhorzcat,,horzcat}, and @ref{XREFvertcat,,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{} 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{} an apple
       two pears
@end group

@group
strcat ("oc", "tave", " is", " good", " for you")
     @result{} 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{} orange
       green 

       red
@end group

@group
strvcat ("orange", "green", "", "red")
    @result{} 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{} red  
        green

        blue 
@end group

@group
strcat (@{"abc"; "ghi"@}, @{"def"; "jkl"@})
     @result{}
        @{
          [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{} dir1/file1
        directory2/file2
@end group
@group

cstrcat (["thirteen apples"; "a banana"], [" 5$";" 1$"])
      @result{} 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 char libinterp/corefcn/strfns.cc
@anchor{XREFchar}
@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{XREFstrvcat,,strvcat}, @ref{XREFcellstr,,cellstr}}
@end deftypefn


@c strvcat libinterp/corefcn/strfns.cc
@anchor{XREFstrvcat}
@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{XREFchar,,char}, @ref{XREFstrcat,,strcat}, @ref{XREFcstrcat,,cstrcat}}
@end deftypefn


@c strcat scripts/strings/strcat.m
@anchor{XREFstrcat}
@deftypefn {Function File} {} strcat (@var{s1}, @var{s2}, @dots{})
Return a string containing all the arguments concatenated
horizontally.  If the arguments are cell 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 for any
character string input is eliminated before the strings are
concatenated.  Note that cell string values do @strong{not} have
whitespace trimmed.

For example:

@example
@group
strcat ("|", " leading space is preserved", "|")
    @result{} | leading space is preserved|
@end group
@end example

@example
@group
strcat ("|", "trailing space is eliminated ", "|")
    @result{} |trailing space is eliminated|
@end group
@end example

@example
@group
strcat ("homogeneous space |", "  ", "| is also eliminated")
    @result{} homogeneous space || is also eliminated
@end group
@end example

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

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

@seealso{@ref{XREFcstrcat,,cstrcat}, @ref{XREFchar,,char}, @ref{XREFstrvcat,,strvcat}}
@end deftypefn


@c cstrcat scripts/strings/cstrcat.m
@anchor{XREFcstrcat}
@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{} "ab ab ab "
         "cdecdecde"
@end group
@end example
@seealso{@ref{XREFstrcat,,strcat}, @ref{XREFchar,,char}, @ref{XREFstrvcat,,strvcat}}
@end deftypefn


@node Converting Numerical Data to Strings
@subsection Converting 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{XREFsprintf,,sprintf}).

@c mat2str scripts/strings/mat2str.m
@anchor{XREFmat2str}
@deftypefn  {Function File} {@var{s} =} mat2str (@var{x}, @var{n})
@deftypefnx {Function File} {@var{s} =} mat2str (@var{x}, @var{n}, "class")
Format real, complex, and logical matrices as strings.  The 
returned string may be used to reconstruct the original matrix by using
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 15.

If the argument @qcode{"class"} is given then the class of @var{x} is
included in the string in such a way that @code{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])"

mat2str (logical (eye (2)))
     @result{} "[true false;false true]"

isequal (x, eval (mat2str (x)))
     @result{} 1
@end group
@end example

@seealso{@ref{XREFsprintf,,sprintf}, @ref{XREFnum2str,,num2str}, @ref{XREFint2str,,int2str}}
@end deftypefn


@c num2str scripts/general/num2str.m
@anchor{XREFnum2str}
@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.

Examples:

@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

Notes:

For @sc{matlab} compatibility, leading spaces are stripped before returning
the string.

The @code{num2str} function is not very flexible.  For better control
over the results, use @code{sprintf} (@pxref{Formatted Output}).

For complex @var{x}, the format string may only contain one
output conversion specification and nothing else.  Otherwise, results
will be unpredictable.
@seealso{@ref{XREFsprintf,,sprintf}, @ref{XREFint2str,,int2str}, @ref{XREFmat2str,,mat2str}}
@end deftypefn


@c int2str scripts/general/int2str.m
@anchor{XREFint2str}
@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{}
      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{XREFsprintf,,sprintf}, @ref{XREFnum2str,,num2str}, @ref{XREFmat2str,,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 strcmp libinterp/corefcn/strfns.cc
@anchor{XREFstrcmp}
@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{XREFstrcmpi,,strcmpi}, @ref{XREFstrncmp,,strncmp}, @ref{XREFstrncmpi,,strncmpi}}
@end deftypefn


@c strncmp libinterp/corefcn/strfns.cc
@anchor{XREFstrncmp}
@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{XREFstrncmpi,,strncmpi}, @ref{XREFstrcmp,,strcmp}, @ref{XREFstrcmpi,,strcmpi}}
@end deftypefn


@c strcmpi libinterp/corefcn/strfns.cc
@anchor{XREFstrcmpi}
@deftypefn {Built-in Function} {} strcmpi (@var{s1}, @var{s2})
Return 1 if the character strings @var{s1} and @var{s2} are the same,
disregarding case of alphabetic characters, 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.

@strong{Caution:} National alphabets are not supported.
@seealso{@ref{XREFstrcmp,,strcmp}, @ref{XREFstrncmp,,strncmp}, @ref{XREFstrncmpi,,strncmpi}}
@end deftypefn


@c strncmpi libinterp/corefcn/strfns.cc
@anchor{XREFstrncmpi}
@deftypefn {Built-in Function} {} strncmpi (@var{s1}, @var{s2}, @var{n})
Return 1 if the first @var{n} character of @var{s1} and @var{s2} are the
same, disregarding case of alphabetic characters, 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.

@strong{Caution:} National alphabets are not supported.
@seealso{@ref{XREFstrncmp,,strncmp}, @ref{XREFstrcmp,,strcmp}, @ref{XREFstrcmpi,,strcmpi}}
@end deftypefn


@c validatestring scripts/strings/validatestring.m
@anchor{XREFvalidatestring}
@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 an element, or substring of an element, in
@var{strarray}.

When @var{str} is a character string to be tested, and @var{strarray} is a
cellstr of valid values, then @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}.  This is useful for both verifying
and expanding short options, such as @qcode{"r"}, to their longer forms,
such as @qcode{"red"}.  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.  Otherwise, an error will be raised
because the expansion of @var{str} is ambiguous.  All comparisons are case
insensitive.

The additional inputs @var{funcname}, @var{varname}, and @var{position}
are optional and will make any generated validation error message more
specific.

Examples:
@c Set example in small font to prevent overfull line

@smallexample
@group
validatestring ("r", @{"red", "green", "blue"@})
@result{} "red"

validatestring ("b", @{"red", "green", "blue", "black"@})
@result{} error: validatestring: multiple unique matches were found for 'b':
   blue, black
@end group
@end smallexample

@seealso{@ref{XREFstrcmp,,strcmp}, @ref{XREFstrcmpi,,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 deblank scripts/strings/deblank.m
@anchor{XREFdeblank}
@deftypefn {Function File} {} deblank (@var{s})
Remove trailing whitespace 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 of strings, operate recursively on each
string element.

Examples:

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

deblank ([" abc   "; "   def   "])
     @result{}  [" abc  " ; "   def"]
@end group
@end example
@seealso{@ref{XREFstrtrim,,strtrim}}
@end deftypefn


@c strtrim scripts/strings/strtrim.m
@anchor{XREFstrtrim}
@deftypefn {Function File} {} strtrim (@var{s})
Remove leading and trailing whitespace 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 of strings, operate recursively
on each string element.  For example:

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

strtrim ([" abc   "; "   def   "])
     @result{}  ["abc  "  ; "  def"]
@end group
@end example
@seealso{@ref{XREFdeblank,,deblank}}
@end deftypefn


@c strtrunc scripts/strings/strtrunc.m
@anchor{XREFstrtrunc}
@deftypefn {Function File} {} strtrunc (@var{s}, @var{n})
Truncate the character string @var{s} to length @var{n}.  If @var{s}
is a character matrix, then the number of columns is adjusted.
If @var{s} is a cell array of strings, then the operation is performed
on each cell element and the new cell array is returned.
@end deftypefn


@c findstr scripts/strings/findstr.m
@anchor{XREFfindstr}
@deftypefn  {Function File} {} findstr (@var{s}, @var{t})
@deftypefnx {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 true, 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

@strong{Caution:} @code{findstr} is scheduled for deprecation.  Use
@code{strfind} in all new code.
@seealso{@ref{XREFstrfind,,strfind}, @ref{XREFstrmatch,,strmatch}, @ref{XREFstrcmp,,strcmp}, @ref{XREFstrncmp,,strncmp}, @ref{XREFstrcmpi,,strcmpi}, @ref{XREFstrncmpi,,strncmpi}, @ref{XREFfind,,find}}
@end deftypefn


@c strchr scripts/strings/strchr.m
@anchor{XREFstrchr}
@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})
@deftypefnx {Function File} {[@var{i}, @var{j}] =} strchr (@dots{})
Search for the string @var{str} for occurrences of characters from
the set @var{chars}.  The return value(s), 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{XREFfind,,find}}
@end deftypefn


@c index scripts/strings/index.m
@anchor{XREFindex}
@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.  @var{s} may also be a
string array or cell array of strings.

For example:

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

If @var{direction} is @qcode{"first"}, return the first element found.
If @var{direction} is @qcode{"last"}, return the last element found.

@seealso{@ref{XREFfind,,find}, @ref{XREFrindex,,rindex}}
@end deftypefn


@c rindex scripts/strings/rindex.m
@anchor{XREFrindex}
@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.  @var{s} may also be a string array or cell array of strings.

For example:

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

The @code{rindex} function is equivalent to @code{index} with
@var{direction} set to @qcode{"last"}.

@seealso{@ref{XREFfind,,find}, @ref{XREFindex,,index}}
@end deftypefn


@c strfind libinterp/corefcn/strfind.cc
@anchor{XREFstrfind}
@deftypefn  {Built-in Function} {@var{idx} =} strfind (@var{str}, @var{pattern})
@deftypefnx {Built-in Function} {@var{idx} =} strfind (@var{cellstr}, @var{pattern})
@deftypefnx {Built-in Function} {@var{idx} =} strfind (@dots{}, "overlaps", @var{val})
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{[]}.
The optional argument @qcode{"overlaps"} determines whether the pattern
can match at every position in @var{str} (true), or only for unique
occurrences of the complete pattern (false).  The default is true.

If a cell array of strings @var{cellstr} is specified
then @var{idx} is a cell array of vectors, as specified above.

Examples:

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

strfind ("abababa", "aba", "overlaps", false)
     @result{} [1, 5]

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

             1   3   5

          [1,2] = [](1x0)
          [1,3] = [](1x0)
        @}
@end group
@end example
@seealso{@ref{XREFfindstr,,findstr}, @ref{XREFstrmatch,,strmatch}, @ref{XREFregexp,,regexp}, @ref{XREFregexpi,,regexpi}, @ref{XREFfind,,find}}
@end deftypefn


@c strjoin scripts/strings/strjoin.m
@anchor{XREFstrjoin}
@deftypefn  {Function File} {@var{str} =} strjoin (@var{cstr})
@deftypefnx {Function File} {@var{str} =} strjoin (@var{cstr}, @var{delimiter})
Join the elements of the cell string array, @var{cstr}, into a single
string.

If no @var{delimiter} is specified, the elements of @var{cstr}
separated by a space.

If @var{delimiter} is specified as a string, the cell string array is
joined using the string.  Escape sequences are supported.

If @var{delimiter} is a cell string array whose length is one less
than @var{cstr}, then the elements of @var{cstr} are joined by
interleaving the cell string elements of @var{delimiter}.  Escape
sequences are not supported.

@example
@group
strjoin (@{'Octave','Scilab','Lush','Yorick'@}, '*')
      @result{} 'Octave*Scilab*Lush*Yorick'
@end group
@end example
@seealso {strsplit}
@end deftypefn


@c strmatch scripts/strings/strmatch.m
@anchor{XREFstrmatch}
@deftypefn  {Function File} {} strmatch (@var{s}, @var{A})
@deftypefnx {Function File} {} strmatch (@var{s}, @var{A}, "exact")
Return indices of entries of @var{A} which begin with the string @var{s}.
The second argument @var{A} must be a string, character matrix, or a cell
array of strings.  If the third argument @qcode{"exact"} is not given, then
@var{s} only needs to match @var{A} up to the length of @var{s}.
Trailing spaces and nulls in @var{s} and @var{A} are ignored when matching.

For example:

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

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

strmatch ("apple", ["apple  "; "apple juice"; "an apple"], "exact")
     @result{} [1]
@end group
@end example

@strong{Caution:} @code{strmatch} is scheduled for deprecation.  Use
@code{strncmp} (normal case), or @code{strcmp} (@qcode{"exact"} case), or
@code{regexp} in all new code.
@seealso{@ref{XREFstrfind,,strfind}, @ref{XREFfindstr,,findstr}, @ref{XREFstrcmp,,strcmp}, @ref{XREFstrncmp,,strncmp}, @ref{XREFstrcmpi,,strcmpi}, @ref{XREFstrncmpi,,strncmpi}, @ref{XREFfind,,find}}
@end deftypefn


@c strtok scripts/strings/strtok.m
@anchor{XREFstrtok}
@deftypefn  {Function File} {[@var{tok}, @var{rem}] =} strtok (@var{str})
@deftypefnx {Function File} {[@var{tok}, @var{rem}] =} strtok (@var{str}, @var{delim})

Find all characters in the string @var{str} up to, but not including, the 
first character which is in the string @var{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, whitespace is assumed.  @var{str} may also be a cell array of
strings in which case the function executes on every individual string
and returns a cell array of tokens and remainders.

Examples:

@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{XREFindex,,index}, @ref{XREFstrsplit,,strsplit}, @ref{XREFstrchr,,strchr}, @ref{XREFisspace,,isspace}}
@end deftypefn


@c strsplit scripts/strings/strsplit.m
@anchor{XREFstrsplit}
@deftypefn  {Function File} {[@var{cstr}] =} strsplit (@var{s})
@deftypefnx {Function File} {[@var{cstr}] =} strsplit (@var{s}, @var{del})
@deftypefnx {Function File} {[@var{cstr}] =} strsplit (@dots{}, @var{name}, @var{value})
@deftypefnx {Function File} {[@var{cstr}, @var{matches}] =} strsplit (@dots{})
Split the string @var{s} using the delimiters specified by @var{del}
and return a cell string array of substrings.  If a delimiter is not
specified the string, @var{s}, is split at whitespace.  The delimiter,
@var{del} may be a string, a scalar cell string, or cell string array.
By default, consecutive delimiters in the input string @var{s} are
collapsed into one.

The second output, @var{matches}, returns the delimiters which were matched
in the original string.

Example:

@example
strsplit ("a b c")
      @result{}
          @{
            [1,1] = a
            [1,2] = b
            [1,3] = c
          @}

strsplit ("a,b,c", ",")
      @result{}
          @{
            [1,1] = a
            [1,2] = b
            [1,3] = c
          @}

strsplit ("a foo b,bar c", @{"\s", "foo", "bar"@})
      @result{}
          @{
            [1,1] = a
            [1,2] = b
            [1,3] = c
          @}

strsplit ("a,,b, c", @{",", " "@}, false)
      @result{}
          @{
            [1,1] = a
            [1,2] = 
            [1,3] = b
            [1,4] = 
            [1,5] = c
          @}

@end example

Supported @var{name}/@var{value} pair arguments are;

@itemize
@item @var{collapsedelimiters} may take the value of @var{true} or
@var{false} with the default being @var{false}.

@item @var{delimitertype} may take the value of @code{simple} or
@code{regularexpression}.  The default is @var{delimitertype} is
@code{simple}.
@end itemize

Example:

@example
strsplit ("a foo b,bar c", ",|\\s|foo|bar", "delimitertype", "regularexpression")
      @result{}
          @{
            [1,1] = a
            [1,2] = b
            [1,3] = c
          @}

strsplit ("a,,b, c", "[, ]", false, "delimitertype", "regularexpression")
      @result{}
          @{
            [1,1] = a
            [1,2] = 
            [1,3] = b
            [1,4] = 
            [1,5] = c
          @}

strsplit ("a,\t,b, c", @{',', '\s'@}, "delimitertype", "regularexpression")
      @result{}
          @{
            [1,1] = a
            [1,2] = b
            [1,3] = c
          @}

strsplit ("a,\t,b, c", @{',', ' ', '\t'@}, "collapsedelimiters", false)
      @result{}
          @{
            [1,1] = a
            [1,2] = 
            [1,3] = 
            [1,4] = b
            [1,5] = 
            [1,6] = c
          @}
@end example

@seealso{@ref{XREFostrsplit,,ostrsplit}, @ref{XREFstrjoin,,strjoin}, @ref{XREFstrtok,,strtok}, @ref{XREFregexp,,regexp}}
@end deftypefn


@c ostrsplit scripts/strings/ostrsplit.m
@anchor{XREFostrsplit}
@deftypefn  {Function File} {[@var{cstr}] =} ostrsplit (@var{s}, @var{sep})
@deftypefnx {Function File} {[@var{cstr}] =} ostrsplit (@var{s}, @var{sep}, @var{strip_empty})
Split the string @var{s} using one or more separators @var{sep} and return
a cell array of strings.  Consecutive separators and separators at
boundaries result in empty strings, unless @var{strip_empty} is true.
The default value of @var{strip_empty} is false.

2-D character arrays are split at separators and at the original column
boundaries.

Example:

@example
@group
ostrsplit ("a,b,c", ",")
      @result{}
          @{
            [1,1] = a
            [1,2] = b
            [1,3] = c
          @}

ostrsplit (["a,b" ; "cde"], ",")
      @result{}
          @{
            [1,1] = a
            [1,2] = b
            [1,3] = cde
          @}
@end group
@end example
@seealso{@ref{XREFstrsplit,,strsplit}, @ref{XREFstrtok,,strtok}}
@end deftypefn


@c strread scripts/io/strread.m
@anchor{XREFstrread}
@deftypefn  {Function File} {[@var{a}, @dots{}] =} strread (@var{str})
@deftypefnx {Function File} {[@var{a}, @dots{}] =} strread (@var{str}, @var{format})
@deftypefnx {Function File} {[@var{a}, @dots{}] =} strread (@var{str}, @var{format}, @var{format_repeat})
@deftypefnx {Function File} {[@var{a}, @dots{}] =} strread (@var{str}, @var{format}, @var{prop1}, @var{value1}, @dots{})
@deftypefnx {Function File} {[@var{a}, @dots{}] =} strread (@var{str}, @var{format}, @var{format_repeat}, @var{prop1}, @var{value1}, @dots{})
Read data from a string.

The string @var{str} is split into words that are repeatedly matched to the
specifiers in @var{format}.  The first word is matched to the first
specifier, the second to the second specifier and so forth.  If there are
more words than specifiers, the process is repeated until all words have
been processed.

The string @var{format} describes how the words in @var{str} should be
parsed.
It may contain any combination of the following specifiers:

@table @code
@item %s
The word is parsed as a string.

@item  %f
@itemx %n
The word is parsed as a number and converted to double.

@item  %d
@itemx %u
The word is parsed as a number and converted to int32.

@item %*', '%*f', '%*s
The word is skipped.

For %s and %d, %f, %n, %u and the associated %*s @dots{} specifiers an
optional width can be specified as %Ns, etc. where N is an integer > 1.
For %f, format specifiers like %N.Mf are allowed.

@item literals
In addition the format may contain literal character strings; these will be
skipped during reading.
@end table

Parsed word corresponding to the first specifier are returned in the first
output argument and likewise for the rest of the specifiers.

By default, @var{format} is @t{"%f"}, meaning that numbers are read from
@var{str}.  This will do if @var{str} contains only numeric fields.

For example, the string

@example
@group
@var{str} = "\
Bunny Bugs   5.5\n\
Duck Daffy  -7.5e-5\n\
Penguin Tux   6"
@end group
@end example

@noindent
can be read using

@example
[@var{a}, @var{b}, @var{c}] = strread (@var{str}, "%s %s %f");
@end example

Optional numeric argument @var{format_repeat} can be used for
limiting the number of items read:

@table @asis
@item -1
(default) read all of the string until the end.

@item N
Read N times @var{nargout} items.  0 (zero) is an acceptable
value for @var{format_repeat}.
@end table

The behavior of @code{strread} can be changed via property-value
pairs.  The following properties are recognized:

@table @asis
@item @qcode{"commentstyle"}
Parts of @var{str} are considered comments and will be skipped.
@var{value} is the comment style and can be any of the following.

@itemize
@item @qcode{"shell"}
Everything from @code{#} characters to the nearest end-of-line is skipped.

@item @qcode{"c"}
Everything between @code{/*} and @code{*/} is skipped.

@item @qcode{"c++"}
Everything from @code{//} characters to the nearest end-of-line is skipped.

@item @qcode{"matlab"}
Everything from @code{%} characters to the nearest end-of-line is skipped.

@item user-supplied.  Two options:
(1) One string, or 1x1 cell string: Skip everything to the right of it;
(2) 2x1 cell string array: Everything between the left and right strings
is skipped.
@end itemize

@item @qcode{"delimiter"}
Any character in @var{value} will be used to split @var{str} into words
(default value = any whitespace).

@item @qcode{"emptyvalue"}:
Value to return for empty numeric values in non-whitespace delimited data.
The default is NaN@.  When the data type does not support NaN
(int32 for example), then default is zero.

@item @qcode{"multipledelimsasone"}
Treat a series of consecutive delimiters, without whitespace in between,
as a single delimiter.  Consecutive delimiter series need not be vertically
@qcode{"aligned"}.

@item @qcode{"treatasempty"}
Treat single occurrences (surrounded by delimiters or whitespace) of the
string(s) in @var{value} as missing values.

@item @qcode{"returnonerror"}
If @var{value} true (1, default), ignore read errors and return normally.
If false (0), return an error.

@item @qcode{"whitespace"}
Any character in @var{value} will be interpreted as whitespace and
trimmed; the string defining whitespace must be enclosed in double
quotes for proper processing of special characters like \t.
The default value for whitespace = @qcode{" \b\r\n\t"} (note the space).
Unless whitespace is set to '' (empty) AND at least one @qcode{"%s"} format
conversion specifier is supplied, a space is always part of whitespace.

@end table

When the number of words in @var{str} doesn't match an exact multiple
of the number of format conversion specifiers, strread's behavior
depends on the last character of @var{str}:

@table @asis
@item last character = @qcode{"\n"}
Data columns are padded with empty fields or Nan so that all columns
have equal length 

@item last character is not @qcode{"\n"}
Data columns are not padded; strread returns columns of unequal length

@end table

@seealso{@ref{XREFtextscan,,textscan}, @ref{XREFtextread,,textread}, @ref{XREFload,,load}, @ref{XREFdlmread,,dlmread}, @ref{XREFfscanf,,fscanf}}
@end deftypefn


@c strrep libinterp/corefcn/strfind.cc
@anchor{XREFstrrep}
@deftypefn  {Built-in Function} {@var{newstr} =} strrep (@var{str}, @var{ptn}, @var{rep})
@deftypefnx {Built-in Function} {@var{newstr} =} strrep (@var{cellstr}, @var{ptn}, @var{rep})
@deftypefnx {Built-in Function} {@var{newstr} =} strrep (@dots{}, "overlaps", @var{val})
Replace all occurrences of the pattern @var{ptn} in the string @var{str}
with the string @var{rep} and return the result.

The optional argument @qcode{"overlaps"} determines whether the pattern
can match at every position in @var{str} (true), or only for unique
occurrences of the complete pattern (false).  The default is true.

@var{s} may also be a cell array of strings, in which case the replacement is
done for each element and a cell array is returned.

Example:

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

@seealso{@ref{XREFregexprep,,regexprep}, @ref{XREFstrfind,,strfind}, @ref{XREFfindstr,,findstr}}
@end deftypefn


@c substr scripts/strings/substr.m
@anchor{XREFsubstr}
@deftypefn  {Function File} {} substr (@var{s}, @var{offset})
@deftypefnx {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.

Position numbering for offsets begins with 1.  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 @var{S}.  A
negative value for @var{len} extracts to within @var{len} characters of
the end of the string

Examples:

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

This function is patterned after the equivalent function in Perl.
@end deftypefn


@c regexp libinterp/corefcn/regexp.cc
@anchor{XREFregexp}
@deftypefn  {Built-in Function} {[@var{s}, @var{e}, @var{te}, @var{m}, @var{t}, @var{nm}, @var{sp}] =} regexp (@var{str}, @var{pat})
@deftypefnx {Built-in Function} {[@dots{}] =} regexp (@var{str}, @var{pat}, "@var{opt1}", @dots{})
Regular expression string matching.  Search for @var{pat} in @var{str} and
return the positions and substrings of any matches, 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 @{@var{n}@}
Match exactly @var{n} times

@item @{@var{n},@}
Match @var{n} or more times

@item @{@var{m},@var{n}@}
Match between @var{m} and @var{n} times
@end table

@item [@dots{}] [^@dots{}]

List operators.  The pattern will match any character listed between "["
and "]".  If the first character is "^" then the pattern is inverted and
any character except those listed between brackets will match.

Escape sequences defined below can also be used inside list
operators.  For example, a template for a floating point number might be
@code{[-+.\d]+}.

@item () (?:)
Grouping operator.  The first form, parentheses only, also creates a token.

@item |
Alternation operator.  Match one of a choice of regular expressions.  The
alternatives must be delimited by the grouping operator @code{()} above.

@item ^ $
Anchoring operators.  Requires pattern to occur at the start (@code{^}) or
end (@code{$}) of the string.
@end table

In addition, the following escaped characters have special meaning.

@table @code

@item \d
Match any digit

@item \D
Match any non-digit

@item \s
Match any whitespace character

@item \S
Match any non-whitespace character

@item \w
Match any word character

@item \W
Match any non-word character

@item \<
Match the beginning of a word

@item \>
Match the end of a word

@item \B
Match within a word
@end table

Implementation Note: For compatibility with @sc{matlab}, ordinary escape
sequences (e.g., @qcode{"\n"} => newline) are processed in @var{pat}
regardless of whether @var{pat} has been defined within single quotes.  Use
a second backslash to stop interpolation of the escape sequence (e.g.,
"\\n") or use the @code{regexptranslate} function.

The outputs of @code{regexp} default to the order given below

@table @var
@item s
The start indices of each matching substring

@item e
The end indices of each matching substring

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

@item m
A cell array of the text of each match

@item t
A cell array of the text of each token matched

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

@item sp
A cell array of the text not returned by match, i.e., what remains if you
split the string based on @var{pat}.
@end table

Particular output arguments, or the order of the output arguments, can be
selected by additional @var{opt} 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 @qcode{'start'}        @tab @var{s}  @tab
@item @tab @qcode{'end'}          @tab @var{e}  @tab
@item @tab @qcode{'tokenExtents'} @tab @var{te} @tab
@item @tab @qcode{'match'}        @tab @var{m}  @tab
@item @tab @qcode{'tokens'}       @tab @var{t}  @tab
@item @tab @qcode{'names'}        @tab @var{nm} @tab
@item @tab @qcode{'split'}        @tab @var{sp} @tab
@end multitable

Additional arguments are summarized below.

@table @samp
@item once
Return only the first occurrence of the pattern.

@item matchcase
Make the matching case sensitive.  (default)

Alternatively, use (?-i) in the pattern.

@item ignorecase
Ignore case when matching the pattern to the string.

Alternatively, use (?i) in the pattern.

@item stringanchors
Match the anchor characters at the beginning and end of the string.
(default)

Alternatively, use (?-m) in the pattern.

@item lineanchors
Match the anchor characters at the beginning and end of the line.

Alternatively, use (?m) in the pattern.

@item dotall
The pattern @code{.} matches all characters including the newline character.
 (default)

Alternatively, use (?s) in the pattern.

@item dotexceptnewline
The pattern @code{.} matches all characters except the newline character.

Alternatively, use (?-s) in the pattern.

@item literalspacing
All characters in the pattern, including whitespace, are significant and are
used in pattern matching.  (default)

Alternatively, use (?-x) in the pattern.

@item freespacing
The pattern may include arbitrary whitespace and also comments beginning with
the character @samp{#}.

Alternatively, use (?x) in the pattern.

@item noemptymatch
Zero-length matches are not returned.  (default)

@item emptymatch
Return zero-length matches.

@code{regexp ('a', 'b*', 'emptymatch')} returns @code{[1 2]} because there
are zero or more @qcode{'b'} characters at positions 1 and end-of-string.

@end table
@seealso{@ref{XREFregexpi,,regexpi}, @ref{XREFstrfind,,strfind}, @ref{XREFregexprep,,regexprep}}
@end deftypefn


@c regexpi libinterp/corefcn/regexp.cc
@anchor{XREFregexpi}
@deftypefn  {Built-in Function} {[@var{s}, @var{e}, @var{te}, @var{m}, @var{t}, @var{nm}, @var{sp}] =} regexpi (@var{str}, @var{pat})
@deftypefnx {Built-in Function} {[@dots{}] =} regexpi (@var{str}, @var{pat}, "@var{opt1}", @dots{})

Case insensitive regular expression string matching.  Search for @var{pat} in
@var{str} and return the positions and substrings of any matches, or empty
values if there are none.  @xref{XREFregexp,,regexp}, for details on the
syntax of the search pattern.
@seealso{@ref{XREFregexp,,regexp}}
@end deftypefn


@c regexprep libinterp/corefcn/regexp.cc
@anchor{XREFregexprep}
@deftypefn  {Built-in Function} {@var{outstr} =} regexprep (@var{string}, @var{pat}, @var{repstr})
@deftypefnx {Built-in Function} {@var{outstr} =} regexprep (@var{string}, @var{pat}, @var{repstr}, "@var{opt1}", @dots{})
Replace occurrences of pattern @var{pat} in @var{string} with @var{repstr}.

The pattern is a regular expression as documented for @code{regexp}.
@xref{XREFregexp,,regexp}.

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

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

@noindent
returns "Dunn, Bill"

Options in addition to those of @code{regexp} are

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

@end table

Implementation Note: For compatibility with @sc{matlab}, ordinary escape
sequences (e.g., @qcode{"\n"} => newline) are processed in both @var{pat}
and @var{repstr} regardless of whether they were defined within single
quotes.  Use a second backslash to stop interpolation of the escape sequence
(e.g., "\\n") or use the @code{regexptranslate} function.
@seealso{@ref{XREFregexp,,regexp}, @ref{XREFregexpi,,regexpi}, @ref{XREFstrrep,,strrep}}
@end deftypefn


@c regexptranslate scripts/strings/regexptranslate.m
@anchor{XREFregexptranslate}
@deftypefn {Function File} {} regexptranslate (@var{op}, @var{s})
Translate a string for use in a regular expression.  This may
include either wildcard replacement or special character escaping.
The behavior is controlled by @var{op} which can take the following
values

@table @asis
@item @qcode{"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 @qcode{"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{XREFregexp,,regexp}, @ref{XREFregexpi,,regexpi}, @ref{XREFregexprep,,regexprep}}
@end deftypefn


@c untabify scripts/strings/untabify.m
@anchor{XREFuntabify}
@deftypefn  {Function File} {} untabify (@var{t})
@deftypefnx {Function File} {} untabify (@var{t}, @var{tw})
@deftypefnx {Function File} {} untabify (@var{t}, @var{tw}, @var{deblank})
Replace TAB characters in @var{t}, with spaces.
The tab width is specified by @var{tw}, or defaults to eight.
The input, @var{t}, may be either a 2-D character array, or a cell
array of character strings.  The output is the same class
as the input.

If the optional argument @var{deblank} is true, then the spaces will
be removed from the end of the character data.

The following example reads a file and writes an untabified version
of the same file with trailing spaces stripped.

@example
@group
fid = fopen ("tabbed_script.m");
text = char (fread (fid, "uchar")');
fclose (fid);
fid = fopen ("untabified_script.m", "w");
text = untabify (strsplit (text, "\n"), 8, true);
fprintf (fid, "%s\n", text@{:@});
fclose (fid);
@end group
@end example

@seealso{@ref{XREFstrjust,,strjust}, @ref{XREFstrsplit,,strsplit}, @ref{XREFdeblank,,deblank}}
@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{} 255
@end group
@end example

@c bin2dec scripts/strings/bin2dec.m
@anchor{XREFbin2dec}
@deftypefn {Function File} {} bin2dec (@var{s})
Return the decimal number corresponding to the binary number represented
by the string @var{s}.  For example:

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

Spaces are ignored during conversion and may be used to make the binary
number more readable.

@example
@group
bin2dec ("1000 0001")
     @result{} 129
@end group
@end example

If @var{s} is a string matrix, return a column vector with one converted
number per row of @var{s}; Invalid rows evaluate to NaN@.

If @var{s} is a cell array of strings, return a column vector with one
converted number per cell element in @var{s}.
@seealso{@ref{XREFdec2bin,,dec2bin}, @ref{XREFbase2dec,,base2dec}, @ref{XREFhex2dec,,hex2dec}}
@end deftypefn


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

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

If @var{d} is a matrix or cell array, return a string matrix with one
row per element in @var{d}, 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{XREFbin2dec,,bin2dec}, @ref{XREFdec2base,,dec2base}, @ref{XREFdec2hex,,dec2hex}}
@end deftypefn


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

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

If @var{d} is a matrix or cell array, return a string matrix with one
row per element in @var{d}, 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{XREFhex2dec,,hex2dec}, @ref{XREFdec2base,,dec2base}, @ref{XREFdec2bin,,dec2bin}}
@end deftypefn


@c hex2dec scripts/strings/hex2dec.m
@anchor{XREFhex2dec}
@deftypefn {Function File} {} hex2dec (@var{s})
Return the integer corresponding to the hexadecimal number represented
by 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, return a column vector with one converted
number per row of @var{s}; Invalid rows evaluate to NaN@.

If @var{s} is a cell array of strings, return a column vector with one
converted number per cell element in @var{s}.

@seealso{@ref{XREFdec2hex,,dec2hex}, @ref{XREFbase2dec,,base2dec}, @ref{XREFbin2dec,,bin2dec}}
@end deftypefn


@c dec2base scripts/strings/dec2base.m
@anchor{XREFdec2base}
@deftypefn  {Function File} {} dec2base (@var{d}, @var{base})
@deftypefnx {Function File} {} dec2base (@var{d}, @var{base}, @var{len})
Return a string of symbols in base @var{base} corresponding to
the non-negative integer @var{d}.

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

If @var{d} is a matrix or cell array, return a string matrix with one
row per element in @var{d}, padded with leading zeros to the width of 
the largest value.

If @var{base} is a string then the characters of @var{base} are used as
the symbols for the digits of @var{d}.  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{XREFbase2dec,,base2dec}, @ref{XREFdec2bin,,dec2bin}, @ref{XREFdec2hex,,dec2hex}}
@end deftypefn


@c base2dec scripts/strings/base2dec.m
@anchor{XREFbase2dec}
@deftypefn {Function File} {} base2dec (@var{s}, @var{base})
Convert @var{s} from a string of digits in base @var{base} to a decimal
integer (base 10).

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

If @var{s} is a string matrix, return a column vector with one value per
row of @var{s}.  If a row contains invalid symbols then the
corresponding value will be NaN@.

If @var{s} is a cell array of strings, return a column vector with one
value per cell element in @var{s}.

If @var{base} is a string, the characters of @var{base} 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{XREFdec2base,,dec2base}, @ref{XREFbin2dec,,bin2dec}, @ref{XREFhex2dec,,hex2dec}}
@end deftypefn


@c num2hex libinterp/corefcn/hex2num.cc
@anchor{XREFnum2hex}
@deftypefn {Built-in Function} {@var{s} =} num2hex (@var{n})
Typecast a double or single precision number or vector to a 8 or 16
character hexadecimal string of the IEEE 754 representation of the number.
For example:

@example
@group
num2hex ([-1, 1, e, Inf])
@result{} "bff0000000000000
    3ff0000000000000
    4005bf0a8b145769
    7ff0000000000000"
@end group
@end example

If the argument @var{n} is a single precision number or vector, the returned
string has a length of 8.  For example:

@example
@group
num2hex (single ([-1, 1, e, Inf]))
@result{} "bf800000
    3f800000
    402df854
    7f800000"
@end group
@end example
@seealso{@ref{XREFhex2num,,hex2num}, @ref{XREFhex2dec,,hex2dec}, @ref{XREFdec2hex,,dec2hex}}
@end deftypefn


@c hex2num libinterp/corefcn/hex2num.cc
@anchor{XREFhex2num}
@deftypefn  {Built-in Function} {@var{n} =} hex2num (@var{s})
@deftypefnx {Built-in Function} {@var{n} =} hex2num (@var{s}, @var{class})
Typecast the 16 character hexadecimal character string to an IEEE 754
double precision number.  If fewer than 16 characters are given the
strings are right padded with @qcode{'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

The optional argument @var{class} can be passed as the string
@qcode{"single"} to specify that the given string should be interpreted as
a single precision number.  In this case, @var{s} should be an 8 character
hexadecimal string.  For example: 

@example
@group
hex2num (["402df854"; "41200000"], "single")
   @result{} [2.7183; 10.000]
@end group
@end example
@seealso{@ref{XREFnum2hex,,num2hex}, @ref{XREFhex2dec,,hex2dec}, @ref{XREFdec2hex,,dec2hex}}
@end deftypefn


@c str2double libinterp/corefcn/str2double.cc
@anchor{XREFstr2double}
@deftypefn {Built-in Function} {} str2double (@var{s})
Convert a string to a real or complex number.

The string must be in one of the following formats where
a and b are real numbers and the complex unit is @qcode{'i'} or @qcode{'j'}:

@itemize
@item a + bi

@item a + b*i

@item a + i*b

@item bi + a

@item b*i + a

@item i*b + a
@end itemize

If present, a and/or b are of the form @nospell{[+-]d[,.]d[[eE][+-]d]} where
the brackets indicate optional arguments and @qcode{'d'} indicates zero or
more digits.  The special input values @code{Inf}, @code{NaN}, and @code{NA}
are also accepted.

@var{s} may be a character string, character matrix, or cell array.
For character arrays the conversion is repeated for every row, and
a double or complex array is returned.  Empty rows in @var{s} are deleted
and not returned in the numeric array.  For cell arrays each character
string element is processed and a double or complex array of the same
dimensions as @var{s} is returned.

For unconvertible scalar or character string input @code{str2double} returns
a NaN@.  Similarly, for character array input @code{str2double} returns a
NaN for any row of @var{s} that could not be converted.  For a cell array,
@code{str2double} returns a NaN for any element of @var{s} for which
conversion fails.  Note that numeric elements in a mixed string/numeric
cell array are not strings and the conversion will fail for these elements
and return NaN.

@code{str2double} can replace @code{str2num}, and it avoids the security
risk of using @code{eval} on unknown data.
@seealso{@ref{XREFstr2num,,str2num}}
@end deftypefn


@c strjust scripts/strings/strjust.m
@anchor{XREFstrjust}
@deftypefn  {Function File} {} strjust (@var{s})
@deftypefnx {Function File} {} strjust (@var{s}, @var{pos})
Return the text, @var{s}, justified according to @var{pos}, which may
be @qcode{"left"}, @qcode{"center"}, or @qcode{"right"}.  If @var{pos}
is omitted it defaults to @qcode{"right"}.

Null characters are replaced by spaces.  All other character
data are treated as non-white space.

Example:

@example
@group
strjust (["a"; "ab"; "abc"; "abcd"])
     @result{}
        "   a"
        "  ab"
        " abc"
        "abcd"
@end group
@end example
@seealso{@ref{XREFdeblank,,deblank}, @ref{XREFstrrep,,strrep}, @ref{XREFstrtrim,,strtrim}, @ref{XREFuntabify,,untabify}}
@end deftypefn


@c str2num scripts/strings/str2num.m
@anchor{XREFstr2num}
@deftypefn  {Function File} {@var{x} =} str2num (@var{s})
@deftypefnx {Function File} {[@var{x}, @var{state}] =} 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{} 1  2  3
         4  5  6
@end group
@end example

The optional second output, @var{state}, is logically true when the
conversion is successful.  If the conversion fails the numeric output,
@var{x}, is empty and @var{state} is false.

@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} for a safer and faster
conversion.

For cell array of strings use @code{str2double}.
@seealso{@ref{XREFstr2double,,str2double}, @ref{XREFeval,,eval}}
@end deftypefn


@c toascii libinterp/corefcn/mappers.cc
@anchor{XREFtoascii}
@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{XREFchar,,char}}
@end deftypefn


@c tolower libinterp/corefcn/mappers.cc
@anchor{XREFtolower}
@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 uppercase
character replaced by the corresponding lowercase 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{XREFtoupper,,toupper}}
@end deftypefn


@c toupper libinterp/corefcn/mappers.cc
@anchor{XREFtoupper}
@deftypefn  {Mapping Function} {} toupper (@var{s})
@deftypefnx {Mapping Function} {} upper (@var{s})
Return a copy of the string or cell string @var{s}, with each lowercase
character replaced by the corresponding uppercase 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{XREFtolower,,tolower}}
@end deftypefn


@c do_string_escapes libinterp/corefcn/utils.cc
@anchor{XREFdo_string_escapes}
@deftypefn {Built-in Function} {} do_string_escapes (@var{string})
Convert special characters in @var{string} to their escaped forms.
@end deftypefn


@c undo_string_escapes libinterp/corefcn/utils.cc
@anchor{XREFundo_string_escapes}
@deftypefn {Built-in Function} {} undo_string_escapes (@var{s})
Convert 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 isalnum libinterp/corefcn/mappers.cc
@anchor{XREFisalnum}
@deftypefn {Mapping Function} {} isalnum (@var{s})
Return a logical array which is true where the elements of @var{s} are
letters or digits and false where they are not.  This is equivalent to
(@code{isalpha (@var{s}) | isdigit (@var{s})}).
@seealso{@ref{XREFisalpha,,isalpha}, @ref{XREFisdigit,,isdigit}, @ref{XREFispunct,,ispunct}, @ref{XREFisspace,,isspace}, @ref{XREFiscntrl,,iscntrl}}
@end deftypefn


@c isalpha libinterp/corefcn/mappers.cc
@anchor{XREFisalpha}
@deftypefn {Mapping Function} {} isalpha (@var{s})
Return a logical array which is true where the elements of @var{s} are
letters and false where they are not.  This is equivalent to
(@code{islower (@var{s}) | isupper (@var{s})}).
@seealso{@ref{XREFisdigit,,isdigit}, @ref{XREFispunct,,ispunct}, @ref{XREFisspace,,isspace}, @ref{XREFiscntrl,,iscntrl}, @ref{XREFisalnum,,isalnum}, @ref{XREFislower,,islower}, @ref{XREFisupper,,isupper}}
@end deftypefn


@c isletter scripts/strings/isletter.m
@anchor{XREFisletter}
@deftypefn {Function File} {} isletter (@var{s})
Return a logical array which is true where the elements of @var{s}
are letters and false where they are not.  This is an alias for
the @code{isalpha} function.
@seealso{@ref{XREFisalpha,,isalpha}, @ref{XREFisdigit,,isdigit}, @ref{XREFispunct,,ispunct}, @ref{XREFisspace,,isspace}, @ref{XREFiscntrl,,iscntrl}, @ref{XREFisalnum,,isalnum}}
@end deftypefn


@c islower libinterp/corefcn/mappers.cc
@anchor{XREFislower}
@deftypefn {Mapping Function} {} islower (@var{s})
Return a logical array which is true where the elements of @var{s} are
lowercase letters and false where they are not.
@seealso{@ref{XREFisupper,,isupper}, @ref{XREFisalpha,,isalpha}, @ref{XREFisletter,,isletter}, @ref{XREFisalnum,,isalnum}}
@end deftypefn


@c isupper libinterp/corefcn/mappers.cc
@anchor{XREFisupper}
@deftypefn {Mapping Function} {} isupper (@var{s})
Return a logical array which is true where the elements of @var{s} are
uppercase letters and false where they are not.
@seealso{@ref{XREFislower,,islower}, @ref{XREFisalpha,,isalpha}, @ref{XREFisletter,,isletter}, @ref{XREFisalnum,,isalnum}}
@end deftypefn


@c isdigit libinterp/corefcn/mappers.cc
@anchor{XREFisdigit}
@deftypefn {Mapping Function} {} isdigit (@var{s})
Return a logical array which is true where the elements of @var{s} are
decimal digits (0-9) and false where they are not.
@seealso{@ref{XREFisxdigit,,isxdigit}, @ref{XREFisalpha,,isalpha}, @ref{XREFisletter,,isletter}, @ref{XREFispunct,,ispunct}, @ref{XREFisspace,,isspace}, @ref{XREFiscntrl,,iscntrl}}
@end deftypefn


@c isxdigit libinterp/corefcn/mappers.cc
@anchor{XREFisxdigit}
@deftypefn {Mapping Function} {} isxdigit (@var{s})
Return a logical array which is true where the elements of @var{s} are
hexadecimal digits (0-9 and @nospell{a-fA-F}).
@seealso{@ref{XREFisdigit,,isdigit}}
@end deftypefn


@c ispunct libinterp/corefcn/mappers.cc
@anchor{XREFispunct}
@deftypefn {Mapping Function} {} ispunct (@var{s})
Return a logical array which is true where the elements of @var{s} are
punctuation characters and false where they are not.
@seealso{@ref{XREFisalpha,,isalpha}, @ref{XREFisdigit,,isdigit}, @ref{XREFisspace,,isspace}, @ref{XREFiscntrl,,iscntrl}}
@end deftypefn


@c isspace libinterp/corefcn/mappers.cc
@anchor{XREFisspace}
@deftypefn {Mapping Function} {} isspace (@var{s})
Return a logical array which is true where the elements of @var{s} are
whitespace characters (space, formfeed, newline, carriage return, tab, and
vertical tab) and false where they are not.
@seealso{@ref{XREFiscntrl,,iscntrl}, @ref{XREFispunct,,ispunct}, @ref{XREFisalpha,,isalpha}, @ref{XREFisdigit,,isdigit}}
@end deftypefn


@c iscntrl libinterp/corefcn/mappers.cc
@anchor{XREFiscntrl}
@deftypefn {Mapping Function} {} iscntrl (@var{s})
Return a logical array which is true where the elements of @var{s} are
control characters and false where they are not.
@seealso{@ref{XREFispunct,,ispunct}, @ref{XREFisspace,,isspace}, @ref{XREFisalpha,,isalpha}, @ref{XREFisdigit,,isdigit}}
@end deftypefn


@c isgraph libinterp/corefcn/mappers.cc
@anchor{XREFisgraph}
@deftypefn {Mapping Function} {} isgraph (@var{s})
Return a logical array which is true where the elements of @var{s} are
printable characters (but not the space character) and false where they are
not.
@seealso{@ref{XREFisprint,,isprint}}
@end deftypefn


@c isprint libinterp/corefcn/mappers.cc
@anchor{XREFisprint}
@deftypefn {Mapping Function} {} isprint (@var{s})
Return a logical array which is true where the elements of @var{s} are
printable characters (including the space character) and false where they
are not.
@seealso{@ref{XREFisgraph,,isgraph}}
@end deftypefn


@c isascii libinterp/corefcn/mappers.cc
@anchor{XREFisascii}
@deftypefn {Mapping Function} {} isascii (@var{s})
Return a logical array which is true where the elements of @var{s} are
ASCII characters (in the range 0 to 127 decimal) and false where they are
not.
@end deftypefn


@c isstrprop scripts/strings/isstrprop.m
@anchor{XREFisstrprop}
@deftypefn {Function File} {} isstrprop (@var{str}, @var{prop})
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{prop} must be one of

@table @asis
@item @qcode{"alpha"}
True for characters that are alphabetic (letters).

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

@item @qcode{"lower"}
True for lowercase letters.

@item @qcode{"upper"}
True for uppercase letters.

@item @qcode{"digit"}
True for decimal digits (0-9).

@item @qcode{"xdigit"}
True for hexadecimal digits (@nospell{a-fA-F0-9}).

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

@item @qcode{"punct"}
True for punctuation characters (printing characters except space
or letter or digit).

@item @qcode{"cntrl"}
True for control characters.

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

@item @qcode{"print"}
True for printing characters including space.

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

@end table

@seealso{@ref{XREFisalpha,,isalpha}, @ref{XREFisalnum,,isalnum}, @ref{XREFislower,,islower}, @ref{XREFisupper,,isupper}, @ref{XREFisdigit,,isdigit}, @ref{XREFisxdigit,,isxdigit}, @ref{XREFisspace,,isspace}, @ref{XREFispunct,,ispunct}, @ref{XREFiscntrl,,iscntrl}, @ref{XREFisgraph,,isgraph}, @ref{XREFisprint,,isprint}, @ref{XREFisascii,,isascii}}
@end deftypefn