[changeset] update of the documentation chapter on strings (strings.txi)

[Thorsten Meyer]

Hi,

attached is a changeset with an update of the strings chapter in the manual.
I added text around the docstrings and changed the structure in a few places:
 - I moved the explanation of escape sequences to a separate section (now
one does not have to scroll down to get to the section menu)
 - I made the part on character arrays a separate section (imho this is
important enough to get its own section)
 - I split up the section "Creating Strings" into two subsections
"Concatenating Strings" and "Conversion of numerical data into Strings".

Feedback would be very welcome.

Thorsten

# HG changeset patch
# User Thorsten Meyer <address@hidden>
# Date 1226844143 -3600
# Node ID eee4587bc8e4a55e5f63192a46afd74b2a5715dd
# Parent  60ada64ad8de526dfc4f4bc96607114d9fac5aa1
improve string documentation

diff -r 60ada64ad8de -r eee4587bc8e4 doc/ChangeLog
--- a/doc/ChangeLog     Sun Nov 16 10:47:11 2008 +0100
+++ b/doc/ChangeLog     Sun Nov 16 15:02:23 2008 +0100
@@ -1,3 +1,8 @@
+2008-11-15  Thorsten Meyer  <address@hidden>
+
+        * interpreter/strings.txi: Add text around docstrings, change
+        structure of the strings chapter.
+        
 2008-10-31  John W. Eaton  <address@hidden>
 
        * interpreter/Makefile.in ($(TEXINFO)): Depend directly on
diff -r 60ada64ad8de -r eee4587bc8e4 doc/interpreter/strings.txi
--- a/doc/interpreter/strings.txi       Sun Nov 16 10:47:11 2008 +0100
+++ b/doc/interpreter/strings.txi       Sun Nov 16 15:02:23 2008 +0100
@@ -40,18 +40,38 @@
 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.
+(@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 
+ 
address@hidden
+[ "foo" , "bar" , "baz" ]
address@hidden example
+
address@hidden
+produces the string whose contents are @samp{foobarbaz}.  @xref{Numeric Data
+Types}, for more information about creating matrices.
+
address@hidden
+* Escape Sequences in string constants::
+* Character Arrays::
+* Creating Strings:: 
+* Comparing Strings::           
+* Manipulating Strings::     
+* String Conversions::          
+* Character Class Functions::   
address@hidden menu
+
address@hidden Escape Sequences in string constants
address@hidden 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
address@hidden"} embeds a double quote character.
-
-In single-quoted strings, backslash is not a special character.
-
-Here is an example showing the difference
address@hidden"} embeds a double quote character.  In single-quoted strings, 
backslash
+is not a special character.  Here is an example showing the difference:
 
 @example
 @group
@@ -62,16 +82,9 @@
 @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,
-
address@hidden
-'I can''t escape'
-    @result{} I can't escape
address@hidden 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.
+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 \\
@@ -124,44 +137,29 @@
 @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
+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
-[ "foo" , "bar" , "baz" ]
address@hidden
+'I can''t escape'
+    @result{} I can't escape
address@hidden group
 @end example
 
address@hidden
-produces the string whose contents are @samp{foobarbaz}.  @xref{Numeric
-Data Types}, for more information about creating matrices.
 
address@hidden
-* Creating Strings:: 
-* Comparing Strings::           
-* Manipulating Strings::     
-* String Conversions::          
-* Character Class Functions::   
address@hidden menu
-
address@hidden Creating Strings
address@hidden 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).
-
address@hidden(blanks)
address@hidden Character Arrays
address@hidden Character Arrays
 
 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.
+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.
@@ -173,30 +171,190 @@
 @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
