[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[changeset] update of the documentation chapter on strings (strings.txi)
From: |
Thorsten Meyer |
Subject: |
[changeset] update of the documentation chapter on strings (strings.txi) |
Date: |
Sun, 16 Nov 2008 15:49:05 +0100 |
User-agent: |
Mozilla-Thunderbird 2.0.0.17 (X11/20081018) |
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
- [changeset] update of the documentation chapter on strings (strings.txi),
Thorsten Meyer <=