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

@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

You may also insert a single quote character in a single-quoted string
by using two single quote characters in succession.  For example,

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

Here is a table of all the escape sequences used in Octave.  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

Strings may 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
* Creating Strings:: 
* Comparing Strings::           
* Manipulating Strings::     
* String Conversions::          
* Character Class Functions::   
@end menu

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

The string representation used by Octave is an array of characters, so
the result of @code{blanks(10)} is actually a row vector of length 10
containing the value 32 in all places. 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.

One relevant question is, what happens when 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. While it is possible to use a different character than the
blank character using the @code{string_fill_char} function, it 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}.

@DOCSTRING(char)

@DOCSTRING(strcat)

@DOCSTRING(strvcat)

@DOCSTRING(strtrunc)

@DOCSTRING(string_fill_char)

@DOCSTRING(str2mat)

@DOCSTRING(ischar)

@DOCSTRING(mat2str)

@DOCSTRING(num2str)

@DOCSTRING(int2str)

@node Comparing Strings
@section Comparing Strings

Since a string is a character array comparison between strings work
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 functions are identical it is therefore necessary
to use the @code{strcmp} or @code{strncpm} functions. Similar 
functions exist for doing case-insensitive comparisons.

@DOCSTRING(strcmp)

@DOCSTRING(strcmpi)

@DOCSTRING(strncmp)

@DOCSTRING(strncmpi)

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

@DOCSTRING(index)

@DOCSTRING(rindex)

@DOCSTRING(strfind)

@DOCSTRING(strmatch)

@DOCSTRING(strtok)

@DOCSTRING(split)

@DOCSTRING(strrep)

@DOCSTRING(substr)

@DOCSTRING(regexp)

@DOCSTRING(regexpi)

@DOCSTRING(regexprep)

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