@c Copyright (C) 1996, 1997, 1999, 2000, 2002, 2003, 2004, 2005,
@c               2006, 2007 John W. Eaton
@c
@c This file is part of Octave.
@c
@c Octave is free software; you can redistribute it and/or modify it
@c under the terms of the GNU General Public License as published by the
@c Free Software Foundation; either version 3 of the License, or (at
@c your option) any later version.
@c 
@c Octave is distributed in the hope that it will be useful, but WITHOUT
@c ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
@c FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
@c for more details.
@c 
@c You should have received a copy of the GNU General Public License
@c along with Octave; see the file COPYING.  If not, see
@c <http://www.gnu.org/licenses/>.

@node Strings
@chapter Strings
@cindex strings
@cindex character strings
@opindex "
@opindex '

A @dfn{string constant} consists of a sequence of characters enclosed in
either double-quote or single-quote marks.  For example, both of the
following expressions

@example
@group
"parrot"
'parrot'
@end group
@end example

@noindent
represent the string whose contents are @samp{parrot}.  Strings in
Octave can be of any length.

Since the single-quote mark is also used for the transpose operator
(@pxref{Arithmetic Ops}) but double-quote marks have no other purpose in Octave,
it is best to use double-quote marks to denote strings.

Strings can be concatenated using the notation for defining matrices.  For
example, the expression 
 
@example
[ "foo" , "bar" , "baz" ]
@end example

@noindent
produces the string whose contents are @samp{foobarbaz}.  @xref{Numeric Data
Types}, for more information about creating matrices.

@menu
* Escape Sequences in string constants::
* Character Arrays::
* Creating Strings:: 
* Comparing Strings::           
* Manipulating Strings::     
* String Conversions::          
* Character Class Functions::   
@end menu

