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

@c Copyright (C) 1996, 1997 John W. Eaton
@c This is part of the Octave manual.
@c For copying conditions, see the file gpl.texi.

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

@c XXX FIXME XXX -- this is probably pretty confusing.

@cindex escape sequence notation
Some characters cannot be included literally in a string constant.  You
represent them instead with @dfn{escape sequences}, which are character
sequences beginning with a backslash (@samp{\}).

One use of an escape sequence is to include a double-quote
(single-quote) character in a string constant that has been defined
using double-quote (single-quote) marks.  Since a plain double-quote
would end the string, you must use @samp{\"} to represent a single
double-quote character as a part of the string.  The backslash character
itself is another character that cannot be included normally.  You must
write @samp{\\} to put one backslash in the string.  Thus, the string
whose contents are the two characters @samp{"\} may be written
@code{"\"\\"} or @code{'"\\'}.  Similarly, the string whose contents are
the two characters @samp{'\} may be written @code{'\'\\'} or @code{"'\\"}.

Another use of backslash is to represent unprintable characters
such as newline.  While there is nothing to stop you from writing most
of these characters directly in a string constant, they may look ugly.

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::            
* Searching and Replacing::     
* String Conversions::          
* Character Class Functions::   
@end menu

@node Creating Strings
@section Creating Strings

@anchor{doc-blanks}
@deftypefn {Function File} {} blanks (@var{n})
Return a string of @var{n} blanks.
@end deftypefn


@anchor{doc-char}
@deftypefn {Built-in Function} {} char (@var{x})
@deftypefnx {Built-in Function} {} char (@var{cell_array})
@deftypefnx {Built-in Function} {} char (@var{s1}, @var{s2}, @dots{})
Create a string array from a numeric matrix, cell array, or list of

If the argument is a numeric matrix, each element of the matrix is
converted to the corresponding ASCII character.  For example,

@example
@group
char ([97, 98, 99])
     @result{} "abc"
@end group
@end example

If the argument is a cell array of strings, the result is a string array
with each element corresponding to one element of the cell array.

For multiple string arguments, the result is a string array with each
element corresponding to the arguments.

The returned values are padded with blanks as needed to make each row
of the string array have the same length.
@end deftypefn


@anchor{doc-int2str}
@deftypefn {Function File} {} int2str (@var{n})
@deftypefnx {Function File} {} num2str (@var{x}, @var{precision})
@deftypefnx {Function File} {} num2str (@var{x}, @var{format})
Convert a number to a string.  These functions are not very flexible,
but are provided for compatibility with @sc{Matlab}.  For better control
over the results, use @code{sprintf} (@pxref{Formatted Output}).
@end deftypefn

@seealso{sprintf and num2str}


@anchor{doc-com2str}
@deftypefn {Function File} {} com2str (@var{zz}, @var{flg})
This function has been deprecated.  Use num2str instead.

Convert complex number to a string.
@strong{Inputs}
@table @var
@item zz
complex number
@item flg
format flag
0 (default):            -1, 0, 1,   1i,   1 + 0.5i
1 (for use with zpout): -1, 0, + 1, + 1i, + 1 + 0.5i
@end table
@end deftypefn


@anchor{doc-strcat}
@deftypefn {Function File} {} strcat (@var{s1}, @var{s2}, @dots{})
Return a string containing all the arguments concatenated.  For example,

@example
@group
s = [ "ab"; "cde" ];
strcat (s, s, s)
@result{} "ab ab ab "
        "cdecdecde"
@end group
@end example
@end deftypefn


@anchor{doc-string_fill_char}
@defvr {Built-in Variable} string_fill_char
The value of this variable is used to pad all strings in a string matrix
to the same length.  It should be a single character.  The default value
is @code{" "} (a single space).  For example,

@example
@group
string_fill_char = "X";
[ "these"; "are"; "strings" ]
     @result{} "theseXX"
        "areXXXX"
        "strings"
@end group
@end example
@end defvr


@anchor{doc-str2mat}
@deftypefn {Function File} {} str2mat (@var{s_1}, @dots{}, @var{s_n})
Return a matrix containing the strings @var{s_1}, @dots{}, @var{s_n} as
its rows.  Each string is padded with blanks in order to form a valid
matrix.

This function is modelled after @sc{Matlab}.  In Octave, you can create
a matrix of strings by @code{[@var{s_1}; @dots{}; @var{s_n}]} even if
the strings are not all the same length.
@end deftypefn


@anchor{doc-ischar}
@deftypefn {Built-in Function} {} ischar (@var{a})
Return 1 if @var{a} is a string.  Otherwise, return 0.
@end deftypefn


@anchor{doc-isstr}
@deftypefn {Function File} {} isstr (@var{a})
This function has been deprecated.  Use ischar instead.
@end deftypefn


@node Searching and Replacing
@section Searching and Replacing

@anchor{doc-deblank}
@deftypefn {Function File} {} deblank (@var{s})
Removes the trailing blanks and nulls from the string @var{s}.
If @var{s} is a matrix, @var{deblank} trims each row to the 
length of longest string.
@end deftypefn


@anchor{doc-findstr}
@deftypefn {Function File} {} findstr (@var{s}, @var{t}, @var{overlap})
Return the vector of all positions in the longer of the two strings
@var{s} and @var{t} where an occurrence of the shorter of the two starts.
If the optional argument @var{overlap} is nonzero, the returned vector
can include overlapping positions (this is the default).  For example,

@example
findstr ("ababab", "a")
@result{} [ 1, 3, 5 ]
findstr ("abababa", "aba", 0)
@result{} [ 1, 5 ]
@end example
@end deftypefn


@anchor{doc-index}
@deftypefn {Function File} {} index (@var{s}, @var{t})
Return the position of the first occurrence of the string @var{t} in the
string @var{s}, or 0 if no occurrence is found.  For example,

@example
index ("Teststring", "t")
@result{} 4
@end example

@strong{Caution:}  This function does not work for arrays of strings.
@end deftypefn


@anchor{doc-rindex}
@deftypefn {Function File} {} rindex (@var{s}, @var{t})
Return the position of the last occurrence of the string @var{t} in the
string @var{s}, or 0 if no occurrence is found.  For example,

@example
rindex ("Teststring", "t")
@result{} 6
@end example

@strong{Caution:}  This function does not work for arrays of strings.
@end deftypefn


@anchor{doc-split}
@deftypefn {Function File} {} split (@var{s}, @var{t})
Divides the string @var{s} into pieces separated by @var{t}, returning
the result in a string array (padded with blanks to form a valid
matrix).  For example,

@example
split ("Test string", "t")
@result{} "Tes "
        " s  "
        "ring"
@end example
@end deftypefn


@anchor{doc-strcmp}
@deftypefn {Function File} {} strcmp (@var{s1}, @var{s2})
Compares two strings, returning 1 if they are the same, and 0 otherwise.

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


@anchor{doc-strrep}
@deftypefn {Function File} {} strrep (@var{s}, @var{x}, @var{y})
Replaces all occurrences of the substring @var{x} of the string @var{s}
with the string @var{y}.  For example,

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


@anchor{doc-substr}
@deftypefn {Function File} {} substr (@var{s}, @var{beg}, @var{len})
Return the substring of @var{s} which starts at character number
@var{beg} and is @var{len} characters long.

If OFFSET is negative, extraction starts that far from the end of
the string.  If LEN is omitted, the substring extends to the end
of S.

  For example,

@example
substr ("This is a test string", 6, 9)
@result{} "is a test"
@end example

@quotation
This function is patterned after AWK.  You can get the same result by
@code{@var{s} (@var{beg} : (@var{beg} + @var{len} - 1))}.
@end quotation
@end deftypefn


@node String Conversions
@section String Conversions

@anchor{doc-bin2dec}
@deftypefn {Function File} {} hex2dec (@var{s})
Return the decimal number corresponding to the binary number stored
in the string @var{s}.  For example,

@example
hex2dec ("1110")
@result{} 14
@end example

If @var{s} is a string matrix, returns a column vector of converted
numbers, one per row of @var{s}.  Invalid rows evaluate to NaN.
@end deftypefn

@seealso{dec2hex, base2dec, dec2base, bin2dec, dec2bin}


@anchor{doc-dec2bin}
@deftypefn {Function File} {} dec2bin (@var{n}, @var{len})
Return a binary number corresponding the nonnegative decimal number
@var{n}, as a string of ones and zeros.  For example,

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

If @var{n} is a vector, returns a string matrix, one row per value,
padded with leading zeros to the width of the largest value.

The optional second argument, @var{len}, specifies the minimum
number of digits in the result.
@end deftypefn

@seealso{bin2dec, dec2base, base2dec, hex2dec, dec2hex}


@anchor{doc-dec2hex}
@deftypefn {Function File} {} dec2hex (@var{n}, @var{len})
Return the hexadecimal string corresponding to the nonnegative 
integer @var{n}.  For example,

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

If @var{n} is a vector, returns a string matrix, one row per value,
padded with leading zeros to the width of the largest value.

The optional second argument, @var{len}, specifies the minimum
number of digits in the result.
@end deftypefn

@seealso{hex2dec, dec2base, base2dec, bin2dec, dec2bin}


@anchor{doc-hex2dec}
@deftypefn {Function File} {} hex2dec (@var{s})
Returns the integer corresponding to the hexadecimal number stored
in the string @var{s}.  For example,

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

If @var{s} is a string matrix, returns a column vector of converted
numbers, one per row of @var{s}.  Invalid rows evaluate to NaN.
@end deftypefn

@seealso{dec2hex, base2dec, dec2base, bin2dec, dec2bin}


@anchor{doc-dec2base}
@deftypefn {Function File} {} dec2base (@var{n}, @var{b}, @var{len})
Return a string of symbols in base @var{b} corresponding to the
the nonnegative integer @var{n}.

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

If @var{n} is a vector, return a string matrix with one row per value,
padded with leading zeros to the width of the largest value.

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

@example
dec2base (123, "aei")
@result{} "eeeia"
@end example

The optional third argument, @var{len}, specifies the minimum
number of digits in the result.
@end deftypefn

@seealso{base2dec, dec2bin, bin2dec, hex2dec, dec2hex}


@anchor{doc-base2dec}
@deftypefn {Function File} {} base2dec (@var{s}, @var{b})
Convert @var{s} from a string of digits of base @var{b} into an
integer.

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

If @var{s} is a matrix, returns a column vector with one value per
row of @var{s}.  If a row contains invalid symbols then the
corresponding value will be NaN.  Rows are right-justified before
converting so that trailing spaces are ignored.

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

@example
base2dec ("yyyzx", "xyz")
@result{} 123
@end example

@end deftypefn

@seealso{dec2base, dec2bin, bin2dec, hex2dec, dec2hex}


@anchor{doc-strjust}
@deftypefn {Function File} {} strjust (@var{s}, ["left"|"right"|"center"])
Shift the non-blank text of @var{s} to the left, right or center of
the string.  If @var{s} is a string array, justify each string in the
array.  Null characters are replaced by blanks.  If no justification
is specified, then all rows are right-justified.
@end deftypefn


@anchor{doc-str2num}
@deftypefn {Function File} {} str2num (@var{s})
Convert the string @var{s} to a number.
@end deftypefn


@anchor{doc-toascii}
@deftypefn {Mapping Function} {} toascii (@var{s})
Return ASCII representation of @var{s} in a matrix.  For example,

@example
@group
toascii ("ASCII")
     @result{} [ 65, 83, 67, 73, 73 ]
@end group

@end example
@end deftypefn


@anchor{doc-tolower}
@deftypefn {Mapping Function} {} tolower (@var{s})
Return a copy of the string @var{s}, with each upper-case character
replaced by the corresponding lower-case one; nonalphabetic characters
are left unchanged.  For example,

@example
tolower ("MiXeD cAsE 123")
     @result{} "mixed case 123"
@end example
@end deftypefn


@anchor{doc-toupper}
@deftypefn {Built-in Function} {} toupper (@var{s})
Return a copy of the string @var{s}, with each  lower-case character
replaced by the corresponding upper-case one; nonalphabetic characters
are left unchanged.  For example,

@example
@group
toupper ("MiXeD cAsE 123")
     @result{} "MIXED CASE 123"
@end group
@end example
@end deftypefn


@anchor{doc-do_string_escapes}
@deftypefn {Built-in Function} {} do_string_escapes (@var{string})
Convert special characters in @var{string} to their escaped forms.
@end deftypefn


@anchor{doc-undo_string_escapes}
@deftypefn {Built-in Function} {} undo_string_escapes (@var{s})
Converts special characters in strings back to their escaped forms.  For
example, the expression

@example
bell = "\a";
@end example

@noindent
assigns the value of the alert character (control-g, ASCII code 7) to
the string variable @code{bell}.  If this string is printed, the
system will ring the terminal bell (if it is possible).  This is
normally the desired outcome.  However, sometimes it is useful to be
able to print the original representation of the string, with the
special characters replaced by their escape sequences.  For example,

@example
octave:13> undo_string_escapes (bell)
ans = \a
@end example

@noindent
replaces the unprintable alert character with its printable
representation.
@end deftypefn


@anchor{doc-warn_num_to_str}
@defvr {Built-in Variable} warn_num_to_str
If the value of @code{warn_num_to_str} is nonzero, a warning is
printed for implicit conversions of numbers to their ASCII character
equivalents when strings are constructed using a mixture of strings and
numbers in matrix notation.  For example,

@example
@group
[ "f", 111, 111 ]
     @result{} "foo"
@end group
@end example
elicits a warning if @code{warn_num_to_str} is nonzero.  The default
value is 1.
@end defvr


@anchor{doc-warn_str_to_num}
@defvr {Built-in Variable} warn_str_to_num
If the value of @code{warn_str_to_num} is nonzero, a warning is printed
for implicit conversions of strings to their numeric ASCII equivalents.
For example,
@example
@group
"abc" + 0
     @result{} 97 98 99
@end group
@end example
elicits a warning if @code{warn_str_to_num} is nonzero.  The default
value is 0.
@end defvr


@anchor{doc-warn_single_quote_string}
@defvr {Built-in Variable} warn_single_quote_string
Print warning if a signle quote character is used to introduce a
string constant.
@end defvr


@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

@anchor{doc-isalnum}
@deftypefn {Mapping Function} {} isalnum (@var{s})
Return 1 for characters that are letters or digits (@code{isalpha
(@var{s})} or @code{isdigit (@var{s})} is true).
@end deftypefn


@anchor{doc-isalpha}
@deftypefn {Mapping Function} {} isalpha (@var{s})
@deftypefnx {Mapping Function} {} isletter (@var{s})
Return true for characters that are letters (@code{isupper (@var{s})}
or @code{islower (@var{s})} is true).
@end deftypefn


@anchor{doc-isascii}
@deftypefn {Mapping Function} {} isascii (@var{s})
Return 1 for characters that are ASCII (in the range 0 to 127 decimal).
@end deftypefn


@anchor{doc-iscntrl}
@deftypefn {Mapping Function} {} iscntrl (@var{s})
Return 1 for control characters.
@end deftypefn


@anchor{doc-isdigit}
@deftypefn {Mapping Function} {} isdigit (@var{s})
Return 1 for characters that are decimal digits.
@end deftypefn


@anchor{doc-isgraph}
@deftypefn {Mapping Function} {} isgraph (@var{s})
Return 1 for printable characters (but not the space character).
@end deftypefn


@anchor{doc-islower}
@deftypefn {Mapping Function} {} islower (@var{s})
Return 1 for characters that are lower case letters.
@end deftypefn


@anchor{doc-isprint}
@deftypefn {Mapping Function} {} isprint (@var{s})
Return 1 for printable characters (including the space character).
@end deftypefn


@anchor{doc-ispunct}
@deftypefn {Mapping Function} {} ispunct (@var{s})
Return 1 for punctuation characters.
@end deftypefn


@anchor{doc-isspace}
@deftypefn {Mapping Function} {} isspace (@var{s})
Return 1 for whitespace characters (space, formfeed, newline,
carriage return, tab, and vertical tab).
@end deftypefn


@anchor{doc-isupper}
@deftypefn {Mapping Function} {} isupper (@var{s})
Return 1 for upper case letters.
@end deftypefn


@anchor{doc-isxdigit}
@deftypefn {Mapping Function} {} isxdigit (@var{s})
Return 1 for characters that are hexadecimal digits.
@end deftypefn

