Although symbols can be assigned expressions for internal reasons, you
should not do it (and we are not going to tell you how it is done). If
you want to replace a symbol with something else in an expression, you
-can use the expression's @code{.subs()} method (@xref{Substituting Symbols},
+can use the expression's @code{.subs()} method (@xref{Substituting Expressions},
for more information).
Sometimes you will want to substitute one symbolic index with another
symbolic or numeric index, for example when calculating one specific element
of a tensor expression. This is done with the @code{.subs()} method, as it
-is done for symbols (see @ref{Substituting Symbols}).
+is done for symbols (see @ref{Substituting Expressions}).
You have two possibilities here. You can either substitute the whole index
by another index or expression:
@menu
* Information About Expressions::
-* Substituting Symbols::
+* Substituting Expressions::
* Polynomial Arithmetic:: Working with polynomials.
* Rational Expressions:: Working with rational functions.
* Symbolic Differentiation::
@end menu
-@node Information About Expressions, Substituting Symbols, Methods and Functions, Methods and Functions
+@node Information About Expressions, Substituting Expressions, Methods and Functions, Methods and Functions
@c node-name, next, previous, up
@section Getting information about expressions
expressions will give very surprising results.
-@node Substituting Symbols, Polynomial Arithmetic, Information About Expressions, Methods and Functions
+@node Substituting Expressions, Polynomial Arithmetic, Information About Expressions, Methods and Functions
@c node-name, next, previous, up
-@section Substituting symbols
+@section Substituting expressions
@cindex @code{subs()}
-Symbols can be replaced with expressions via the @code{.subs()} method:
+Algebraic objects inside expressions can be replaced with arbitrary
+expressions via the @code{.subs()} method:
@example
ex ex::subs(const ex & e);
@end example
In the first form, @code{subs()} accepts a relational of the form
-@samp{symbol == expression} or a @code{lst} of such relationals. E.g.
+@samp{object == expression} or a @code{lst} of such relationals:
@example
@{
symbol x("x"), y("y");
+
ex e1 = 2*x^2-4*x+3;
cout << "e1(7) = " << e1.subs(x == 7) << endl;
+ // -> 73
+
ex e2 = x*y + x;
cout << "e2(-2, 4) = " << e2.subs(lst(x == -2, y == 4)) << endl;
+ // -> -10
@}
@end example
-will print @samp{73} and @samp{-10}, respectively.
+@code{subs()} performs syntactic substitution of any complete algebraic
+object; it does not try to match sub-expressions as is demonstrated by the
+following example:
+
+@example
+@{
+ symbol x("x"), y("y"), z("z");
+
+ ex e1 = pow(x+y, 2);
+ cout << e1.subs(x+y == 4) << endl;
+ // -> 16
+
+ ex e2 = sin(x)*cos(x);
+ cout << e2.subs(sin(x) == cos(x)) << endl;
+ // -> cos(x)^2
+
+ ex e3 = x+y+z;
+ cout << e3.subs(x+y == 4) << endl;
+ // -> x+y+z
+ // (and not 4+z as one might expect)
+@}
+@end example
If you specify multiple substitutions, they are performed in parallel, so e.g.
@code{subs(lst(x == y, y == x))} exchanges @samp{x} and @samp{y}.
-The second form of @code{subs()} takes two lists, one for the symbols and
-one for the expressions to be substituted (both lists must contain the same
-number of elements). Using this form, you would write @code{subs(lst(x, y), lst(y, x))}
-to exchange @samp{x} and @samp{y}.
+The second form of @code{subs()} takes two lists, one for the objects to be
+replaced and one for the expressions to be substituted (both lists must
+contain the same number of elements). Using this form, you would write
+@code{subs(lst(x, y), lst(y, x))} to exchange @samp{x} and @samp{y}.
-@node Polynomial Arithmetic, Rational Expressions, Substituting Symbols, Methods and Functions
+@node Polynomial Arithmetic, Rational Expressions, Substituting Expressions, Methods and Functions
@c node-name, next, previous, up
@section Polynomial arithmetic
or even from run to run since the internal canonical ordering is not
within the user's sphere of influence.
+@code{degree()}, @code{ldegree()}, @code{coeff()}, @code{lcoeff()},
+@code{tcoeff()} and @code{collect()} can also be used to a certain degree
+with non-polynomial expressions as they not only work with symbols but with
+constants, functions and indexed objects as well:
+
+@example
+@{
+ symbol a("a"), b("b"), c("c");
+ idx i(symbol("i"), 3);
+
+ ex e = pow(sin(x) - cos(x), 4);
+ cout << e.degree(cos(x)) << endl;
+ // -> 4
+ cout << e.expand().coeff(sin(x), 3) << endl;
+ // -> -4*cos(x)
+
+ e = indexed(a+b, i) * indexed(b+c, i);
+ e = e.expand(expand_options::expand_indexed);
+ cout << e.collect(indexed(b, i)) << endl;
+ // -> a.i*c.i+(a.i+c.i)*b.i+b.i^2
+@}
+@end example
+
@subsection Polynomial division
@cindex polynomial division
@{
symbol x("x");
ex e = 4.5+pow(x,2)*3/2;
- cout << e << endl; // prints '4.5+3/2*x^2'
+ cout << e << endl; // prints '(4.5)+3/2*x^2'
// ...
@end example
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
+It is possible to print expressions in a number of different formats with
+the method
@example
-void ex::printcsrc(ostream & os, unsigned type, const char *name);
+void ex::print(const print_context & c, unsigned level = 0);
@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:
+The type of @code{print_context} object passed in determines the format
+of the output. The possible types are defined in @file{ginac/print.h}.
+All constructors of @code{print_context} and derived classes take an
+@code{ostream &} as their first argument.
+
+To print an expression in a way that can be directly used in a C or C++
+program, you pass a @code{print_csrc} object like this:
@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");
+ cout << "float f = ";
+ e.print(print_csrc_float(cout));
+ cout << ";\n";
+
+ cout << "double d = ";
+ e.print(print_csrc_double(cout));
+ cout << ";\n";
+
+ cout << "cl_N n = ";
+ e.print(print_csrc_cl_N(cout));
+ cout << ";\n";
// ...
@end example
+The three possible types mostly affect the way in which floating point
+numbers are written.
+
The above example will produce (note the @code{x^2} being converted to @code{x*x}):
@example
float f = (3.000000e+00/2.000000e+00)*(x*x)+4.500000e+00;
double d = (3.000000e+00/2.000000e+00)*(x*x)+4.500000e+00;
-cl_N n = (cl_F("3.0")/cl_F("2.0"))*(x*x)+cl_F("4.5");
+cl_N n = (cln::cl_F("3.0")/cln::cl_F("2.0"))*(x*x)+cln::cl_F("4.5");
@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:
+The @code{print_context} type @code{print_tree} provdes a dump of the
+internal structure of an expression for debugging purposes:
@example
// ...
- e.printraw(cout); cout << endl << endl;
- e.printtree(cout);
+ e.print(print_tree(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(3/2)),,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
- 3/2 (numeric): hash=2147483745 (0x80000061), flags=11
+add, hash=0x0, flags=0x3, nops=2
+ power, hash=0x9, flags=0x3, nops=2
+ x (symbol), serial=3, hash=0x44a113a6, flags=0xf
+ 2 (numeric), hash=0x80000042, flags=0xf
+ 3/2 (numeric), hash=0x80000061, flags=0xf
-----
overall_coeff
- 4.5L0 (numeric): hash=2147483723 (0x8000004b), flags=11
+ 4.5L0 (numeric), hash=0x8000004b, flags=0xf
=====
@end example
-The @code{printtree()} method is also available in @command{ginsh} as the
-@code{print()} function.
+This kind of output is also available in @command{ginsh} as the @code{print()}
+function.
+
+If you need any fancy special output format, e.g. for interfacing GiNaC
+with other algebra systems or for producing code for different
+programming languages, you can always traverse the expression tree yourself:
+
+@example
+static void my_print(const ex & e)
+@{
+ if (is_ex_of_type(e, function))
+ cout << ex_to_function(e).get_name();
+ else
+ cout << e.bp->class_name();
+ cout << "(";
+ unsigned n = e.nops();
+ if (n)
+ for (unsigned i=0; i<n; i++) @{
+ my_print(e.op(i));
+ if (i != n-1)
+ cout << ",";
+ @}
+ else
+ cout << e;
+ cout << ")";
+@}
+
+int main(void)
+@{
+ my_print(pow(3, x) - 2 * sin(y / Pi)); cout << endl;
+ return 0;
+@}
+@end example
+
+This will produce
+
+@example
+add(power(numeric(3),symbol(x)),mul(sin(mul(power(constant(Pi),numeric(-1)),
+symbol(y))),numeric(-2)))
+@end example
+
+If you need an output format that makes it possible to accurately
+reconstruct an expression by feeding the output to a suitable parser or
+object factory, you should consider storing the expression in an
+@code{archive} object and reading the object properties from there.
+See the section on archiving for more information.
@subsection Expression input
different symbol than the @code{x} which was defined at the beginning of
the program, altough both would appear as @samp{x} when printed.
+You can also use the information stored in an @code{archive} object to
+output expressions in a format suitable for exact reconstruction. The
+@code{archive} and @code{archive_node} classes have a couple of member
+functions that let you access the stored properties:
+
+@example
+static void my_print2(const archive_node & n)
+@{
+ string class_name;
+ n.find_string("class", class_name);
+ cout << class_name << "(";
+
+ archive_node::propinfovector p;
+ n.get_properties(p);
+
+ unsigned num = p.size();
+ for (unsigned i=0; i<num; i++) @{
+ const string &name = p[i].name;
+ if (name == "class")
+ continue;
+ cout << name << "=";
+
+ unsigned count = p[i].count;
+ if (count > 1)
+ cout << "@{";
+
+ for (unsigned j=0; j<count; j++) @{
+ switch (p[i].type) @{
+ case archive_node::PTYPE_BOOL: @{
+ bool x;
+ n.find_bool(name, x);
+ cout << (x ? "true" : "false");
+ break;
+ @}
+ case archive_node::PTYPE_UNSIGNED: @{
+ unsigned x;
+ n.find_unsigned(name, x);
+ cout << x;
+ break;
+ @}
+ case archive_node::PTYPE_STRING: @{
+ string x;
+ n.find_string(name, x);
+ cout << '\"' << x << '\"';
+ break;
+ @}
+ case archive_node::PTYPE_NODE: @{
+ const archive_node &x = n.find_ex_node(name, j);
+ my_print2(x);
+ break;
+ @}
+ @}
+
+ if (j != count-1)
+ cout << ",";
+ @}
+
+ if (count > 1)
+ cout << "@}";
+
+ if (i != num-1)
+ cout << ",";
+ @}
+
+ cout << ")";
+@}
+
+int main(void)
+@{
+ ex e = pow(2, x) - y;
+ archive ar(e, "e");
+ my_print2(ar.get_top_node(0)); cout << endl;
+ return 0;
+@}
+@end example
+
+This will produce:
+
+@example
+add(rest=@{power(basis=numeric(number="2"),exponent=symbol(name="x")),
+symbol(name="y")@},coeff=@{numeric(number="1"),numeric(number="-1")@},
+overall_coeff=numeric(number="0"))
+@end example
+
+Be warned, however, that the set of properties and their meaning for each
+class may change between GiNaC versions.
@node Extending GiNaC, What does not belong into GiNaC, Input/Output, Top
@{
...
public:
- void print(ostream &os, unsigned upper_precedence) const;
+ void print(const print_context &c, unsigned level = 0) const;
...
@};
-void mystring::print(ostream &os, unsigned upper_precedence) const
+void mystring::print(const print_context &c, unsigned level) const
@{
- os << '\"' << str << '\"';
+ // print_context::s is a reference to an ostream
+ c.s << '\"' << str << '\"';
@}
@end example
-The @code{upper_precedence} argument is only required for container classes
-to correctly parenthesize the output. Let's try again to print the expression:
+The @code{level} argument is only required for container classes to
+correctly parenthesize the output. Let's try again to print the expression:
@example
cout << e << endl;
git://www.ginac.de / ginac.git / blobdiff