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

@c Copyright (C) 1996-2011 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 ischar src/strfns.cc
@anchor{doc-ischar}
@deftypefn {Built-in Function} {} ischar (@var{x})
Return true if @var{x} is a character array.
@seealso{@ref{doc-isfloat,,isfloat}, @ref{doc-isinteger,,isinteger}, @ref{doc-islogical,,islogical}, @ref{doc-isnumeric,,isnumeric}, @ref{doc-iscellstr,,iscellstr}, @ref{doc-isa,,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{} 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 string_fill_char src/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 blanks scripts/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 char src/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 strvcat src/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 strcat scripts/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 cstrcat scripts/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 mat2str scripts/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 num2str scripts/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 int2str scripts/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 strcmp src/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 strncmp src/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 strcmpi src/strfns.cc
@anchor{doc-strcmpi}
@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{doc-strcmp,,strcmp}, @ref{doc-strncmp,,strncmp}, @ref{doc-strncmpi,,strncmpi}}
@end deftypefn


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


@c validatestring scripts/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 deblank scripts/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 strtrim scripts/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 strtrunc scripts/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 findstr scripts/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 strchr scripts/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 index scripts/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 rindex scripts/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 strfind src/DLD-FUNCTIONS/strfind.cc
@anchor{doc-strfind}
@deftypefn  {Loadable Function} {@var{idx} =} strfind (@var{str}, @var{pattern})
@deftypefnx {Loadable Function} {@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 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", "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-regexp,,regexp}, @ref{doc-regexpi,,regexpi}, @ref{doc-find,,find}}
@end deftypefn


@c strmatch scripts/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}.
Trailing whitespace is ignored.
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 strtok scripts/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 strsplit scripts/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 strread scripts/io/strread.m
@anchor{doc-strread}
@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{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 %d
@itemx %f
The word is parsed as a number.

@item %*
The word is skipped.
@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}.

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

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

@table @asis
@item "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 "shell"
Everything from @code{#} characters to the nearest end-line is skipped.

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

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

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

@item "delimiter"
Any character in @var{value} will be used to split @var{str} into words.

@item "emptyvalue"
Parts of the output where no word is available is filled with @var{value}.
@end table

@seealso{@ref{doc-textread,,textread}, @ref{doc-load,,load}, @ref{doc-dlmread,,dlmread}, @ref{doc-fscanf,,fscanf}}
@end deftypefn


@c strrep src/DLD-FUNCTIONS/strfind.cc
@anchor{doc-strrep}
@deftypefn  {Loadable Function} {} strrep (@var{s}, @var{ptn}, @var{rep})
@deftypefnx {Loadable Function} {} strrep (@var{s}, @var{ptn}, @var{rep}, "overlaps", @var{o})
Replace all occurrences of the substring @var{ptn} in the string @var{s}
with the string @var{rep} and return the result.  For example:

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

@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.
@seealso{@ref{doc-regexprep,,regexprep}, @ref{doc-strfind,,strfind}, @ref{doc-findstr,,findstr}}
@end deftypefn


@c substr scripts/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 regexp src/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{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

@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.  Note,
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
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 \s
Match any whitespace character

@item \S
Match any non-whitespace character

@item \d
Match any digit

@item \D
Match any non-digit
@end table

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{})}.
@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 '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

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.

@end table
@seealso{@ref{doc-regexpi,,regexpi}, @ref{doc-strfind,,strfind}, @ref{doc-regexprep,,regexprep}}
@end deftypefn


@c regexpi src/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{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{doc-regexp,,regexp}, for details on the
syntax of the search pattern.
@seealso{@ref{doc-regexp,,regexp}}
@end deftypefn


@c regexprep src/DLD-FUNCTIONS/regexp.cc
@anchor{doc-regexprep}
@deftypefn  {Loadable Function} {@var{outstr} =} regexprep (@var{string}, @var{pat}, @var{repstr})
@deftypefnx {Loadable 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{doc-regexp,,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
@seealso{@ref{doc-regexp,,regexp}, @ref{doc-regexpi,,regexpi}, @ref{doc-strrep,,strrep}}
@end deftypefn


@c regexptranslate scripts/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


@c untabify scripts/strings/untabify.m
@anchor{doc-untabify}
@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{doc-strjust,,strjust}, @ref{doc-strsplit,,strsplit}, @ref{doc-deblank,,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{} ans = 255
@end group
@end example

@c bin2dec scripts/strings/bin2dec.m
@anchor{doc-bin2dec}
@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

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


@c dec2bin scripts/strings/dec2bin.m
@anchor{doc-dec2bin}
@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 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-dec2hex,,dec2hex}}
@end deftypefn


@c dec2hex scripts/strings/dec2hex.m
@anchor{doc-dec2hex}
@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 vector, return 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-dec2bin,,dec2bin}}
@end deftypefn


@c hex2dec scripts/strings/hex2dec.m
@anchor{doc-hex2dec}
@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, 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-bin2dec,,bin2dec}}
@end deftypefn


@c dec2base scripts/strings/dec2base.m
@anchor{doc-dec2base}
@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 vector, return a string matrix with one row per value,
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{doc-base2dec,,base2dec}, @ref{doc-dec2bin,,dec2bin}, @ref{doc-dec2hex,,dec2hex}}
@end deftypefn


