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

@DOCSTRING(blanks)

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

@DOCSTRING(is_dq_string)

@DOCSTRING(is_sq_string)

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

@DOCSTRING(ischar)

@DOCSTRING(isstring)

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.

@DOCSTRING(string_fill_char)

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

@DOCSTRING(strjust)

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.

@DOCSTRING(tolower)

@DOCSTRING(toupper)

@DOCSTRING(deblank)

@DOCSTRING(strtrim)

@DOCSTRING(strtrunc)

@DOCSTRING(untabify)

@DOCSTRING(do_string_escapes)

@DOCSTRING(undo_string_escapes)

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

@DOCSTRING(newline)

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

@DOCSTRING(char)

@DOCSTRING(strvcat)

@DOCSTRING(strcat)

@DOCSTRING(cstrcat)

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

@DOCSTRING(substr)

@DOCSTRING(strtok)

@DOCSTRING(strsplit)

@DOCSTRING(ostrsplit)

@DOCSTRING(strjoin)

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

@DOCSTRING(strcmp)

@DOCSTRING(strncmp)

@DOCSTRING(strcmpi)

@DOCSTRING(strncmpi)

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

@DOCSTRING(startsWith)

@DOCSTRING(endsWith)

@DOCSTRING(findstr)

@DOCSTRING(strchr)

@DOCSTRING(index)

@DOCSTRING(rindex)

@DOCSTRING(unicode_idx)

@DOCSTRING(strfind)

@DOCSTRING(strmatch)

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

@DOCSTRING(strrep)

@DOCSTRING(erase)

@DOCSTRING(regexp)

@DOCSTRING(regexpi)

@DOCSTRING(regexprep)

@DOCSTRING(regexptranslate)

@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

@DOCSTRING(unicode2native)

@DOCSTRING(native2unicode)

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

@DOCSTRING(mat2str)

@DOCSTRING(num2str)

@DOCSTRING(int2str)

@DOCSTRING(str2double)

@DOCSTRING(str2num)

@DOCSTRING(bin2dec)

@DOCSTRING(dec2bin)

@DOCSTRING(dec2hex)

@DOCSTRING(hex2dec)

@DOCSTRING(dec2base)

@DOCSTRING(base2dec)

@DOCSTRING(num2hex)

@DOCSTRING(hex2num)

@DOCSTRING(strread)

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

@DOCSTRING(jsonencode)

@DOCSTRING(jsondecode)

@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

@DOCSTRING(isalnum)

@DOCSTRING(isalpha)

@DOCSTRING(isletter)

@DOCSTRING(islower)

@DOCSTRING(isupper)

@DOCSTRING(isdigit)

@DOCSTRING(isxdigit)

@DOCSTRING(ispunct)

@DOCSTRING(isspace)

@DOCSTRING(iscntrl)

@DOCSTRING(isgraph)

@DOCSTRING(isprint)

@DOCSTRING(isascii)

@DOCSTRING(isstrprop)