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

@c Copyright (C) 1996-2025 The Octave Project Developers
@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
@c the Free Software Foundation, either version 3 of the License, or
@c (at your option) any later version.
@c
@c Octave is distributed in the hope that it will be useful, but
@c WITHOUT ANY WARRANTY; without even the implied warranty of
@c MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
@c GNU General Public License 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 <https://www.gnu.org/licenses/>.

@node Strings
@chapter Strings
@cindex strings
@cindex character strings
@opindex "
@opindex @code{'}

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.

While strings can in principle store arbitrary content, most functions expect
them to be UTF-8 encoded Unicode strings.

Furthermore, it is 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}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn {} {@var{str} =} 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
@xseealso{@ref{XREFrepmat,,repmat}}
@end deftypefn


@menu
* Escape Sequences in String Constants::
* Character Arrays::
* String Operations::
* Converting Strings::
* 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
double ("\n")
    @result{} 10
double ('\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}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn {} {@var{tf} =} is_dq_string (@var{x})
Return true if @var{x} is a double-quoted character string.
@xseealso{@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}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn {} {@var{tf} =} is_sq_string (@var{x})
Return true if @var{x} is a single-quoted character string.
@xseealso{@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}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn {} {@var{tf} =} ischar (@var{x})
Return true if @var{x} is a character array.
@xseealso{@ref{XREFisfloat,,isfloat}, @ref{XREFisinteger,,isinteger}, @ref{XREFislogical,,islogical}, @ref{XREFisnumeric,,isnumeric}, @ref{XREFisstring,,isstring}, @ref{XREFiscellstr,,iscellstr}, @ref{XREFisa,,isa}}
@end deftypefn


@c isstring scripts/strings/isstring.m
@anchor{XREFisstring}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn {} {@var{tf} =} isstring (@var{s})
Return true if @var{s} is a string array.

A string array is a data type that stores strings (row vectors of
characters) at each element in the array.  It is distinct from character
arrays which are N-dimensional arrays where each element is a single 1x1
character.  It is also distinct from cell arrays of strings which store
strings at each element, but use cell indexing @samp{@{@}} to access
elements rather than string arrays which use ordinary array indexing
@samp{()}.

Programming Note: Octave does not yet implement string arrays so this
function will always return false.
@xseealso{@ref{XREFischar,,ischar}, @ref{XREFiscellstr,,iscellstr}, @ref{XREFisfloat,,isfloat}, @ref{XREFisinteger,,isinteger}, @ref{XREFislogical,,islogical}, @ref{XREFisnumeric,,isnumeric}, @ref{XREFisa,,isa}}
@end deftypefn


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

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

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

ischar ("my string") && isrow ("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-eval.cc
@anchor{XREFstring_fill_char}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {@var{val} =} string_fill_char ()
@deftypefnx {} {@var{old_val} =} string_fill_char (@var{new_val})
@deftypefnx {} {@var{old_val} =} 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.

The value must be a single character and the default 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


Another useful function to control the text justification in this case is
the @code{strjust} function.

@c strjust scripts/strings/strjust.m
@anchor{XREFstrjust}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {@var{str} =} strjust (@var{s})
@deftypefnx {} {@var{str} =} 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
@xseealso{@ref{XREFdeblank,,deblank}, @ref{XREFstrrep,,strrep}, @ref{XREFstrtrim,,strtrim}, @ref{XREFuntabify,,untabify}}
@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 String Operations
@section String Operations

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.

@menu
* Common String Operations::
* Concatenating Strings::
* Splitting and Joining Strings::
* Searching in Strings::
* Searching and Replacing in Strings::
@end menu

@node Common String Operations
@subsection Common String Operations

The following functions are useful to perform common String operations.

@c lower libinterp/corefcn/mappers.cc
@anchor{XREFlower}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {@var{y} =} lower (@var{s})
@deftypefnx {} {@var{y} =} tolower (@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
lower ("MiXeD cAsE 123")
    @result{} "mixed case 123"
@end group
@end example

Programming Note: @code{tolower} is an alias for @code{lower} and either name
can be used in Octave.

@xseealso{@ref{XREFupper,,upper}}
@end deftypefn


@c upper libinterp/corefcn/mappers.cc
@anchor{XREFupper}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {@var{y} =} upper (@var{s})
@deftypefnx {} {@var{y} =} toupper (@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
upper ("MiXeD cAsE 123")
    @result{} "MIXED CASE 123"
@end group
@end example

Programming Note: @code{toupper} is an alias for @code{upper} and either name
can be used in Octave.

@xseealso{@ref{XREFlower,,lower}}
@end deftypefn


@c deblank scripts/strings/deblank.m
@anchor{XREFdeblank}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn {} {@var{s} =} 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
the 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
@xseealso{@ref{XREFstrtrim,,strtrim}}
@end deftypefn


@c strtrim scripts/strings/strtrim.m
@anchor{XREFstrtrim}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn {} {@var{s} =} 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
@xseealso{@ref{XREFdeblank,,deblank}}
@end deftypefn


@c strtrunc scripts/strings/strtrunc.m
@anchor{XREFstrtrunc}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn {} {@var{s} =} 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 untabify scripts/strings/untabify.m
@anchor{XREFuntabify}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {@var{str} =} untabify (@var{t})
@deftypefnx {} {@var{str} =} untabify (@var{t}, @var{tw})
@deftypefnx {} {@var{str} =} untabify (@var{t}, @var{tw}, @var{deblank})
Replace TAB characters in @var{t} with spaces.

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.

The tab width is specified by @var{tw}, and defaults to eight.

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

@xseealso{@ref{XREFstrjust,,strjust}, @ref{XREFstrsplit,,strsplit}, @ref{XREFdeblank,,deblank}}
@end deftypefn


@c do_string_escapes libinterp/corefcn/utils.cc
@anchor{XREFdo_string_escapes}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn {} {@var{newstr} =} do_string_escapes (@var{string})
Convert escape sequences in @var{string} to the characters they represent.

Escape sequences begin with a leading backslash
(@qcode{'@backslashchar{}'}) followed by 1--3 characters
(.e.g., @qcode{"@backslashchar{}n"} => newline).
@xseealso{@ref{XREFundo_string_escapes,,undo_string_escapes}}
@end deftypefn


@c undo_string_escapes libinterp/corefcn/utils.cc
@anchor{XREFundo_string_escapes}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn {} {@var{newstr} =} undo_string_escapes (@var{string})
Convert special characters in @var{string} back to their escaped forms.

For example, the expression

@example
@var{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.
@xseealso{@ref{XREFdo_string_escapes,,do_string_escapes}}
@end deftypefn


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

The @code{newline} function can be used to join strings such that they appear
as multiple lines of text when displayed.

@c newline libinterp/corefcn/strfns.cc
@anchor{XREFnewline}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn {} {@var{c} =} newline
Return the character corresponding to a newline.

This is equivalent to @qcode{"@backslashchar{}n"}.

Example Code

@example
@group
joined_string = [newline "line1" newline "line2"]
@result{}
line1
line2
@end group
@end example

@xseealso{@ref{XREFstrcat,,strcat}, @ref{XREFstrjoin,,strjoin}, @ref{XREFstrsplit,,strsplit}}
@end deftypefn


In addition, 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 UTF-8
character for each element (or multi-byte sequence), as in the following
example:

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

For conversion between locale encodings and UTF-8, see
@ref{XREFunicode2native,,unicode2native} and
@ref{XREFnative2unicode,,native2unicode}.

@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}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {@var{C} =} char (@var{A})
@deftypefnx {} {@var{C} =} char (@var{A}, @dots{})
@deftypefnx {} {@var{C} =} char (@var{str1}, @var{str2}, @dots{})
@deftypefnx {} {@var{C} =} char (@var{cell_array})
@deftypefnx {} {'' =} char ()

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
@xseealso{@ref{XREFstrvcat,,strvcat}, @ref{XREFcellstr,,cellstr}}
@end deftypefn


@c strvcat libinterp/corefcn/strfns.cc
@anchor{XREFstrvcat}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {@var{C} =} strvcat (@var{A})
@deftypefnx {} {@var{C} =} strvcat (@var{A}, @dots{})
@deftypefnx {} {@var{C} =} strvcat (@var{str1}, @var{str2}, @dots{})
@deftypefnx {} {@var{C} =} 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
@xseealso{@ref{XREFchar,,char}, @ref{XREFstrcat,,strcat}, @ref{XREFcstrcat,,cstrcat}}
@end deftypefn


@c strcat scripts/strings/strcat.m
@anchor{XREFstrcat}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn {} {@var{str} =} 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

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


@c cstrcat scripts/strings/cstrcat.m
@anchor{XREFcstrcat}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn {} {@var{str} =} cstrcat (@var{s1}, @var{s2}, @dots{})
Return a string containing all the arguments concatenated horizontally
with trailing white space 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
@xseealso{@ref{XREFstrcat,,strcat}, @ref{XREFchar,,char}, @ref{XREFstrvcat,,strvcat}}
@end deftypefn


@node Splitting and Joining Strings
@subsection Splitting and Joining Strings

@c substr scripts/strings/substr.m
@anchor{XREFsubstr}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {@var{str} =} substr (@var{s}, @var{offset})
@deftypefnx {} {} 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 strtok scripts/strings/strtok.m
@anchor{XREFstrtok}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {[@var{tok}, @var{rem}] =} strtok (@var{str})
@deftypefnx {} {[@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}.

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

Leading delimiters are ignored.  If @var{delim} is not specified,
whitespace is assumed.

If @var{rem} is requested, it contains the remainder of the string, starting
at the first delimiter.

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


@c strsplit scripts/strings/strsplit.m
@anchor{XREFstrsplit}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {[@var{cstr}] =} strsplit (@var{str})
@deftypefnx {} {[@var{cstr}] =} strsplit (@var{str}, @var{del})
@deftypefnx {} {[@var{cstr}] =} strsplit (@dots{}, @var{name}, @var{value})
@deftypefnx {} {[@var{cstr}, @var{matches}] =} strsplit (@dots{})
Split the string @var{str} using the delimiters specified by @var{del} and
return a cell string array of substrings.

If a delimiter is not specified the string is split at whitespace
@code{@{" ", "\f", "\n", "\r", "\t", "\v"@}}.  Otherwise, the delimiter,
@var{del} must be a string or cell array of strings.  By default,
consecutive delimiters in the input string @var{s} are collapsed into one
resulting in a single split.

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

@itemize
@item @var{collapsedelimiters} which may take the value of @code{true}
(default) or @code{false}.

@item @var{delimitertype} which may take the value of @qcode{"simple"}
(default) or @nospell{@qcode{"regularexpression"}}.  A simple delimiter
matches the text exactly as written.  Otherwise, the syntax for regular
expressions outlined in @code{regexp} is used.
@end itemize

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

Examples with simple delimiters:

@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", @{" ", ",", "foo", "bar"@})
      @result{}
          @{
            [1,1] = a
            [1,2] = b
            [1,3] = c
          @}

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

@end example

Examples with @nospell{regularexpression} delimiters:

@smallexample
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", '[, ]', "collapsedelimiters", 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 smallexample

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


@c ostrsplit scripts/strings/ostrsplit.m
@anchor{XREFostrsplit}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {[@var{cstr}] =} ostrsplit (@var{s}, @var{sep})
@deftypefnx {} {[@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
@xseealso{@ref{XREFstrsplit,,strsplit}, @ref{XREFstrtok,,strtok}}
@end deftypefn


@c strjoin scripts/strings/strjoin.m
@anchor{XREFstrjoin}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {@var{str} =} strjoin (@var{cstr})
@deftypefnx {} {@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} are
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
@xseealso{@ref{XREFstrsplit,,strsplit}}
@end deftypefn


@node Searching in Strings
@subsection Searching in 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}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn {} {@var{tf} =} strcmp (@var{str1}, @var{str2})
Return 1 if the character strings @var{str1} and @var{str2} are the same,
and 0 otherwise.

If either @var{str1} or @var{str2} 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.
@xseealso{@ref{XREFstrcmpi,,strcmpi}, @ref{XREFstrncmp,,strncmp}, @ref{XREFstrncmpi,,strncmpi}}
@end deftypefn


@c strncmp libinterp/corefcn/strfns.cc
@anchor{XREFstrncmp}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn {} {@var{tf} =} strncmp (@var{str1}, @var{str2}, @var{n})
Return 1 if the first @var{n} characters of strings @var{str1} and @var{str2}
are the same, and 0 otherwise.

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

If either @var{str1} or @var{str2} 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 true if the character strings are equal, and false
otherwise.  This is just the opposite of the corresponding C library
function.  In addition Octave's strncmp function returns true if N = 0.

Matlab incompatibility : Octave's strncmp function produces an error if
N < 0, while @sc{matlab} treats N < 0 the same as N = 0, always returning
true.

@xseealso{@ref{XREFstrncmpi,,strncmpi}, @ref{XREFstrcmp,,strcmp}, @ref{XREFstrcmpi,,strcmpi}}
@end deftypefn


@c strcmpi libinterp/corefcn/strfns.cc
@anchor{XREFstrcmpi}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn {} {@var{tf} =} strcmpi (@var{str1}, @var{str2})
Return 1 if the character strings @var{str1} and @var{str2} are the same,
disregarding case of alphabetic characters, and 0 otherwise.

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

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

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


@c strncmpi libinterp/corefcn/strfns.cc
@anchor{XREFstrncmpi}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn {} {@var{tf} =} strncmpi (@var{str1}, @var{str2}, @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{str1} or @var{str2} 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 true if the character strings are equal, and false
otherwise.  This is just the opposite of the corresponding C library
function.  In addition Octave's strncmpi function returns true if N = 0.

Matlab incompatibility : Octave's strncmpi function produces an error if
N < 0, while @sc{matlab} treats N < 0 the same as N = 0, always returning
true.

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


Despite those comparison functions, there are more specialized function to
find the index position of a search pattern within a string.

@c startsWith scripts/strings/startsWith.m
@anchor{XREFstartsWith}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {@var{retval} =} startsWith (@var{str}, @var{pattern})
@deftypefnx {} {@var{retval} =} startsWith (@var{str}, @var{pattern}, "IgnoreCase", @var{ignore_case})
Check whether string(s) start with pattern(s).

Return an array of logical values that indicates which string(s) in the
input @var{str} (a single string or cell array of strings) begin with
the input @var{pattern} (a single string or cell array of strings).

If the value of the parameter @qcode{"IgnoreCase"} is true, then the
function will ignore the letter case of @var{str} and @var{pattern}.  By
default, the comparison is case sensitive.

Examples:

@example
@group
## one string and one pattern while considering case
startsWith ("hello", "he")
      @result{}  1
@end group

@group
## one string and one pattern while ignoring case
startsWith ("hello", "HE", "IgnoreCase", true)
      @result{}  1
@end group

@group
## multiple strings and multiple patterns while considering case
startsWith (@{"lab work.pptx", "data.txt", "foundations.ppt"@},
            @{"lab", "data"@})
      @result{}  1  1  0
@end group

@group
## multiple strings and one pattern while considering case
startsWith (@{"DATASHEET.ods", "data.txt", "foundations.ppt"@},
            "data", "IgnoreCase", false)
      @result{}  0  1  0
@end group

@group
## multiple strings and one pattern while ignoring case
startsWith (@{"DATASHEET.ods", "data.txt", "foundations.ppt"@},
            "data", "IgnoreCase", true)
      @result{}  1  1  0
@end group
@end example

@xseealso{@ref{XREFendsWith,,endsWith}, @ref{XREFregexp,,regexp}, @ref{XREFstrncmp,,strncmp}, @ref{XREFstrncmpi,,strncmpi}}
@end deftypefn


@c endsWith scripts/strings/endsWith.m
@anchor{XREFendsWith}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {@var{retval} =} endsWith (@var{str}, @var{pattern})
@deftypefnx {} {@var{retval} =} endsWith (@var{str}, @var{pattern}, "IgnoreCase", @var{ignore_case})
Check whether string(s) end with pattern(s).

Return an array of logical values that indicates which string(s) in the
input @var{str} (a single string or cell array of strings) end with
the input @var{pattern} (a single string or cell array of strings).

If the value of the parameter @qcode{"IgnoreCase"} is true, then the
function will ignore the letter case of @var{str} and @var{pattern}.  By
default, the comparison is case sensitive.

Examples:

@example
@group
## one string and one pattern while considering case
endsWith ("hello", "lo")
      @result{}  1
@end group

@group
## one string and one pattern while ignoring case
endsWith ("hello", "LO", "IgnoreCase", true)
      @result{}  1
@end group

@group
## multiple strings and multiple patterns while considering case
endsWith (@{"tests.txt", "mydoc.odt", "myFunc.m", "results.pptx"@},
          @{".docx", ".odt", ".txt"@})
      @result{}  1  1  0  0
@end group

@group
## multiple strings and one pattern while considering case
endsWith (@{"TESTS.TXT", "mydoc.odt", "result.txt", "myFunc.m"@},
          ".txt", "IgnoreCase", false)
      @result{}  0  0  1  0
@end group

@group
## multiple strings and one pattern while ignoring case
endsWith (@{"TESTS.TXT", "mydoc.odt", "result.txt", "myFunc.m"@},
          ".txt", "IgnoreCase", true)
      @result{}  1  0  1  0
@end group
@end example

@xseealso{@ref{XREFstartsWith,,startsWith}, @ref{XREFregexp,,regexp}, @ref{XREFstrncmp,,strncmp}, @ref{XREFstrncmpi,,strncmpi}}
@end deftypefn


@c findstr scripts/legacy/findstr.m
@anchor{XREFfindstr}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {@var{v} =} findstr (@var{s}, @var{t})
@deftypefnx {} {@var{v} =} findstr (@var{s}, @var{t}, @var{overlap})

This function is obsolete.  Use @code{strfind} instead.

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 (default), the returned
vector can include overlapping positions.  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 obsolete.  Use @code{strfind} in all new
code.
@xseealso{@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}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {@var{idx} =} strchr (@var{str}, @var{chars})
@deftypefnx {} {@var{idx} =} strchr (@var{str}, @var{chars}, @var{n})
@deftypefnx {} {@var{idx} =} strchr (@var{str}, @var{chars}, @var{n}, @var{direction})
@deftypefnx {} {[@var{i}, @var{j}] =} strchr (@dots{})
Search through 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 @code{regexp} in most cases.

@xseealso{@ref{XREFfind,,find}}
@end deftypefn


@c index scripts/strings/index.m
@anchor{XREFindex}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {@var{n} =} index (@var{s}, @var{t})
@deftypefnx {} {@var{n} =} 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.

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


@c rindex scripts/strings/rindex.m
@anchor{XREFrindex}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn {} {@var{n} =} 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"}.

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


@c unicode_idx libinterp/corefcn/strfns.cc
@anchor{XREFunicode_idx}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn {} {@var{idx} =} unicode_idx (@var{str})
Return an array with the indices for each UTF-8 encoded character in @var{str}.

@example
@group
unicode_idx ("aäbc")
     @result{} [1, 2, 2, 3, 4]
@end group
@end example

@end deftypefn


@c strfind libinterp/corefcn/strfind.cc
@anchor{XREFstrfind}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {@var{idx} =} strfind (@var{str}, @var{pattern})
@deftypefnx {} {@var{idx} =} strfind (@var{cellstr}, @var{pattern})
@deftypefnx {} {@var{idx} =} strfind (@dots{}, "overlaps", @var{val})
@deftypefnx {} {@var{idx} =} strfind (@dots{}, "forcecelloutput", @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}, or if @var{pattern} itself is empty, 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.

The optional argument @qcode{"forcecelloutput"} forces @var{idx} to be
returned as a cell array of vectors.  The default is false.

Examples:

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

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

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

             1   3   5

          [1,2] = [](1x0)
          [1,3] = [](1x0)
        @}
@end group

@group
strfind ("abababa", "aba", "forcecelloutput", true)
     @result{}
        @{
          [1,1] =

             1   3   5
        @}
@end group
@end example
@xseealso{@ref{XREFregexp,,regexp}, @ref{XREFregexpi,,regexpi}, @ref{XREFfind,,find}}
@end deftypefn


@c strmatch scripts/legacy/strmatch.m
@anchor{XREFstrmatch}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {@var{idx} =} strmatch (@var{s}, @var{A})
@deftypefnx {} {@var{idx} =} strmatch (@var{s}, @var{A}, "exact")

This function is obsolete.  @strong{Use an alternative} such as
@code{strncmp} or @code{strcmp} instead.

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 obsolete (and can produce incorrect
results in @sc{matlab} when used with cell arrays of strings.  Use
@code{strncmp} (normal case) or @code{strcmp} (@qcode{"exact"} case) in all
new code.  Other replacement possibilities, depending on application,
include @code{regexp} or @code{validatestring}.
@xseealso{@ref{XREFstrncmp,,strncmp}, @ref{XREFstrcmp,,strcmp}, @ref{XREFregexp,,regexp}, @ref{XREFstrfind,,strfind}, @ref{XREFvalidatestring,,validatestring}}
@end deftypefn


@node Searching and Replacing in Strings
@subsection Searching and Replacing in Strings

@c strrep libinterp/corefcn/strfind.cc
@anchor{XREFstrrep}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {@var{newstr} =} strrep (@var{str}, @var{ptn}, @var{rep})
@deftypefnx {} {@var{newstr} =} strrep (@var{cellstr}, @var{ptn}, @var{rep})
@deftypefnx {} {@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

@xseealso{@ref{XREFregexprep,,regexprep}, @ref{XREFstrfind,,strfind}}
@end deftypefn


@c erase scripts/strings/erase.m
@anchor{XREFerase}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn {} {@var{newstr} =} erase (@var{str}, @var{ptn})
Delete all occurrences of @var{ptn} within @var{str}.

@var{str} and @var{ptn} can be ordinary strings, cell array of strings, or
character arrays.

Examples

@example
@group
## string, single pattern
erase ("Hello World!", " World")
    @result{} "Hello!"

## cellstr, single pattern
erase (@{"Hello", "World!"@}, "World")
    @result{} @{"Hello", "!"@}

## string, multiple patterns
erase ("The Octave interpreter is fabulous", ...
       @{"interpreter ", "The "@})
    @result{} "Octave is fabulous"

## cellstr, multiple patterns
erase (@{"The ", "Octave interpreter ", "is fabulous"@}, ...
       @{"interpreter ", "The "@})
    @result{} @{"", "Octave ", "is fabulous"@}
@end group
@end example

Programming Note: @code{erase} deletes the first instance of a pattern in a
string when there are overlapping occurrences.  For example:

@example
@group
erase ("abababa", "aba")
    @result{} "b"
@end group
@end example

For processing overlaps, @pxref{XREFstrrep,,@code{strrep}}.

@xseealso{@ref{XREFstrrep,,strrep}, @ref{XREFregexprep,,regexprep}}
@end deftypefn


@c regexp libinterp/corefcn/regexp.cc
@anchor{XREFregexp}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {[@var{s}, @var{e}, @var{te}, @var{m}, @var{t}, @var{nm}, @var{sp}] =} regexp (@var{str}, @var{pat})
@deftypefnx {} {[@dots{}] =} regexp (@var{str}, @var{pat}, "@var{opt1}", @dots{})
Regular expression string matching.

Search for @var{pat} in UTF-8 encoded @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
@qcode{"["} and @qcode{"]"}.  If the first character is @qcode{"^"} 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}, escape sequences
in @var{pat} (e.g., @qcode{"@backslashchar{}n"} => newline) are expanded
even when @var{pat} has been defined with single quotes.  To disable
expansion use a second backslash before the escape sequence (e.g.,
"@backslashchar{}@backslashchar{}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

Stack Limitation Note: Pattern searches are done with a recursive function
which can overflow the program stack when there are a high number of matches.
For example,

@example
@code{regexp (repmat ('a', 1, 1e5), '(a)+')}
@end example

@noindent
may lead to a segfault.  As an alternative, consider constructing pattern
searches that reduce the number of matches (e.g., by creatively using set
complement), and then further processing the return variables (now reduced in
size) with successive @code{regexp} searches.

Octave's @code{regexp} implementation is based on the Perl Compatible
Regular Expressions library (@url{https://www.pcre.org/}).  For a more
comprehensive list of @code{regexp} operator syntax see the
@url{https://www.pcre.org/current/doc/html/pcre2syntax.html,,
"PCRE Syntax quick-reference summary"}.

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


@c regexpi libinterp/corefcn/regexp.cc
@anchor{XREFregexpi}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {[@var{s}, @var{e}, @var{te}, @var{m}, @var{t}, @var{nm}, @var{sp}] =} regexpi (@var{str}, @var{pat})
@deftypefnx {} {[@dots{}] =} regexpi (@var{str}, @var{pat}, "@var{opt1}", @dots{})

Case insensitive regular expression string matching.

Search for @var{pat} in UTF-8 encoded @var{str} and return the positions and
substrings of any matches, or empty values if there are none.
@xref{XREFregexp,,@code{regexp}}, for details on the syntax of the search
pattern.
@xseealso{@ref{XREFregexp,,regexp}}
@end deftypefn


@c regexprep libinterp/corefcn/regexp.cc
@anchor{XREFregexprep}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {@var{outstr} =} regexprep (@var{string}, @var{pat}, @var{repstr})
@deftypefnx {} {@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,,@code{regexp}}.

All strings must be UTF-8 encoded.

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 @qcode{"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}, escape sequences
in @var{pat} (e.g., @qcode{"@backslashchar{}n"} => newline) are expanded
even when @var{pat} has been defined with single quotes.  To disable
expansion use a second backslash before the escape sequence (e.g.,
"@backslashchar{}@backslashchar{}n") or use the @code{regexptranslate}
function.
@xseealso{@ref{XREFregexp,,regexp}, @ref{XREFregexpi,,regexpi}, @ref{XREFstrrep,,strrep}}
@end deftypefn


@c regexptranslate scripts/strings/regexptranslate.m
@anchor{XREFregexptranslate}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn {} {@var{str} =} 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
@xseealso{@ref{XREFregexp,,regexp}, @ref{XREFregexpi,,regexpi}, @ref{XREFregexprep,,regexprep}}
@end deftypefn


@node Converting Strings
@section Converting Strings

Octave offers several kinds of conversion functions for Strings.

@menu
* String encoding::
* Numerical Data and Strings::
* JSON data encoding/decoding::
@end menu

@node String encoding
@subsection String encoding

@c unicode2native scripts/strings/unicode2native.m
@anchor{XREFunicode2native}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {@var{native_bytes} =} unicode2native (@var{utf8_str}, @var{codepage})
@deftypefnx {} {@var{native_bytes} =} unicode2native (@var{utf8_str})
Convert UTF-8 string @var{utf8_str} to byte stream using @var{codepage}.

The character vector @var{utf8_str} is converted to a byte stream
@var{native_bytes} using the code page given by @var{codepage}.  The
string @var{codepage} must be an identifier of a valid code page.
Examples for valid code pages are @qcode{"ISO-8859-1"},
@qcode{"Shift-JIS"}, or @qcode{"UTF-16"}.  For a list of supported code
pages, see @url{https://www.gnu.org/software/libiconv}.  If @var{codepage}
is omitted or empty, the system default codepage is used.

If any of the characters cannot be mapped into the codepage @var{codepage},
they are replaced with the appropriate substitution sequence for that
codepage.

@xseealso{@ref{XREFnative2unicode,,native2unicode}}
@end deftypefn


@c native2unicode scripts/strings/native2unicode.m
@anchor{XREFnative2unicode}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {@var{utf8_str} =} native2unicode (@var{native_bytes}, @var{codepage})
@deftypefnx {} {@var{utf8_str} =} native2unicode (@var{native_bytes})
Convert byte stream @var{native_bytes} to UTF-8 using @var{codepage}.

The numbers in the vector @var{native_bytes} are rounded and clipped to
integers between 0 and 255.  This byte stream is then mapped into the
code page given by the string @var{codepage} and returned in the string
@var{utf8_str}.  Octave uses UTF-8 as its internal encoding.  The string
@var{codepage} must be an identifier of a valid code page.  Examples for
valid code pages are @qcode{"ISO-8859-1"}, @qcode{"Shift-JIS"}, or
@qcode{"UTF-16"}.  For a list of supported code pages, see
@url{https://www.gnu.org/software/libiconv}.  If @var{codepage} is omitted
or empty, the system default codepage is used.

If @var{native_bytes} is a string vector, it is returned as is.

@xseealso{@ref{XREFunicode2native,,unicode2native}}
@end deftypefn


@node Numerical Data and Strings
@subsection Numerical Data and Strings

Apart from the string concatenation functions (@pxref{Concatenating Strings})
which cast numerical data to the corresponding UTF-8 encoded 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}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {@var{s} =} mat2str (@var{x}, @var{n})
@deftypefnx {} {@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

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


@c num2str scripts/general/num2str.m
@anchor{XREFnum2str}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {@var{str} =} num2str (@var{x})
@deftypefnx {} {@var{str} =} num2str (@var{x}, @var{precision})
@deftypefnx {} {@var{str} =} 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 process complex numbers.

Examples:

@example
num2str (123.456)
  @result{} 123.456

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{} Variables in the current scope:
        Attr Name        Size                     Bytes  Class
        ==== ====        ====                     =====  =====
             s           2x8                         16  char
     Total is 16 elements using 16 bytes

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

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

Programming Notes:

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

Integers larger than @code{flintmax} may not be displayed correctly.

For complex @var{x}, the format string may only contain one output
conversion specification and nothing else.  Otherwise, results will be
unpredictable.

Any optional @var{format} specified by the programmer is used without
modification.  This is in contrast to @sc{matlab} which tampers with the
@var{format} based on internal heuristics.
@xseealso{@ref{XREFsprintf,,sprintf}, @ref{XREFint2str,,int2str}, @ref{XREFmat2str,,mat2str}}
@end deftypefn


@c int2str scripts/general/int2str.m
@anchor{XREFint2str}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn {} {@var{str} =} 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{} Variables in the current scope:
        Attr Name        Size                     Bytes  Class
        ==== ====        ====                     =====  =====
             s           2x7                         14  char
     Total is 14 elements using 14 bytes
@end group
@end example

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

Programming Notes:

Non-integers are rounded to integers before display.  Only the real part
of complex numbers is displayed.

@xseealso{@ref{XREFsprintf,,sprintf}, @ref{XREFnum2str,,num2str}, @ref{XREFmat2str,,mat2str}}
@end deftypefn


@c str2double libinterp/corefcn/strfns.cc
@anchor{XREFstr2double}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn {} {@var{d} =} str2double (@var{str})
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{str} 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{str} 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.

Programming Note: @code{str2double} can replace @code{str2num}, is more
efficient, and avoids the security risk of using @code{eval} on unknown data.
@xseealso{@ref{XREFstr2num,,str2num}}
@end deftypefn


@c str2num scripts/strings/str2num.m
@anchor{XREFstr2num}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {@var{x} =} str2num (@var{s})
@deftypefnx {} {[@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}.
@xseealso{@ref{XREFstr2double,,str2double}, @ref{XREFeval,,eval}}
@end deftypefn


@c bin2dec scripts/strings/bin2dec.m
@anchor{XREFbin2dec}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn {} {@var{d} =} bin2dec (@var{str})
Return the decimal number corresponding to the binary number represented
by the string @var{str}.

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{str} is a string matrix, return a column vector with one converted
number per row of @var{str}; Invalid rows evaluate to NaN@.

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


@c dec2bin scripts/strings/dec2bin.m
@anchor{XREFdec2bin}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {@var{bstr} =} dec2bin (@var{d})
@deftypefnx {} {@var{bstr} =} dec2bin (@var{d}, @var{len})
Return a string of ones and zeros representing the conversion of the integer
@var{d} to a binary number.

If @var{d} is a matrix or cell array, return a string matrix with one row
for each 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.

For negative elements of @var{d}, return the binary value of the two's
complement.  The result is padded with leading ones to 8, 16, 32, or 64
bits as appropriate for the magnitude of the input.  Positive input
elements are padded with leading zeros to the same width.

Examples:

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

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

Programming tip: @code{dec2bin} discards any fractional part of the input.
If you need the fractional part to be converted too, call @code{dec2base}
with a nonzero number of decimal places.  You can also use @code{fix} or
@code{round} on fractional inputs to ensure predictable rounding behavior.

@xseealso{@ref{XREFbin2dec,,bin2dec}, @ref{XREFdec2base,,dec2base}, @ref{XREFdec2hex,,dec2hex}}
@end deftypefn


@c dec2hex scripts/strings/dec2hex.m
@anchor{XREFdec2hex}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {@var{hstr} =} dec2hex (@var{d})
@deftypefnx {} {@var{hstr} =} dec2hex (@var{d}, @var{len})
Return a string representing the conversion of the integer @var{d} to a
hexadecimal (base16) number.

If @var{d} is negative, return the hexadecimal complement of @var{d}.

If @var{d} is a matrix or cell array, return a string matrix with one row
for each 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.

Examples:

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

dec2hex (-2)
     @result{} "FE"
@end group
@end example

Programming tip: @code{dec2hex} discards any fractional part of the input.
If you need the fractional part to be converted too, call @code{dec2base}
with a nonzero number of decimal places.  You can also use @code{fix} or
@code{round} on fractional inputs to ensure predictable rounding behavior.

@xseealso{@ref{XREFhex2dec,,hex2dec}, @ref{XREFdec2base,,dec2base}, @ref{XREFdec2bin,,dec2bin}}
@end deftypefn


@c hex2dec scripts/strings/hex2dec.m
@anchor{XREFhex2dec}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn {} {@var{d} =} hex2dec (@var{str})
Return the integer corresponding to the hexadecimal number represented by
the string @var{str}.

For example:

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

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

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

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


@c dec2base scripts/strings/dec2base.m
@anchor{XREFdec2base}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {@var{str} =} dec2base (@var{d}, @var{base})
@deftypefnx {} {@var{str} =} dec2base (@var{d}, @var{base}, @var{len})
@deftypefnx {} {@var{str} =} dec2base (@var{d}, @var{base}, @var{len}, @var{decimals})
Return a string of symbols in base @var{base} corresponding to the
value @var{d}.

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

If @var{d} is negative, then the result will represent @var{d} in complement
notation.  For example, negative binary numbers are in twos-complement, and
analogously for other bases.

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}.  Whitespace (spaces, tabs, newlines,
, etc.@:) 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 integer part of the result.  If this is omitted, then
@code{dec2base} uses enough digits to accommodate the input.

The optional fourth argument, @var{decimals}, specifies the number of
digits to represent the fractional part of the input.  If this is omitted,
then it is set to zero, and @code{dec2base} returns an integer output for
backward compatibility.

@example
@group
dec2base (100*pi, 16)
@result{} "13A"
dec2base (100*pi, 16, 4)
@result{} "013A"
dec2base (100*pi, 16, 4, 6)
@result{} "013A.28C59D"
dec2base (-100*pi, 16)
@result{} "EC6"
dec2base (-100*pi, 16, 4)
@result{} "FEC6"
dec2base (-100*pi, 16, 4, 6)
@result{} "FEC5.D73A63"
@end group
@end example

Programming tip: When passing negative inputs to @code{dec2base}, it is
best to explicitly specify the length of the output required.

@xseealso{@ref{XREFbase2dec,,base2dec}, @ref{XREFdec2bin,,dec2bin}, @ref{XREFdec2hex,,dec2hex}}
@end deftypefn


@c base2dec scripts/strings/base2dec.m
@anchor{XREFbase2dec}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn {} {@var{d} =} base2dec (@var{str}, @var{base})
Convert @var{str} 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{str} is a string matrix, return a column vector with one value per
row of @var{str}.  If a row contains invalid symbols then the corresponding
value will be NaN@.

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

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

@example
@group
base2dec ("yyyzx", "xyz")
   @result{} 123
@end group
@end example
@xseealso{@ref{XREFdec2base,,dec2base}, @ref{XREFbin2dec,,bin2dec}, @ref{XREFhex2dec,,hex2dec}}
@end deftypefn


@c num2hex libinterp/corefcn/hex2num.cc
@anchor{XREFnum2hex}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {@var{s} =} num2hex (@var{n})
@deftypefnx {} {@var{s} =} num2hex (@var{n}, "cell")
Convert a numeric array to an array of hexadecimal strings.

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

With the optional second argument @qcode{"cell"}, return a cell array of
strings instead of a character array.
@xseealso{@ref{XREFhex2num,,hex2num}, @ref{XREFhex2dec,,hex2dec}, @ref{XREFdec2hex,,dec2hex}}
@end deftypefn


@c hex2num libinterp/corefcn/hex2num.cc
@anchor{XREFhex2num}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {@var{n} =} hex2num (@var{s})
@deftypefnx {} {@var{n} =} hex2num (@var{s}, @var{class})
Typecast a hexadecimal character array or cell array of strings to an
array of numbers.

By default, the input array is interpreted as a hexadecimal number
representing a double precision value.  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 second argument @var{class} may be used to cause the input
array to be interpreted as a different value type.  Possible values are

@multitable {@qcode{"uint64"}} {Characters}
@headitem Option @tab Characters
@item @qcode{"int8"} @tab 2
@item @qcode{"uint8"} @tab 2
@item @qcode{"int16"} @tab 4
@item @qcode{"uint16"} @tab 4
@item @qcode{"int32"} @tab 8
@item @qcode{"uint32"} @tab 8
@item @qcode{"int64"} @tab 16
@item @qcode{"uint64"} @tab 16
@item @qcode{"char"} @tab 2
@item @qcode{"single"} @tab 8
@item @qcode{"double"} @tab 16
@end multitable

For example:

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


@c strread scripts/legacy/strread.m
@anchor{XREFstrread}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {[@var{a}, @dots{}] =} strread (@var{str})
@deftypefnx {} {[@var{a}, @dots{}] =} strread (@var{str}, @var{format})
@deftypefnx {} {[@var{a}, @dots{}] =} strread (@var{str}, @var{format}, @var{format_repeat})
@deftypefnx {} {[@var{a}, @dots{}] =} strread (@var{str}, @var{format}, @var{prop1}, @var{value1}, @dots{})
@deftypefnx {} {[@var{a}, @dots{}] =} strread (@var{str}, @var{format}, @var{format_repeat}, @var{prop1}, @var{value1}, @dots{})

This function is obsolete.  Use @code{textscan} instead.

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  %*
@itemx %*f
@itemx %*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).  Note that whitespace is implicitly added
to the set of delimiter characters unless a @qcode{"%s"} format conversion
specifier is supplied; see @qcode{"whitespace"} parameter below.  The set
of delimiter characters cannot be empty; if needed Octave substitutes a
space as delimiter.

@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 @qcode{"@backslashchar{}t"}.  In
each data field, multiple consecutive whitespace characters are collapsed
into one space and leading and trailing whitespace is removed.  The default
value for whitespace is
@c Note: the next line specifically has a newline which generates a space
@c       in the output of qcode, but keeps the next line < 80 characters.
@qcode{"
@backslashchar{}b@backslashchar{}r@backslashchar{}n@backslashchar{}t"}
(note the space).  Whitespace is always added to the set of delimiter
characters unless at least one @qcode{"%s"} format conversion specifier is
supplied; in that case only whitespace explicitly specified in
@qcode{"delimiter"} is retained as delimiter and removed from the set of
whitespace characters.  If whitespace characters are to be kept as-is (in
e.g., strings), specify an empty value (i.e., @qcode{""}) for
@qcode{"whitespace"}; obviously, whitespace cannot be a delimiter then.

@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{"@backslashchar{}n"}
Data columns are padded with empty fields or NaN so that all columns have
equal length

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

@end table

@xseealso{@ref{XREFtextscan,,textscan}, @ref{XREFsscanf,,sscanf}}
@end deftypefn


@node JSON data encoding/decoding
@subsection JSON data encoding/decoding

JavaScript Object Notation, in short JSON, is a very common human readable
and structured data format.  GNU Octave supports encoding and decoding this
format with the following two functions.

@c jsonencode libinterp/corefcn/jsonencode.cc
@anchor{XREFjsonencode}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {@var{JSON_txt} =} jsonencode (@var{object})
@deftypefnx {} {@var{JSON_txt} =} jsonencode (@dots{}, "ConvertInfAndNaN", @var{TF})
@deftypefnx {} {@var{JSON_txt} =} jsonencode (@dots{}, "PrettyPrint", @var{TF})

Encode Octave data types into JSON text.

The input @var{object} is an Octave variable to encode.

The output @var{JSON_txt} is the JSON text that contains the result of encoding
@var{object}.

If the value of the option @qcode{"ConvertInfAndNaN"} is true then @code{NaN},
@code{NA}, @code{-Inf}, and @code{Inf} values will be converted to
@qcode{"null"} in the output.  If it is false then they will remain as their
original values.  The default value for this option is true.

If the value of the option @qcode{"PrettyPrint"} is true, the output text will
have indentations and line feeds.  If it is false, the output will be condensed
and written without whitespace.  The default value for this option is false.

Programming Notes:

@itemize @bullet
@item
Complex numbers are not supported.

@item
classdef objects are first converted to structs and then encoded.

@item
To preserve escape characters (e.g., @qcode{"@backslashchar{}n"}), use
single-quoted strings.

@item
Every character after the null character (@qcode{"@backslashchar{}0"}) in a
double-quoted string will be dropped during encoding.

@item
Encoding and decoding an array is not guaranteed to preserve the dimensions
of the array.  In particular, row vectors will be reshaped to column vectors.

@item
Encoding and decoding is not guaranteed to preserve the Octave data type
because JSON supports fewer data types than Octave.  For example, if you
encode an @code{int8} and then decode it, you will get a @code{double}.
@end itemize

This table shows the conversions from Octave data types to JSON data types:

@multitable @columnfractions 0.50 0.50
@headitem Octave data type @tab JSON data type
@item logical scalar @tab Boolean
@item logical vector @tab Array of Boolean, reshaped to row vector
@item logical array  @tab nested Array of Boolean
@item numeric scalar @tab Number
@item numeric vector @tab Array of Number, reshaped to row vector
@item numeric array  @tab nested Array of Number
@item @code{NaN}, @code{NA}, @code{Inf}, @code{-Inf}@*
when @qcode{"ConvertInfAndNaN" = true} @tab @qcode{"null"}
@item @code{NaN}, @code{NA}, @code{Inf}, @code{-Inf}@*
when @qcode{"ConvertInfAndNaN" = false} @tab @qcode{"NaN"}, @qcode{"NaN"},
@qcode{"Infinity"}, @qcode{"-Infinity"}
@item empty array    @tab @qcode{"[]"}
@item character vector @tab String
@item character array @tab Array of String
@item empty character array @tab @qcode{""}
@item cell scalar @tab Array
@item cell vector @tab Array, reshaped to row vector
@item cell array @tab Array, flattened to row vector
@item struct scalar @tab Object
@item struct vector @tab Array of Object, reshaped to row vector
@item struct array  @tab nested Array of Object
@item classdef object @tab Object
@end multitable

Examples:

@smallexample
@group
jsonencode ([1, NaN; 3, 4])
@result{} [[1,null],[3,4]]
@end group

@group
jsonencode ([1, NaN; 3, 4], "ConvertInfAndNaN", false)
@result{} [[1,NaN],[3,4]]
@end group

@group
## Escape characters inside a single-quoted string
jsonencode ('\0\a\b\t\n\v\f\r')
@result{} "\\0\\a\\b\\t\\n\\v\\f\\r"
@end group

@group
## Escape characters inside a double-quoted string
jsonencode ("\a\b\t\n\v\f\r")
@result{} "\u0007\b\t\n\u000B\f\r"
@end group

@group
jsonencode ([true; false], "PrettyPrint", true)
@result{} ans = [
     true,
     false
   ]
@end group

@group
jsonencode (['foo', 'bar'; 'foo', 'bar'])
@result{} ["foobar","foobar"]
@end group

@group
jsonencode (struct ('a', Inf, 'b', [], 'c', struct ()))
@result{} @{"a":null,"b":[],"c":@{@}@}
@end group

@group
jsonencode (struct ('structarray', struct ('a', @{1; 3@}, 'b', @{2; 4@})))
@result{} @{"structarray":[@{"a":1,"b":2@},@{"a":3,"b":4@}]@}
@end group

@group
jsonencode (@{'foo'; 'bar'; @{'foo'; 'bar'@}@})
@result{} ["foo","bar",["foo","bar"]]
@end group

@group
jsonencode (containers.Map(@{'foo'; 'bar'; 'baz'@}, [1, 2, 3]))
@result{} @{"bar":2,"baz":3,"foo":1@}
@end group
@end smallexample

@xseealso{@ref{XREFjsondecode,,jsondecode}}
@end deftypefn


@c jsondecode libinterp/corefcn/jsondecode.cc
@anchor{XREFjsondecode}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {@var{object} =} jsondecode (@var{JSON_txt})
@deftypefnx {} {@var{object} =} jsondecode (@dots{}, "ReplacementStyle", @var{rs})
@deftypefnx {} {@var{object} =} jsondecode (@dots{}, "Prefix", @var{pfx})
@deftypefnx {} {@var{object} =} jsondecode (@dots{}, "makeValidName", @var{TF})

Decode text that is formatted in JSON.

The input @var{JSON_txt} is a string that contains JSON text.

The output @var{object} is an Octave object that contains the result of
decoding @var{JSON_txt}.

For more information about the options @qcode{"ReplacementStyle"} and
@qcode{"Prefix"},
@pxref{XREFmatlab_lang_makeValidName,,@code{matlab.lang.makeValidName}}.

If the value of the option @qcode{"makeValidName"} is false then names
will not be changed by @code{matlab.lang.makeValidName} and the
@qcode{"ReplacementStyle"} and @qcode{"Prefix"} options will be ignored.

NOTE: Decoding and encoding JSON text is not guaranteed to reproduce the
original text as some names may be changed by @code{matlab.lang.makeValidName}.

This table shows the conversions from JSON data types to Octave data types:

@multitable @columnfractions 0.50 0.50
@headitem JSON data type @tab Octave data type
@item Boolean @tab scalar logical
@item Number @tab scalar double
@item String @tab vector of characters
@item Object @tab scalar struct (field names of the struct may be different from the keys of the JSON object due to @code{matlab_lang_makeValidName}
@item null, inside a numeric array @tab @code{NaN}
@item null, inside a non-numeric array @tab empty double array @code{[]}
@item Array, of different data types @tab cell array
@item Array, of Booleans @tab logical array
@item Array, of Numbers @tab double array
@item Array, of Strings @tab cell array of character vectors (@code{cellstr})
@item Array of Objects, same field names @tab struct array
@item Array of Objects, different field names @tab cell array of scalar structs
@end multitable

Examples:

@example
@group
jsondecode ('[1, 2, null, 3]')
    @result{} ans =

      1
      2
    NaN
      3
@end group

@group
jsondecode ('["foo", "bar", ["foo", "bar"]]')
    @result{} ans =
       @{
         [1,1] = foo
         [2,1] = bar
         [3,1] =
         @{
           [1,1] = foo
           [2,1] = bar
         @}

       @}
@end group

@group
jsondecode ('@{"nu#m#ber": 7, "s#tr#ing": "hi"@}', ...
            'ReplacementStyle', 'delete')
    @result{} scalar structure containing the fields:

         number = 7
         string = hi
@end group

@group
jsondecode ('@{"nu#m#ber": 7, "s#tr#ing": "hi"@}', ...
            'makeValidName', false)
    @result{} scalar structure containing the fields:

         nu#m#ber = 7
         s#tr#ing = hi
@end group

@group
jsondecode ('@{"1": "one", "2": "two"@}', 'Prefix', 'm_')
    @result{} scalar structure containing the fields:

         m_1 = one
         m_2 = two
@end group
@end example

@xseealso{@ref{XREFjsonencode,,jsonencode}, @ref{XREFmatlab_lang_makeValidName,,matlab.lang.makeValidName}}
@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}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn {} {@var{tf} =} 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})}).
@xseealso{@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}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn {} {@var{tf} =} 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})}).
@xseealso{@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}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn {} {@var{tf} =} 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.
@xseealso{@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}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn {} {@var{tf} =} 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.
@xseealso{@ref{XREFisupper,,isupper}, @ref{XREFisalpha,,isalpha}, @ref{XREFisletter,,isletter}, @ref{XREFisalnum,,isalnum}}
@end deftypefn


@c isupper libinterp/corefcn/mappers.cc
@anchor{XREFisupper}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn {} {@var{tf} =} 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.
@xseealso{@ref{XREFislower,,islower}, @ref{XREFisalpha,,isalpha}, @ref{XREFisletter,,isletter}, @ref{XREFisalnum,,isalnum}}
@end deftypefn


@c isdigit libinterp/corefcn/mappers.cc
@anchor{XREFisdigit}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn {} {@var{tf} =} 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.
@xseealso{@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}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn {} {@var{tf} =} 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}).
@xseealso{@ref{XREFisdigit,,isdigit}}
@end deftypefn


@c ispunct libinterp/corefcn/mappers.cc
@anchor{XREFispunct}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn {} {@var{tf} =} 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.
@xseealso{@ref{XREFisalpha,,isalpha}, @ref{XREFisdigit,,isdigit}, @ref{XREFisspace,,isspace}, @ref{XREFiscntrl,,iscntrl}}
@end deftypefn


@c isspace libinterp/corefcn/mappers.cc
@anchor{XREFisspace}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn {} {@var{tf} =} 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.
@xseealso{@ref{XREFiscntrl,,iscntrl}, @ref{XREFispunct,,ispunct}, @ref{XREFisalpha,,isalpha}, @ref{XREFisdigit,,isdigit}}
@end deftypefn


@c iscntrl libinterp/corefcn/mappers.cc
@anchor{XREFiscntrl}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn {} {@var{tf} =} 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.
@xseealso{@ref{XREFispunct,,ispunct}, @ref{XREFisspace,,isspace}, @ref{XREFisalpha,,isalpha}, @ref{XREFisdigit,,isdigit}}
@end deftypefn


@c isgraph libinterp/corefcn/mappers.cc
@anchor{XREFisgraph}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn {} {@var{tf} =} 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.
@xseealso{@ref{XREFisprint,,isprint}}
@end deftypefn


@c isprint libinterp/corefcn/mappers.cc
@anchor{XREFisprint}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn {} {@var{tf} =} 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.
@xseealso{@ref{XREFisgraph,,isgraph}}
@end deftypefn


@c isascii libinterp/corefcn/mappers.cc
@anchor{XREFisascii}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn {} {@var{tf} =} 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}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {@var{tf} =} isstrprop (@var{str}, @var{prop})
@deftypefnx {} {@var{tf} =} isstrprop (@var{str}, @var{prop}, 'ForceCellOutput', @var{flag})
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  @nospell{@qcode{"alnum"}}
@itemx @nospell{@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 @nospell{@qcode{"xdigit"}}
True for hexadecimal digits (@nospell{a-fA-F0-9}).

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

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

@item @nospell{@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

If the option @nospell{@qcode{'ForceCellOutput'}} is given and @var{flag} is
true then a cell value is returned rather than a logical array.

@xseealso{@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