@node Escape Sequences in string constants
@section Escape Sequences in string constants
@cindex escape sequence notation
In double-quoted strings, the backslash character is used to introduce
@dfn{escape sequences} that represent other characters.  For example,
@samp{\n} embeds a newline character in a double-quoted string and
@samp{\"} embeds a double quote character.  In single-quoted strings, backslash
is not a special character.  Here is an example showing the difference:

@example
@group
toascii ("\n")
    @result{} 10
toascii ('\n')
    @result{} [ 92 110 ]
@end group
@end example

Here is a table of all the escape sequences used in Octave (within
double quoted strings).  They are the same as those used in the C 
programming language.

@table @code
@item \\
Represents a literal backslash, @samp{\}.

@item \"
Represents a literal double-quote character, @samp{"}.

@item \'
Represents a literal single-quote character, @samp{'}.

@item \0
Represents the ``nul'' character, control-@@, ASCII code 0.

@item \a
Represents the ``alert'' character, control-g, ASCII code 7.

@item \b
Represents a backspace, control-h, ASCII code 8.

@item \f
Represents a formfeed, control-l, ASCII code 12.

@item \n
Represents a newline, control-j, ASCII code 10.

@item \r
Represents a carriage return, control-m, ASCII code 13.

@item \t
Represents a horizontal tab, control-i, ASCII code 9.

@item \v
Represents a vertical tab, control-k, ASCII code 11.

@c We don't do octal or hex this way yet.
@c
@c @item \@var{nnn}
@c Represents the octal value @var{nnn}, where @var{nnn} are one to three
@c digits between 0 and 7.  For example, the code for the ASCII ESC
@c (escape) character is @samp{\033}.@refill
@c 
@c @item \x@var{hh}@dots{}
@c Represents the hexadecimal value @var{hh}, where @var{hh} are hexadecimal
@c digits (@samp{0} through @samp{9} and either @samp{A} through @samp{F} or
@c @samp{a} through @samp{f}).  Like the same construct in @sc{ansi} C,
@c the escape 
@c sequence continues until the first non-hexadecimal digit is seen.  However,
@c using more than two hexadecimal digits produces undefined results.  (The
@c @samp{\x} escape sequence is not allowed in @sc{posix} @code{awk}.)@refill
@end table

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

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


@node Character Arrays
@section Character Arrays

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

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

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

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

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

One relevant question is, what happens when a character matrix is
created from strings of different length.  The answer is that Octave
puts blank characters at the end of strings shorter than the longest
string.  It is possible to use a different character than the
blank character using the @code{string_fill_char} function.

@DOCSTRING(string_fill_char)

This shows a problem with character matrices.  It simply isn't possible to
represent strings of different lengths.  The solution is to use a cell array of
strings, which is described in @ref{Cell Arrays of Strings}.

@node Creating Strings
@section Creating Strings

The easiest way to create a string is, as illustrated in the introduction,
to enclose a text in double-quotes or single-quotes.  It is however
possible to create a string without actually writing a text.  The
function @code{blanks} creates a string of a given length consisting
only of blank characters (ASCII code 32).

@DOCSTRING(blanks)

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

@node Concatenating Strings
@subsection Concatenating Strings

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

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

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

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

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

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

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

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

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

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

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

       blue 
@end group

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

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

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

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

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

@DOCSTRING(char)

@DOCSTRING(strvcat)

@DOCSTRING(strcat)

@DOCSTRING(cstrcat)

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

@DOCSTRING(mat2str)

@DOCSTRING(num2str)

@DOCSTRING(int2str)

@node Comparing Strings
@section Comparing Strings

Since a string is a character array comparison between strings works
element by element as the following example shows.

@example
GNU = "GNU's Not UNIX";
spaces = (GNU == " ")
     @result{} spaces =
       0   0   0   0   0   1   0   0   0   1   0   0   0   0
@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
sensistive.  @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)

@DOCSTRING(validatestring)

@node Manipulating Strings
@section Manipulating Strings

Octave supports a wide range of functions for manipulating strings.
Since a string is just a matrix, simple manipulations can be accomplished
using standard operators. The following example shows how to replace
all blank characters with underscores.

@example
quote = ...
  "First things first, but not necessarily in that order";
quote( quote == " " ) = "_"
@result{} quote = 
    First_things_first,_but_not_necessarily_in_that_order
@end example

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

@DOCSTRING(deblank)

@DOCSTRING(strtrim)

@DOCSTRING(strtrunc)

@DOCSTRING(findstr)

@DOCSTRING(strchr)

@DOCSTRING(index)

@DOCSTRING(rindex)

@DOCSTRING(strfind)

@DOCSTRING(strmatch)

@DOCSTRING(strtok)

@DOCSTRING(split)

@DOCSTRING(strrep)

@DOCSTRING(substr)

@DOCSTRING(regexp)

@DOCSTRING(regexpi)

@DOCSTRING(regexprep)

@DOCSTRING(regexptranslate)

@node String Conversions
@section String Conversions

Octave supports various kinds of conversions between strings and
numbers.  As an example, it is possible to convert a string containing
a hexadecimal number to a floating point number.

@example
hex2dec ("FF")
     @result{} ans = 255
@end example

@DOCSTRING(bin2dec)

@DOCSTRING(dec2bin)

@DOCSTRING(dec2hex)

@DOCSTRING(hex2dec)

@DOCSTRING(dec2base)

@DOCSTRING(base2dec)

@DOCSTRING(num2hex)

@DOCSTRING(hex2num)

@DOCSTRING(str2double)

@DOCSTRING(strjust)

@DOCSTRING(str2num)

@DOCSTRING(toascii)

@DOCSTRING(tolower)

@DOCSTRING(toupper)

@DOCSTRING(do_string_escapes)

@DOCSTRING(undo_string_escapes)

@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(isascii)

@DOCSTRING(iscntrl)

@DOCSTRING(isdigit)

@DOCSTRING(isgraph)

@DOCSTRING(isletter)

@DOCSTRING(islower)

@DOCSTRING(isprint)

@DOCSTRING(ispunct)

@DOCSTRING(isspace)

@DOCSTRING(isupper)

@DOCSTRING(isxdigit)

@DOCSTRING(isstrprop)