added documentation for const_iterator

[ginac.git] / doc / tutorial / ginac.texi

diff --git a/doc/tutorial/ginac.texi b/doc/tutorial/ginac.texi
index 8d2f985ec729cdc2854a42f98795bfd938c7b283..cbcd183975a64ffde62ceb317c683573447917ab 100644 (file)
--- a/doc/tutorial/ginac.texi
+++ b/doc/tutorial/ginac.texi
@@ -48,7 +48,7 @@ notice identical to this one.
 @subtitle An open framework for symbolic computation within the C++ programming language
 @subtitle @value{UPDATED}
 @author The GiNaC Group:
-@author Christian Bauer, Alexander Frink, Richard Kreckel
+@author Christian Bauer, Alexander Frink, Richard Kreckel, Jens Vollinga
 
 @page
 @vskip 0pt plus 1filll
@@ -2828,7 +2828,7 @@ You can use this to compare two expressions or for further simplifications:
 
     e = canonicalize_clifford(e);
     cout << e << endl;
-     // -> 2*eta~mu~nu
+     // -> 2*ONE*eta~mu~nu
 @}
 @end example
 
@@ -2999,6 +2999,9 @@ avoided.
 * Series Expansion::                Taylor and Laurent expansion.
 * Symmetrization::
 * Built-in Functions::              List of predefined mathematical functions.
+* Multiple polylogarithms::
+* Complex Conjugation::
+* Built-in Functions::              List of predefined mathematical functions.
 * Solving Linear Systems of Equations::
 * Input/Output::                    Input and output of expressions.
 @end menu
@@ -3151,23 +3154,62 @@ for an explanation of these.
 @cindex container
 @cindex @code{relational} (class)
 
-GiNaC provides the two methods
+Many GiNaC classes, like @code{add}, @code{mul}, @code{lst}, and
+@code{function}, act as containers for subexpressions. For example, the
+subexpressions of a sum (an @code{add} object) are the individual terms,
+and the subexpressions of a @code{function} are the function's arguments.
+
+GiNaC provides two ways of accessing subexpressions. The first way is to use
+the two methods
 
 @example
 size_t ex::nops();
 ex ex::op(size_t i);
 @end example
 
-for accessing the subexpressions in the container-like GiNaC classes like
-@code{add}, @code{mul}, @code{lst}, and @code{function}. @code{nops()}
-determines the number of subexpressions (@samp{operands}) contained, while
-@code{op()} returns the @code{i}-th (0..@code{nops()-1}) subexpression.
-In the case of a @code{power} object, @code{op(0)} will return the basis
-and @code{op(1)} the exponent. For @code{indexed} objects, @code{op(0)}
-is the base expression and @code{op(i)}, @math{i>0} are the indices.
+@code{nops()} determines the number of subexpressions (operands) contained
+in the expression, while @code{op(i)} returns the @code{i}-th
+(0..@code{nops()-1}) subexpression. In the case of a @code{power} object,
+@code{op(0)} will return the basis and @code{op(1)} the exponent. For
+@code{indexed} objects, @code{op(0)} is the base expression and @code{op(i)},
+@math{i>0} are the indices.
+
+The second way to access subexpressions is via the STL-style random-access
+iterator class @code{const_iterator} and the methods
+
+@example
+const_iterator ex::begin();
+const_iterator ex::end();
+@end example
+
+@code{begin()} returns an iterator referring to the first subexpression;
+@code{end()} returns an iterator which is one-past the last subexpression.
+If the expression has no subexpressions, then @code{begin() == end()}. These
+iterators can also be used in conjunction with non-modifying STL algorithms.
 
-The left-hand and right-hand side expressions of objects of class
-@code{relational} (and only of these) can also be accessed with the methods
+Here is an example that (non-recursively) prints all the subexpressions of a
+given expression in three different ways:
+
+@example
+@{
+    ex e = ...
+
+    // with nops()/op()
+    for (size_t i = 0; i != e.nops(); ++i)
+        cout << e.op(i) << endl;
+
+    // with iterators
+    for (const_iterator i = e.begin(); i != e.end(); ++i)
+        cout << *i << endl;
+
+    // with iterators and STL copy()
+    std::copy(e.begin(), e.end(), std::ostream_iterator<ex>(cout, "\n"));
+@}
+@end example
+
+Additionally, the left-hand and right-hand side expressions of objects of
+class @code{relational} (and only of these) can also be accessed with the
+methods
 
 @example
 ex ex::lhs();
@@ -3274,7 +3316,7 @@ after @code{other}.
 
 @node Numerical Evaluation, Substituting Expressions, Information About Expressions, Methods and Functions
 @c    node-name, next, previous, up
-@section Numercial Evaluation
+@section Numerical Evaluation
 @cindex @code{evalf()}
 
 GiNaC keeps algebraic expressions, numbers and constants in their exact form.
@@ -4755,7 +4797,7 @@ almost any kind of object (anything that is @code{subs()}able):
 @}
 @end example
 
-@node Built-in Functions, Complex Conjugation, Symmetrization, Methods and Functions
+@node Built-in Functions, Multiple polylogarithms, Symmetrization, Methods and Functions
 @c    node-name, next, previous, up
 @section Predefined mathematical functions
 @c
@@ -4885,6 +4927,8 @@ serious CAS.  It is to be expected that future revisions of the C++
 standard incorporate these functions in the complex domain in a manner
 compatible with C99.
 
+@node Multiple polylogarithms, Complex Conjugation, Built-in Functions, Methods and Functions
+@c    node-name, next, previous, up
 @subsection Multiple polylogarithms
 
 @cindex polylogarithm
@@ -5031,7 +5075,7 @@ E.Remiddi, J.A.M.Vermaseren, Int.J.Mod.Phys. A15 (2000), pp. 725-754
 @cite{Special Values of Multiple Polylogarithms}, 
 J.Borwein, D.Bradley, D.Broadhurst, P.Lisonek, Trans.Amer.Math.Soc. 353/3 (2001), pp. 907-941
 
-@node Complex Conjugation, Solving Linear Systems of Equations, Built-in Functions, Methods and Functions
+@node Complex Conjugation, Solving Linear Systems of Equations, Multiple polylogarithms, Methods and Functions
 @c    node-name, next, previous, up
 @section Complex Conjugation
 @c