+@node Built-in Functions, Input/Output, Series Expansion, Methods and Functions
+@c node-name, next, previous, up
+@section Predefined mathematical functions
+
+GiNaC contains the following predefined mathematical functions:
+
+@cartouche
+@multitable @columnfractions .30 .70
+@item @strong{Name} @tab @strong{Function}
+@item @code{abs(x)}
+@tab absolute value
+@item @code{csgn(x)}
+@tab complex sign
+@item @code{sqrt(x)}
+@tab square root (not a GiNaC function proper but equivalent to @code{pow(x, numeric(1, 2)})
+@item @code{sin(x)}
+@tab sine
+@item @code{cos(x)}
+@tab cosine
+@item @code{tan(x)}
+@tab tangent
+@item @code{asin(x)}
+@tab inverse sine
+@item @code{acos(x)}
+@tab inverse cosine
+@item @code{atan(x)}
+@tab inverse tangent
+@item @code{atan2(y, x)}
+@tab inverse tangent with two arguments
+@item @code{sinh(x)}
+@tab hyperbolic sine
+@item @code{cosh(x)}
+@tab hyperbolic cosine
+@item @code{tanh(x)}
+@tab hyperbolic tangent
+@item @code{asinh(x)}
+@tab inverse hyperbolic sine
+@item @code{acosh(x)}
+@tab inverse hyperbolic cosine
+@item @code{atanh(x)}
+@tab inverse hyperbolic tangent
+@item @code{exp(x)}
+@tab exponential function
+@item @code{log(x)}
+@tab natural logarithm
+@item @code{zeta(x)}
+@tab Riemann's zeta function
+@item @code{zeta(n, x)}
+@tab derivatives of Riemann's zeta function
+@item @code{tgamma(x)}
+@tab Gamma function
+@item @code{lgamma(x)}
+@tab logarithm of Gamma function
+@item @code{beta(x, y)}
+@tab Beta function (@code{tgamma(x)*tgamma(y)/tgamma(x+y)})
+@item @code{psi(x)}
+@tab psi (digamma) function
+@item @code{psi(n, x)}
+@tab derivatives of psi function (polygamma functions)
+@item @code{factorial(n)}
+@tab factorial function
+@item @code{binomial(n, m)}
+@tab binomial coefficients
+@item @code{Order(x)}
+@tab order term function in truncated power series
+@item @code{Derivative(x, l)}
+@tab inert partial differentiation operator (used internally)
+@end multitable
+@end cartouche
+
+@cindex branch cut
+For functions that have a branch cut in the complex plane GiNaC follows
+the conventions for C++ as defined in the ANSI standard. In particular:
+the natural logarithm (@code{log}) and the square root (@code{sqrt})
+both have their branch cuts running along the negative real axis where
+the points on the axis itself belong to the upper part.
+
+
+@node Input/Output, Extending GiNaC, Built-in Functions, Methods and Functions
+@c node-name, next, previous, up
+@section Input and output of expressions
+@cindex I/O
+
+@subsection Expression output
+@cindex printing
+@cindex output of expressions
+
+The easiest way to print an expression is to write it to a stream:
+
+@example
+@{
+ symbol x("x");
+ ex e = 7+4.2*pow(x,2);
+ cout << e << endl; // prints '7+4.2*x^2'
+ // ...
+@end example
+
+The output format is identical to the @command{ginsh} input syntax and
+to that used by most computer algebra systems, but not directly pastable
+into a GiNaC C++ program (note that in the above example, @code{pow(x,2)}
+is printed as @samp{x^2}).
+
+To print an expression in a way that can be directly used in a C or C++
+program, you use the method
+
+@example
+void ex::printcsrc(ostream & os, unsigned type, const char *name);
+@end example
+
+This outputs a line in the form of a variable definition @code{<type> <name> = <expression>}.
+The possible types are defined in @file{ginac/flags.h} (@code{csrc_types})
+and mostly affect the way in which floating point numbers are written:
+
+@example
+ // ...
+ e.printcsrc(cout, csrc_types::ctype_float, "f");
+ e.printcsrc(cout, csrc_types::ctype_double, "d");
+ e.printcsrc(cout, csrc_types::ctype_cl_N, "n");
+ // ...
+@end example
+
+The above example will produce (note the @code{x^2} being converted to @code{x*x}):
+
+@example
+float f = 4.200000e+00*(x*x)+7.000000e+00;
+double d = 4.200000e+00*(x*x)+7.000000e+00;
+cl_N n = cl_F("4.2000000000000001776")*(x*x)+cl_F("7.0");
+@end example
+
+Finally, there are the two methods @code{printraw()} and @code{printtree()} intended for GiNaC
+developers, that provide a dump of the internal structure of an expression for
+debugging purposes:
+
+@example
+ // ...
+ e.printraw(cout); cout << endl << endl;
+ e.printtree(cout);
+@}
+@end example
+
+produces
+
+@example
+ex(+((power(ex(symbol(name=x,serial=1,hash=150875740,flags=11)),ex(numeric(2)),hash=2,flags=3),numeric(4.2000000000000001776L0)),,hash=0,flags=3))
+
+type=Q25GiNaC3add, hash=0 (0x0), flags=3, nops=2
+ power: hash=2 (0x2), flags=3
+ x (symbol): serial=1, hash=150875740 (0x8fe2e5c), flags=11
+ 2 (numeric): hash=2147483714 (0x80000042), flags=11
+ 4.2000000000000001776L0 (numeric): hash=3006477126 (0xb3333346), flags=11
+ -----
+ overall_coeff
+ 7 (numeric): hash=2147483763 (0x80000073), flags=11
+ =====
+@end example
+
+The @code{printtree()} method is also available in @command{ginsh} as the
+@code{print()} function.
+
+
+@subsection Expression input
+@cindex input of expressions
+
+GiNaC provides no way to directly read an expression from a stream because
+you will usually want the user to be able to enter something like @samp{2*x+sin(y)}
+and have the @samp{x} and @samp{y} correspond to the symbols @code{x} and
+@code{y} you defined in your program and there is no way to specify the
+desired symbols to the @code{>>} stream input operator.
+
+Instead, GiNaC lets you construct an expression from a string, specifying the
+list of symbols to be used:
+
+@example
+@{
+ symbol x("x"), y("y");
+ ex e("2*x+sin(y)", lst(x, y));
+@}
+@end example
+
+The input syntax is the same as that used by @command{ginsh} and the stream
+output operator @code{<<}. The symbols in the string are matched by name to
+the symbols in the list and if GiNaC encounters a symbol not specified in
+the list it will throw an exception.
+
+With this constructor, it's also easy to implement interactive GiNaC programs:
+
+@example
+#include <iostream>
+#include <string>
+#include <stdexcept>
+#include <ginac/ginac.h>
+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;
+ @}
+@}
+@end example
+
+
+@subsection Archiving
+@cindex @code{archive} (class)
+@cindex archiving
+
+GiNaC allows creating @dfn{archives} of expressions which can be stored
+to or retrieved from files. To create an archive, you declare an object
+of class @code{archive} and archive expressions in it, giving each
+expression a unique name:
+
+@example
+#include <ginac/ginac.h>
+#include <fstream>
+using namespace GiNaC;
+
+int main()
+@{
+ symbol x("x"), y("y"), z("z");
+
+ ex foo = sin(x + 2*y) + 3*z + 41;
+ ex bar = foo + 1;
+
+ archive a;
+ a.archive_ex(foo, "foo");
+ a.archive_ex(bar, "the second one");
+ // ...
+@end example
+
+The archive can then be written to a file:
+
+@example
+ // ...
+ ofstream out("foobar.gar");
+ out << a;
+ out.close();
+ // ...
+@end example
+
+The file @file{foobar.gar} contains all information that is needed to
+reconstruct the expressions @code{foo} and @code{bar}.
+
+@cindex @command{viewgar}
+The tool @command{viewgar} that comes with GiNaC can be used to view
+the contents of GiNaC archive files:
+
+@example
+$ viewgar foobar.gar
+foo = 41+sin(x+2*y)+3*z
+the second one = 42+sin(x+2*y)+3*z
+@end example
+
+The point of writing archive files is of course that they can later be
+read in again:
+
+@example
+ // ...
+ archive a2;
+ ifstream in("foobar.gar");
+ in >> a2;
+ // ...
+@end example
+
+And the stored expressions can be retrieved by their name:
+
+@example
+ // ...
+ lst syms(x, y);
+
+ ex ex1 = a2.unarchive_ex(syms, "foo");
+ ex ex2 = a2.unarchive_ex(syms, "the second one");
+
+ cout << ex1 << endl; // prints "41+sin(x+2*y)+3*z"
+ cout << ex2 << endl; // prints "42+sin(x+2*y)+3*z"
+ cout << ex1.subs(x == 2) << endl; // prints "41+sin(2+2*y)+3*z"
+@}
+@end example
+
+Note that you have to supply a list of the symbols which are to be inserted
+in the expressions. Symbols in archives are stored by their name only and
+if you don't specify which symbols you have, unarchiving the expression will
+create new symbols with that name. E.g. if you hadn't included @code{x} in
+the @code{syms} list above, the @code{ex1.subs(x == 2)} statement would
+have had no effect because the @code{x} in @code{ex1} would have been a
+different symbol than the @code{x} which was defined at the beginning of
+the program, altough both would appear as @samp{x} when printed.
+
+
+
+@node Extending GiNaC, What does not belong into GiNaC, Input/Output, Top