@c base2dec scripts/strings/base2dec.m
@anchor{doc-base2dec}
@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 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{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{doc-dec2base,,dec2base}, @ref{doc-bin2dec,,bin2dec}, @ref{doc-hex2dec,,hex2dec}}
@end deftypefn


@c num2hex src/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 hex2num src/DLD-FUNCTIONS/hex2num.cc
@anchor{doc-hex2num}
@deftypefn {Loadable Function} {@var{n} =} hex2num (@var{s})
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 '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 str2double src/DLD-FUNCTIONS/str2double.cc
@anchor{doc-str2double}
@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 'i' or '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 'd' indicates zero or more
digits.  The special input values @code{Inf}, @code{NaN}, and @code{NA} are
also accepted.

@var{s} may also be a character matrix, in which case the conversion is
repeated for each row.  Or @var{s} may be a cell array of strings, in which
case each element is converted and an array of the same dimensions is
returned.

@code{str2double} returns NaN for elements of @var{s} which cannot be
converted.

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


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

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{} ans =
           a
          ab
         abc
        abcd
@end group
@end example
@seealso{@ref{doc-deblank,,deblank}, @ref{doc-strrep,,strrep}, @ref{doc-strtrim,,strtrim}, @ref{doc-untabify,,untabify}}
@end deftypefn


@c str2num scripts/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 toascii src/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 tolower src/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 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{doc-toupper,,toupper}}
@end deftypefn


@c toupper src/mappers.cc
@anchor{doc-toupper}
@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{doc-tolower,,tolower}}
@end deftypefn


@c do_string_escapes src/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 undo_string_escapes src/utils.cc
@anchor{doc-undo_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 src/mappers.cc
@anchor{doc-isalnum}
@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{doc-isalpha,,isalpha}, @ref{doc-isdigit,,isdigit}, @ref{doc-ispunct,,ispunct}, @ref{doc-isspace,,isspace}, @ref{doc-iscntrl,,iscntrl}}
@end deftypefn


@c isalpha src/mappers.cc
@anchor{doc-isalpha}
@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{doc-isdigit,,isdigit}, @ref{doc-ispunct,,ispunct}, @ref{doc-isspace,,isspace}, @ref{doc-iscntrl,,iscntrl}, @ref{doc-isalnum,,isalnum}, @ref{doc-islower,,islower}, @ref{doc-isupper,,isupper}}
@end deftypefn


@c isletter scripts/strings/isletter.m
@anchor{doc-isletter}
@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{doc-isalpha,,isalpha}, @ref{doc-isdigit,,isdigit}, @ref{doc-ispunct,,ispunct}, @ref{doc-isspace,,isspace}, @ref{doc-iscntrl,,iscntrl}, @ref{doc-isalnum,,isalnum}}
@end deftypefn


@c islower src/mappers.cc
@anchor{doc-islower}
@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{doc-isupper,,isupper}, @ref{doc-isalpha,,isalpha}, @ref{doc-isletter,,isletter}, @ref{doc-isalnum,,isalnum}}
@end deftypefn


@c isupper src/mappers.cc
@anchor{doc-isupper}
@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{doc-islower,,islower}, @ref{doc-isalpha,,isalpha}, @ref{doc-isletter,,isletter}, @ref{doc-isalnum,,isalnum}}
@end deftypefn


@c isdigit src/mappers.cc
@anchor{doc-isdigit}
@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{doc-isxdigit,,isxdigit}, @ref{doc-isalpha,,isalpha}, @ref{doc-isletter,,isletter}, @ref{doc-ispunct,,ispunct}, @ref{doc-isspace,,isspace}, @ref{doc-iscntrl,,iscntrl}}
@end deftypefn


@c isxdigit src/mappers.cc
@anchor{doc-isxdigit}
@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{doc-isdigit,,isdigit}}
@end deftypefn


@c ispunct src/mappers.cc
@anchor{doc-ispunct}
@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{doc-isalpha,,isalpha}, @ref{doc-isdigit,,isdigit}, @ref{doc-isspace,,isspace}, @ref{doc-iscntrl,,iscntrl}}
@end deftypefn


@c isspace src/mappers.cc
@anchor{doc-isspace}
@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{doc-iscntrl,,iscntrl}, @ref{doc-ispunct,,ispunct}, @ref{doc-isalpha,,isalpha}, @ref{doc-isdigit,,isdigit}}
@end deftypefn


@c iscntrl src/mappers.cc
@anchor{doc-iscntrl}
@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{doc-ispunct,,ispunct}, @ref{doc-isspace,,isspace}, @ref{doc-isalpha,,isalpha}, @ref{doc-isdigit,,isdigit}}
@end deftypefn


@c isgraph src/mappers.cc
@anchor{doc-isgraph}
@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{doc-isprint,,isprint}}
@end deftypefn


@c isprint src/mappers.cc
@anchor{doc-isprint}
@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{doc-isgraph,,isgraph}}
@end deftypefn


@c isascii src/mappers.cc
@anchor{doc-isascii}
@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{doc-isstrprop}
@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 "alpha"
True for characters that are alphabetic (letters).

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

@item "lower"
True for lowercase letters.

@item "upper"
True for uppercase letters.

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

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

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

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

@item "cntrl"
True for control characters.

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

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

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

@end table

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