+The function @code{ischar} can be used to test if an object is a character
+matrix.
+
address@hidden(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
address@hidden function as in the following example:
+
address@hidden
address@hidden
+ischar(collection)
+     @result{} ans = 1
+ischar(collection) && isvector(collection)
+     @result{} ans = 0
+ischar("my string") && isvector("my string")
+     @result{} ans = 1
address@hidden group
address@hidden 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. 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}.
+string.  It is possible to use a different character than the
+blank character using the @code{string_fill_char} function.
+
address@hidden(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}.
+
address@hidden Creating Strings
address@hidden 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).
+
address@hidden(blanks)
+
address@hidden
+* Concatenating Strings:: 
+* Conversion of Numerical Data to Strings::
address@hidden menu
+
address@hidden Concatenating Strings
address@hidden 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{str2mat},
address@hidden, @code{strcat} and @code{cstrcat}.  In addition, the general
+purpose concatenation functions can be used: see @ref{doc-cat,,cat},
address@hidden,,horzcat} and @ref{doc-vertcat,,vertcat}.
+
address@hidden @bullet
address@hidden 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:
+
address@hidden
address@hidden
+char([98, 97, 110, 97, 110, 97])
+     @result{} ans =
+       banana
address@hidden group
address@hidden example
+
address@hidden
address@hidden, @code{str2mat} and @code{strvcat}
+concatenate vertically, while @code{strcat} and @code{cstrcat} concatenate
+horizontally.  For example:
+
address@hidden
address@hidden
+char("an apple", "two pears")
+     @result{} ans =
+       an apple
+       two pears
address@hidden group
+
address@hidden
+strcat("oc", "tave", " is", " good", " for you")
+     @result{} ans =
+       octave is good for you
address@hidden group
address@hidden example
+
address@hidden @code{char} and @code{str2mat} both generate an empty row in the 
output
+for each empty string in the input.  @code{strvcat}, on the other hand,
+eliminates empty strings.
+
address@hidden
address@hidden
+char("orange", "green", "", "red")
+     @result{} ans =
+       orange
+       green 
+             
+       red   
address@hidden group
+
address@hidden
+strvcat("orange", "green", "", "red")
+     @result{} ans =
+       orange
+       green 
+       red  
address@hidden group
address@hidden example
+
address@hidden All string concatenation functions except @code{cstrcat} also 
accept cell
+array data (@pxref{Cell Arrays}).  @code{char}, @code{str2mat} and
address@hidden convert cell arrays into character arrays, while @code{strcat}
+concatenates within the cells of the cell arrays:
+
address@hidden
address@hidden
+char(@{"red", "green", "", "blue"@})
+     @result{} ans =
+       red  
+       green
+
+       blue 
address@hidden group
+
address@hidden
+strcat(@{"abc"; "ghi"@}, @{"def"; "jkl"@})
+     @result{} ans =
+       @{
+         [1,1] = abcdef
+         [2,1] = ghijkl
+       @}
address@hidden group
address@hidden example
+
address@hidden @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:
+
address@hidden
address@hidden
+strcat(["dir1";"directory2"], ["/";"/"], ["file1";"file2"])
+     @result{} ans =
+       dir1/file1      
+       directory2/file2
address@hidden group
address@hidden
+
+cstrcat(["thirteen apples"; "a banana"], [" 5$";" 1$"])
+     @result{} ans =
+       thirteen apples 5$
+       a banana        1$
address@hidden group
address@hidden 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}).
address@hidden itemize
 
 @DOCSTRING(char)
 
address@hidden(strcat)
address@hidden(str2mat)
 
 @DOCSTRING(strvcat)
 
address@hidden(strcat)
+
 @DOCSTRING(cstrcat)
 
address@hidden(strtrunc)
-
address@hidden(string_fill_char)
-
address@hidden(str2mat)
-
address@hidden(ischar)
address@hidden Conversion of Numerical Data to Strings 
address@hidden 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
address@hidden 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},
address@hidden).
 
 @DOCSTRING(mat2str)
 
@@ -207,38 +365,39 @@
 @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.
+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 == " ")
address@hidden spaces =
-      0   0   0   0   0   1   0   0   0   1   0   0   0   0
+     @result{} spaces =
+       0   0   0   0   0   1   0   0   0   1   0   0   0   0
 @end example
 
address@hidden
-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.
address@hidden To determine if two strings are identical it is necessary to use 
the
address@hidden function.  It compares complete strings and is case
+sensistive.  @code{strncmp} compares only the first @code{N} characters (with
address@hidden given as a parameter).  @code{strcmpi} and @code{strncmpi} are 
the
+corresponding functions for case-insensitive comparison.
 
 @DOCSTRING(strcmp)
 
address@hidden(strncmp)
+
 @DOCSTRING(strcmpi)
-
address@hidden(strncmp)
 
 @DOCSTRING(strncmpi)
 
address@hidden(validstring)
address@hidden(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.
+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 = ...
@@ -252,6 +411,8 @@
 general regular expressions, the following functions come with Octave.
 
 @DOCSTRING(deblank)
+
address@hidden(strtrunc)
 
 @DOCSTRING(findstr)
 
@@ -283,7 +444,7 @@
 @section String Conversions
 
 Octave supports various kinds of conversions between strings and
-numbers. As an example, it is possible to convert a string containing
+numbers.  As an example, it is possible to convert a string containing
 a hexadecimal number to a floating point number.
 
 @example