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

@cindex strings

@node String Functions, System Utilities, Matrix Manipulation, Top
@chapter String Functions

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

@strong{Note: 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

@deftypefn {Function File} {} int2str (@var{n})
@deftypefnx {Function File} {} num2str (@var{x})
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

@deftypefn {Built-in Function} {} setstr (@var{x})
Convert a matrix to a string.  Each element of the matrix is converted
to the corresponding ASCII 
character.  For example,

@example
setstr ([97, 98, 99])
@end example

@noindent
creates the string

@example
abc
@end example
@end deftypefn

@defvr {Built-in Variable} implicit_str_to_num_ok
If the value of @code{implicit_str_to_num_ok} is nonzero, implicit
conversions of strings to their numeric ASCII equivalents are allowed.
Otherwise, an error message is printed and control is returned to the
top level.  The default value is 0.
@end defvr

@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 @var{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.  @xref{String Constants}, for a description of string
escapes.
@end deftypefn

@deftypefn {Function File} {} bin2dec (@var{s})
Given a binary number represented as a string of zeros and ones,
returns the corresponding decimal number.  For example,

@example
bin2dec ("1110")
    @result{} 14
@end example
@end deftypefn

@deftypefn {Function File} {} blanks (var{n})
Returns a string of @var{n} blanks.
@end deftypefn

@deftypefn {Function File} {} deblank (@var{s})
Removes the trailing blanks from the string @var{s}. 
@end deftypefn

@deftypefn {Function File} {} dec2bin (@var{n})
Given a nonnegative integer, returns the corresponding binary number as
a string of ones and zeros.  For example, 

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

@deftypefn {Function File} {} dec2hex (@var{n})
Given a nonnegative integer, returns the corresponding hexadecimal
number as a string.  For example,

@example
dec2hex (2748)
   @result{} "abc"
@end example
@end deftypefn

@deftypefn {Function File} {} findstr (@var{s}, @var{t}, @var{overlap})
Returns the vector of all positions in the longer of the two strings
@var{s} and @var{t} where an occurence 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

@deftypefn {Function File} {} hex2dec (@var{s})
Given a hexadecimal number represented as a string, returns the
corresponding decimal number.  For example,

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

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

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

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

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

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

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

@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

@deftypefn {Function File} {} str2mat (@var{s_1}, @dots{}, @var{s_n})
Returns 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.

@quotation
@strong{Note:}
This function is modelled after @sc{MATLAB}.  In Octave, you can create
a matrix of strings by @kbd{[@var{s_1}; @dots{}; @var{s_n}]}.
@end quotation
@end deftypefn

@defvr {Built-in Variable} string_fill_char
@end defvr

@deftypefn {Function File} {} strrep (@var{s}, @var{x}, @var{y})
Replaces all occurences 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

@deftypefn {Function File} {} substr (@var{s}, @var{beg}, @var{len})
Returns the substring of @var{s} which starts at character number
@var{beg} and is @var{len} characters long.  For example,

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

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

@deftypefn {Function File} {} 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

@deftypefn {Function File} {} toupper (@var{s})
Returns 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

@deftypefn {Function File} {} 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

Octave also provides the following C-type character class test
functions.  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.

@deftypefn {Mapping Function} {} isalnum (@var{s})
letter or a digit
@end deftypefn

@deftypefn {Mapping Function} {} isalpha (@var{s})
letter
@end deftypefn

@deftypefn {Mapping Function} {} isascii (@var{s})
ascii
@end deftypefn

@deftypefn {Mapping Function} {} iscntrl (@var{s})
control character
@end deftypefn

@deftypefn {Mapping Function} {} isdigit (@var{s})
digit
@end deftypefn

@deftypefn {Mapping Function} {} isgraph (@var{s})
printable (but not space character)
@end deftypefn

@deftypefn {Mapping Function} {} islower (@var{s})
lower case
@end deftypefn

@deftypefn {Mapping Function} {} isprint (@var{s})
printable (including space character)
@end deftypefn

@deftypefn {Mapping Function} {} ispunct (@var{s})
punctuation
@end deftypefn

@deftypefn {Mapping Function} {} isspace (@var{s})
whitespace
@end deftypefn

@deftypefn {Mapping Function} {} isupper (@var{s})
upper case
@end deftypefn

@deftypefn {Mapping Function} {} isxdigit (@var{s})
hexadecimal digit
@end deftypefn