From d2d45a3f3e8a42bbd4c0ad96fd4b6d4b6b86af9c Mon Sep 17 00:00:00 2001
From: Christian Bauer <Christian.Bauer@uni-mainz.de>
Date: Mon, 3 Sep 2001 22:28:30 +0000
Subject: [PATCH] added a section about error handling

---
 doc/tutorial/ginac.texi | 92 +++++++++++++++++++++++++++++++++--------
 1 file changed, 75 insertions(+), 17 deletions(-)

diff --git a/doc/tutorial/ginac.texi b/doc/tutorial/ginac.texi
index 3e0256b9..e6993f33 100644
--- a/doc/tutorial/ginac.texi
+++ b/doc/tutorial/ginac.texi
@@ -668,6 +668,7 @@ meta-class for storing all mathematical objects.
 @menu
 * Expressions::                  The fundamental GiNaC class.
 * The Class Hierarchy::          Overview of GiNaC's classes.
+* Error handling::               How the library reports errors.
 * Symbols::                      Symbolic objects.
 * Numbers::                      Numerical objects.
 * Constants::                    Pre-defined constants.
@@ -715,7 +716,7 @@ hierarchy and describe the classes of objects that are handled by
 @code{ex}.
 
 
-@node The Class Hierarchy, Symbols, Expressions, Basic Concepts
+@node The Class Hierarchy, Error handling, Expressions, Basic Concepts
 @c    node-name, next, previous, up
 @section The Class Hierarchy
 
@@ -781,7 +782,64 @@ $\sqrt{2}$
 @end multitable
 @end cartouche
 
-@node Symbols, Numbers, The Class Hierarchy, Basic Concepts
+
+@node Error handling, Symbols, The Class Hierarchy, Basic Concepts
+@c    node-name, next, previous, up
+@section Error handling
+@cindex exceptions
+@cindex @code{pole_error} (class)
+
+GiNaC reports run-time errors by throwing C++ exceptions. All exceptions
+generated by GiNaC are subclassed from the standard @code{exception} class
+defined in the @file{<stdexcept>} header. In addition to the predefined
+@code{logic_error}, @code{domain_error}, @code{out_of_range},
+@code{invalid_argument}, @code{runtime_error}, @code{range_error} and
+@code{overflow_error} types, GiNaC also defines a @code{pole_error}
+exception that gets thrown when trying to evaluate a mathematical function
+at a singularity.
+
+The @code{pole_error} class has a member function
+
+@example
+int pole_error::degree(void) const;
+@end example
+
+that returns the order of the singularity (or 0 when the pole is
+logarithmic or the order is undefined).
+
+When using GiNaC it is useful to arrange for exceptions to be catched in
+the main program even if you don't want to do any special error handling.
+Otherwise whenever an error occurs in GiNaC, it will be delegated to the
+default exception handler of your C++ compiler's run-time system which
+ususally only aborts the program without giving any information what went
+wrong.
+
+Here is an example for a @code{main()} function that catches and prints
+exceptions generated by GiNaC:
+
+@example
+#include <iostream>
+#include <stdexcept>
+#include <ginac/ginac.h>
+using namespace std;
+using namespace GiNaC;
+
+int main(void)
+@{
+    try @{
+        ...
+        // code using GiNaC
+        ...
+    @} catch (exception &p) @{
+        cerr << p.what() << endl;
+        return 1;
+    @}
+    return 0;
+@}
+@end example
+
+
+@node Symbols, Numbers, Error handling, Basic Concepts
 @c    node-name, next, previous, up
 @section Symbols
 @cindex @code{symbol} (class)
@@ -3187,8 +3245,8 @@ GiNaC offers the @code{map()} method to aid in the implementation of such
 operations:
 
 @example
-static ex ex::map(map_function & f) const;
-static ex ex::map(ex (*f)(const ex & e)) const;
+ex ex::map(map_function & f) const;
+ex ex::map(ex (*f)(const ex & e)) const;
 @end example
 
 In the first (preferred) form, @code{map()} takes a function object that
@@ -4190,19 +4248,19 @@ using namespace GiNaC;
 
 int main()
 @{
-     symbol x("x");
-     string s;
-
-     cout << "Enter an expression containing 'x': ";
-     getline(cin, s);
-
-     try @{
-         ex e(s, lst(x));
-         cout << "The derivative of " << e << " with respect to x is ";
-         cout << e.diff(x) << ".\n";
-     @} catch (exception &p) @{
-         cerr << p.what() << endl;
-     @}
+    symbol x("x");
+    string s;
+
+    cout << "Enter an expression containing 'x': ";
+    getline(cin, s);
+
+    try @{
+        ex e(s, lst(x));
+        cout << "The derivative of " << e << " with respect to x is ";
+        cout << e.diff(x) << ".\n";
+    @} catch (exception &p) @{
+        cerr << p.what() << endl;
+    @}
 @}
 @end example
 
-- 
2.44.0