/** @page libsbml-math Working with mathematical expressions

This section describes libSBML's facilities for working with SBML
representations of mathematical expressions.

@section math-overview Basic concepts

LibSBML uses <a target="_blank"
href="http://en.wikipedia.org/wiki/Abstract_syntax_tree">Abstract Syntax
Trees</a> (ASTs) to provide a canonical, in-memory representation for all
mathematical formulas regardless of their original format (i.e., C-like infix
strings or <a target="_blank"
href="http://www.w3.org/TR/MathML2/">MathML&nbsp;2.0</a>).  In libSBML, an
AST is a collection of one or more objects of class ASTNode.

@copydetails doc_what_is_astnode

@section math-convert Converting between ASTs and text strings

SBML Levels 2 and 3 represent mathematical expressions using using <a
href="http://www.w3.org/Math/">MathML&nbsp;2.0</a> (more specifically, a
subset of the <em>content</em> portion of MathML&nbsp;2.0), but most
applications using libSBML do not use MathML directly.  Instead, applications
generally either interact with mathematics in text-string form, or else they
use the API for working with Abstract Syntax Trees (described below).
LibSBML provides support for both approaches.  The libSBML formula parser has
been carefully engineered so that transformations from MathML to infix string
notation <em>and back</em> is possible with a minimum of disruption to the
structure of the mathematical expression.

The example below shows a simple program that, when run, takes a MathML
string compiled into the program, converts it to an AST, converts
<em>that</em> to an infix representation of the formula, compares it to the
expected form of that formula, and finally translates that formula back to
MathML and displays it.  The output displayed on the terminal should have
the same structure as the MathML it started with.  The program is a simple
example of using the various MathML and AST reading and writing methods,
and shows that libSBML preserves the ordering and structure of the
mathematical expressions.

<a class="anchor" name="example-program">
<!--
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~ C++ version ~~~~~~~~~~~~~~~~~~~~~~~~~~~
-->
@if cpp
@verbatim
#include <iostream>
#include <sbml/SBMLTypes.h>

int
main (int argc, char *argv[])
{
  const char* expected = "1 + f(x)";

  const char* s = "<?xml version='1.0' encoding='UTF-8'?>"
    "<math xmlns='http://www.w3.org/1998/Math/MathML'>"
    "  <apply> <plus/> <cn> 1 </cn>"
    "                  <apply> <ci> f </ci> <ci> x </ci> </apply>"
    "  </apply>"
    "</math>";

  ASTNode* ast    = readMathMLFromString(s);
  char*    result = SBML_formulaToString(ast);

  if ( strcmp(result, expected) == 0 )
    cout << "Got expected result" << endl;
  else
    cout << "Mismatch after readMathMLFromString()" << endl;

  ASTNode* new_mathml = SBML_parseFormula(result);
  char*    new_s      = writeMathMLToString(new_mathml);

  cout << "Result of writing AST:" << endl << new_s << endl;
}
@endverbatim
@endif
<!--
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~ C version ~~~~~~~~~~~~~~~~~~~~~~~~~~~
-->
@if conly
@verbatim
NEED A C VERSION HERE ...
@endverbatim
@endif
<!--
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~ Python version ~~~~~~~~~~~~~~~~~~~~~~~~~~
-->
@if python
@verbatim
import libsbml

expected = "1 + f(x)"

xml = "<?xml version='1.0' encoding='UTF-8'?>"\
      "<math xmlns='http://www.w3.org/1998/Math/MathML'>"\
      "  <apply> <plus/> <cn> 1 </cn>"\
      "                  <apply> <ci> f </ci> <ci> x </ci> </apply>"\
      "  </apply>"\
      "</math>"

ast    = libsbml.readMathMLFromString(xml)
result = libsbml.formulaToString(ast)

if (result == text):
    print "Got expected result"
else:
    print "Mismatch after readMathMLFromString()"

new_mathml = libsbml.parseFormula(result)
new_string = libsbml.writeMathMLToString(new_mathml)

print "Result of writing AST to string: "
print new_string
@endverbatim
@endif

The text-string form of mathematical formulas produced by
@if clike SBML_formulaToString() and read by SBML_parseFormula() and
SBML_parseL3Formula()@endif@if python libsbml.formulaToString() and
read by libsbml.parseFormula()@endif@~ are in a simple C-inspired infix
notation.  It is summarized in the next section below.  A formula in this
text-string form therefore can be handed to a program that understands SBML
mathematical expressions, or used as part of a translation system.  The
libSBML distribution comes with an example program in the @c "examples"
subdirectory called @c translateMath that implements an interactive
command-line demonstration of translating infix formulas into MathML and
vice-versa.  In summary, the functions available are the following:

<!--
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~ C++ and C version ~~~~~~~~~~~~~~~~~~~~~~~~~~
-->
@if clike
@li <code>char * @link SBML_formulaToString(const ASTNode_t* tree)
SBML_formulaToString(const ASTNode* tree) @endlink</code> reads an
AST, converts it to a text string in SBML Level&nbsp;1 formula syntax, and
returns it.  The caller owns the character string returned and should free
it after it is no longer needed.
@li <code>ASTNode * SBML_parseFormula(const char* formula)</code> reads a
text-string containing a mathematical expression in SBML Level&nbsp;1 syntax and
returns an AST corresponding to the expression.
@li <code>ASTNode * SBML_parseL3Formula(const char* formula)</code> reads a
reads a text-string containing a mathematical expression in
an expanded syntax more compatible with SBML Levels&nbsp;2 and&nbsp;3,
and returns an AST corresponding to the expression.
@endif
<!--
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~ Python version ~~~~~~~~~~~~~~~~~~~~~~~~~~
-->
@if python
@li @link formulaToString()
<code>libsbml.formulaToString(ASTNode)</code>@endlink
reads an AST, converts it to a text string in SBML Level&nbsp;1 formula
syntax, and returns a string.  The caller owns the character string
returned and should free it after it is no longer needed.
@li @link parseFormula() <code>libsbml.parseFormula(string)</code>@endlink
reads a text-string containing a mathematical expression in
SBML Level&nbsp;1 syntax, and returns an @c ASTNode object corresponding
to the expression.
@li @link parseL3Formula() <code>libsbml.parseL3Formula(string)</code>@endlink
reads a text-string containing a mathematical expression in
an expanded syntax more compatible with SBML Levels&nbsp;2 and&nbsp;3,
and returns an ASTNode object corresponding to the expression.
@endif


@section math-diffs The string formula syntax and differences with MathML

The text-string formula syntax is an infix notation essentially derived
from the syntax of the C programming language and was originally used in
SBML Level&nbsp;1.  The formula strings may contain operators, function
calls, symbols, and white space characters.  The allowable white space
characters are tab and space.  The following are illustrative examples of
formulas expressed in the syntax:

@verbatim
0.10 * k4^2
@endverbatim
@verbatim
(vm * s1)/(km + s1)
@endverbatim

The following table shows the precedence rules in this syntax.  In the
Class column, @em operand implies the construct is an operand, @em prefix
implies the operation is applied to the following arguments, @em unary
implies there is one argument, and @em binary implies there are two
arguments.  The values in the Precedence column show how the order of
different types of operation are determined.  For example, the expression
<code>a * b + c</code> is evaluated as <code>(a * b) + c</code> because the
@c * operator has higher precedence.  The Associates column shows how the
order of similar precedence operations is determined; for example, 
<code>a - b + c</code> is evaluated as <code>(a - b) + c</code> because the
@c + and @c - operators are left-associative.  The precedence and associativity
rules are taken from the C programming language, except for the symbol @c
^, which is used in C for a different purpose.  (Exponentiation can be
invoked using either @c ^ or the function @c power.)

@htmlinclude math-precedence-table.html

A program parsing a formula in an SBML model should assume that names
appearing in the formula are the identifiers of Species, Parameter,
Compartment, FunctionDefinition, (in Level&nbsp;2) Reaction, or (in
Level&nbsp;3) SpeciesReference objects defined in a model.
When a function call is involved, the syntax consists of a function
identifier, followed by optional white space, followed by an opening
parenthesis, followed by a sequence of zero or more arguments separated by
commas (with each comma optionally preceded and/or followed by zero or more
white space characters), followed by a closing parenthesis.  There is an
almost one-to-one mapping between the list of predefined functions
available, and those defined in MathML.  All of the MathML functions are
recognized; this set is larger than the functions defined in SBML Level&nbsp;1.
In the subset of functions that overlap between MathML and SBML Level&nbsp;1,
there exist a few differences.  The following table summarizes the
differences between the predefined functions in SBML Level&nbsp;1 and the MathML
equivalents in SBML Levels&nbsp;2 and&nbsp;3:

@htmlinclude math-functions.html

@section math-ast Methods for working with libSBML's Abstract Syntax Trees

@copydetails doc_astnode_types

There are a number of methods for interrogating the type of an ASTNode and
for testing whether a node belongs to a general category of constructs.
The methods on ASTNode for this purpose are the following:

<!--
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~ C++ version ~~~~~~~~~~~~~~~~~~~~~~~~~~
-->
@if cpp
@li <code>ASTNodeType_t @link ASTNode::getType() getType() @endlink</code>
returns the type of this AST node.
@li <code>bool @link ASTNode::isConstant() isConstant() @endlink</code>
returns @c true if this AST node is a MathML constant (@c true, @c false,
@c pi, @c exponentiale), @c false otherwise.
@li <code>bool @link ASTNode::isBoolean() isBoolean() @endlink</code>
returns @c true if this AST node returns a boolean value (by being either a
logical operator, a relational operator, or the constant @c true or @c
false).
@li <code>bool @link ASTNode::isFunction() isFunction() @endlink</code>
returns @c true if this AST node is a function (i.e., a MathML defined
function such as @c exp or else a function defined by a FunctionDefinition
in the Model).
@li <code>bool @link ASTNode::isInfinity() isInfinity() @endlink</code>
returns @c true if this AST node is the special IEEE 754 value infinity.
@li <code>bool @link ASTNode::isInteger() isInteger() @endlink</code>
returns @c true if this AST node is holding an integer value.
@li <code>bool @link ASTNode::isNumber() isNumber() @endlink</code> returns
@c true if this AST node is holding any number.
@li <code>bool @link ASTNode::isLambda() isLambda() @endlink</code> returns
@c true if this AST node is a MathML @c lambda construct.
@li <code>bool @link ASTNode::isLog10() isLog10() @endlink</code> returns
@c true if this AST node represents the @c log10 function, specifically,
that its type is @c AST_FUNCTION_LOG and it has two children, the first of
which is an integer equal to 10.
@li <code>bool @link ASTNode::isLogical() isLogical() @endlink</code>
returns @c true if this AST node is a logical operator (@c and, @c or, @c
not, @c xor).
@li <code>bool @link ASTNode::isName() isName() @endlink</code> returns @c
true if this AST node is a user-defined name or (in SBML Levels&nbsp;2
and&nbsp;3) one of the two special @c csymbol constructs "delay" or "time".
@li <code>bool @link ASTNode::isNaN() isNaN() @endlink</code> returns @c
true if this AST node has the special IEEE 754 value "not a number" (NaN).
@li <code>bool @link ASTNode::isNegInfinity() isNegInfinity()
@endlink</code> returns @c true if this AST node has the special IEEE 754
value of negative infinity.
@li <code>bool @link ASTNode::isOperator() isOperator() @endlink</code>
returns @c true if this AST node is an operator (e.g., @c +, @c -, etc.)
@li <code>bool @link ASTNode::isPiecewise() isPiecewise() @endlink</code>
returns @c true if this AST node is the MathML @c piecewise function.
@li <code>bool @link ASTNode::isRational() isRational() @endlink</code>
returns @c true if this AST node is a rational number having a numerator
and a denominator.
@li <code>bool @link ASTNode::isReal() isReal() @endlink</code> returns @c
true if this AST node is a real number (specifically, @c AST_REAL_E or
@c AST_RATIONAL).
@li <code>bool @link ASTNode::isRelational() isRelational() @endlink</code>
returns @c true if this AST node is a relational operator.
@li <code>bool @link ASTNode::isSqrt() isSqrt() @endlink</code> returns @c
true if this AST node is the square-root operator
@li <code>bool @link ASTNode::isUMinus() isUMinus() @endlink</code> returns
@c true if this AST node is a unary minus.
@li <code>bool @link ASTNode::isUnknown() isUnknown() @endlink</code>
returns @c true if this AST node's type is unknown.
@endif
<!--
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~ C version ~~~~~~~~~~~~~~~~~~~~~~~~~~
-->
@if conly
@li <code>ASTNodeType_t ASTNode_getType()</code>
returns the type of this AST node.
@li <code>bool ASTNode_isConstant()</code>
returns @c 1 if this AST node is a MathML constant (@c true, @c false,
@c pi, @c exponentiale), @c 0 otherwise.
@li <code>bool ASTNode_isBoolean()</code>
returns @c 1 if this AST node returns a boolean value (by being either a
logical operator, a relational operator, or the constant @c true or @c
false).
@li <code>bool ASTNode_isFunction()</code>
returns @c 1 if this AST node is a function (i.e., a MathML defined
function such as @c exp or else a function defined by a FunctionDefinition
in the Model).
@li <code>bool ASTNode_isInfinity()</code>
returns @c 1 if this AST node is the special IEEE 754 value infinity.
@li <code>bool ASTNode_isInteger()</code>
returns @c 1 if this AST node is holding an integer value.
@li <code>bool ASTNode_isNumber()</code> returns
@c 1 if this AST node is holding any number.
@li <code>bool ASTNode_isLambda()</code> returns
@c 1 if this AST node is a MathML @c lambda construct.
@li <code>bool ASTNode_isLog10()</code> returns
@c 1 if this AST node represents the @c log10 function, specifically,
that its type is @c AST_FUNCTION_LOG and it has two children, the first of
which is an integer equal to 10.
@li <code>bool ASTNode_isLogical()</code>
returns @c 1 if this AST node is a logical operator (@c and, @c or, @c
not, @c xor).
@li <code>bool ASTNode_isName()</code> returns @c
true if this AST node is a user-defined name or (in SBML Levels&nbsp;2
and&nbsp;3) one of the two special @c csymbol constructs "delay" or "time".
@li <code>bool ASTNode_isNaN()</code> returns @c
true if this AST node has the special IEEE 754 value "not a number" (NaN).
@li <code>bool ASTNode_isNegInfinity()</code> returns @c 1 if this AST node has the special IEEE 754
value of negative infinity.
@li <code>bool ASTNode_isOperator()</code>
returns @c 1 if this AST node is an operator (e.g., @c +, @c -, etc.)
@li <code>bool ASTNode_isPiecewise()</code>
returns @c 1 if this AST node is the MathML @c piecewise function.
@li <code>bool ASTNode_isRational()</code>
returns @c 1 if this AST node is a rational number having a numerator
and a denominator.
@li <code>bool ASTNode_isReal()</code> returns @c
true if this AST node is a real number (specifically, @c AST_REAL_E or
@c AST_RATIONAL).
@li <code>bool ASTNode_isRelational()</code>
returns @c 1 if this AST node is a relational operator.
@li <code>bool ASTNode_isSqrt()</code> returns @c
true if this AST node is the square-root operator
@li <code>bool ASTNode_isUMinus()</code> returns
@c 1 if this AST node is a unary minus.
@li <code>bool ASTNode_isUnknown()</code>
returns @c 1 if this AST node's type is unknown.
@endif
<!--
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~ Python version ~~~~~~~~~~~~~~~~~~~~~~~~~~
-->
@if python
@li <code>long</code> @link libsbml.ASTNode.getType() ASTNode.getType()@endlink returns the type of
this AST node.
@li <code>bool</code> @link libsbml.ASTNode.isConstant() ASTNode.isConstant()@endlink returns @c True if this
AST node is a MathML constant (@c True, @c False, @c pi, @c exponentiale),
@c False otherwise.
@li <code>bool</code> @link libsbml.ASTNode.isBoolean() ASTNode.isBoolean()@endlink returns @c True if this
AST node returns a boolean value (by being either a logical operator, a
relational operator, or the constant @c True or @c False).
@li <code>bool</code> @link libsbml.ASTNode.isFunction() ASTNode.isFunction()@endlink returns @c True if this
AST node is a function (i.e., a MathML defined function such as @c exp or
else a function defined by a FunctionDefinition in the Model).
@li <code>bool</code> @link libsbml.ASTNode.isInfinity() ASTNode.isInfinity()@endlink returns @c True if this
AST node is the special IEEE 754 value infinity.
@li <code>bool</code> @link libsbml.ASTNode.isInteger() ASTNode.isInteger()@endlink returns @c True if this
AST node is holding an integer value.
@li <code>bool</code> @link libsbml.ASTNode.isNumber() ASTNode.isNumber()@endlink  returns @c True if this
AST node is holding any number.
@li <code>bool</code> @link libsbml.ASTNode.isLambda() ASTNode.isLambda()@endlink  returns @c True if this
AST node is a MathML @c lambda construct.
@li <code>bool</code> @link libsbml.ASTNode.isLog10() ASTNode.isLog10()@endlink  returns @c True if this
AST node represents the @c log10 function, specifically, that its type is
@c AST_FUNCTION_LOG and it has two children, the first of which is an integer
equal to 10.
@li <code>bool</code> @link libsbml.ASTNode.isLogical() ASTNode.isLogical()@endlink  returns @c True if this
AST node is a logical operator (@c and, @c or, @c not, @c xor).
@li <code>bool</code> @link libsbml.ASTNode.isName() ASTNode.isName()@endlink  returns @c True if this
AST node is a user-defined name or (in SBML Level 2) one of the two special
@c csymbol constructs "delay" or "time".
@li <code>bool</code> @link libsbml.ASTNode.isNaN() ASTNode.isNaN()@endlink  returns @c True if this
AST node has the special IEEE 754 value "not a number" (NaN).
@li <code>bool</code> @link libsbml.ASTNode.isNegInfinity() ASTNode.isNegInfinity()@endlink  returns @c True if this
AST node has the special IEEE 754 value of negative infinity.
@li <code>bool</code> @link libsbml.ASTNode.isOperator() ASTNode.isOperator()@endlink  returns @c True if this
AST node is an operator (e.g., <code>+</code>, <code>-</code>, etc.)
@li <code>bool</code> @link libsbml.ASTNode.isPiecewise() ASTNode.isPiecewise()@endlink  returns @c True if this
AST node is the MathML @c piecewise function.
@li <code>bool</code> @link libsbml.ASTNode.isRational() ASTNode.isRational()@endlink  returns @c True if this
AST node is a rational number having a numerator and a denominator.
@li <code>bool</code> @link libsbml.ASTNode.isReal() ASTNode.isReal()@endlink  returns @c True if this
AST node is a real number (specifically, @c AST_REAL_E or @c AST_RATIONAL).
@li <code>bool</code> @link libsbml.ASTNode.isRelational() ASTNode.isRelational()@endlink  returns @c True if this
AST node is a relational operator.
@li <code>bool</code> @link libsbml.ASTNode.isSqrt() ASTNode.isSqrt()@endlink  returns @c True if this
AST node is the square-root operator
@li <code>bool</code> @link libsbml.ASTNode.isUMinus() ASTNode.isUMinus()@endlink  returns @c True if this
AST node is a unary minus.
@li <code>bool</code> @link libsbml.ASTNode.isUnknown() ASTNode.isUnknown()@endlink  returns @c True if this
AST node's type is unknown.
@endif


Programs manipulating AST node structures should check the type of a given
node before calling methods that return a value from the node.  The
following are the ASTNode object methods available for returning values
from nodes:

<!--
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~ C++ version ~~~~~~~~~~~~~~~~~~~~~~~~~~
-->
@if cpp
@li <code>long @link ASTNode::getInteger() getInteger() @endlink</code> 
@li <code>char @link ASTNode::getCharacter() getCharacter() @endlink</code> 
@li <code>const char* @link ASTNode::getName() getName() @endlink</code> 
@li <code>long @link ASTNode::getNumerator() getNumerator() @endlink</code> 
@li <code>long @link ASTNode::getDenominator() getDenominator()
@endlink</code>
@li <code>double @link ASTNode::getReal() getReal() @endlink</code> 
@li <code>double @link ASTNode::getMantissa() getMantissa() @endlink</code> 
@li <code>long @link ASTNode::getExponent() getExponent() @endlink</code> 
@endif
<!--
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~ C version ~~~~~~~~~~~~~~~~~~~~~~~~~~
-->
@if conly
@if cpp
@li <code>long ASTNode_getInteger()</code> 
@li <code>char ASTNode_getCharacter()</code> 
@li <code>const char* ASTNode_getName()</code> 
@li <code>long ASTNode_getNumerator()</code> 
@li <code>long ASTNode_getDenominator()</code>
@li <code>double ASTNode_getReal()</code> 
@li <code>double ASTNode_getMantissa()</code> 
@li <code>long ASTNode_getExponent()</code> 
@endif
@endif
<!--
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~ Python version ~~~~~~~~~~~~~~~~~~~~~~~~~~
-->
@if python
@li <code>long</code> @link libsbml.ASTNode.getInteger() ASTNode.getInteger()@endlink 
@li <code>char</code> @link libsbml.ASTNode.getCharacter() ASTNode.getCharacter()@endlink 
@li <code>string</code> @link libsbml.ASTNode.getName() ASTNode.getName()@endlink 
@li <code>long</code> @link libsbml.ASTNode.getNumerator() ASTNode.getNumerator()@endlink 
@li <code>long</code> @link libsbml.ASTNode.getDenominator() ASTNode.getDenominator()@endlink 
@li <code>float</code> @link libsbml.ASTNode.getReal() ASTNode.getReal()@endlink 
@li <code>float</code> @link libsbml.ASTNode.getMantissa() ASTNode.getMantissa()@endlink 
@li <code>long</code> @link libsbml.ASTNode.getExponent() ASTNode.getExponent()@endlink 
@endif


Of course, all of this would be of little use if libSBML didn't also
provide methods for @em setting the values of AST node objects!  And it
does.  The methods are the following:

<!--
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~ C++ version ~~~~~~~~~~~~~~~~~~~~~~~~~~
-->
@if cpp
@li <code>void @link ASTNode::setCharacter(char value) setCharacter(char
value) @endlink</code> sets the value of this ASTNode to the given
character <code>value</code>.  If character is one of @c +, @c -, @c *, @c
/ or @c ^, the node type will be to the appropriate operator type.  For all
other characters, the node type will be set to @c AST_UNKNOWN.
@li <code>void @link ASTNode::setName(const char *name) setName(const char
*name) @endlink</code> sets the value of this AST node to the given
<code>name</code>.  The node type will be set (to @c AST_NAME) <em>only
if</em> the AST node was previously an operator (<code>isOperator(node) !=
0</code>) or number (<code>isNumber(node) != 0</code>).  This allows names
to be set for @c AST_FUNCTIONs and the like.
@li <code>void @link ASTNode::setValue(int value) setValue(int value)
@endlink</code> sets the value of the node to the given integer
<code>value</code>.  Equivalent to the next method.
@li <code>void @link ASTNode::setValue(long value) setValue(long value)
@endlink</code> sets the value of the node to the given integer
<code>value</code>.  Equivalent to the previous method.  No, this is not a
G&ouml;delian self-referential loop.
@li <code>void @link ASTNode::setValue(long numerator, long denominator)
setValue(long numerator, long denominator) @endlink</code> sets the value
of this ASTNode to the given rational <code>value</code> in two parts: the
numerator and denominator.  The node type is set to @c AST_RATIONAL.
@li <code>void @link ASTNode::setValue(double value) setValue(double value)
@endlink</code> sets the value of this ASTNode to the given real (double)
<code>value</code> and sets the node type to @c AST_REAL.
@li <code>void @link ASTNode::setValue(double mantissa, long exponent)
setValue(double mantissa, long exponent) @endlink</code> sets the value of
this ASTNode to a real (double) using the two parts given: the mantissa and
the exponent.  The node type is set to @c AST_REAL_E.
@endif
<!--
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~ C version ~~~~~~~~~~~~~~~~~~~~~~~~~~
-->
@if conly
@li <code>void ASTNode_setCharacter(ASTNode_t *node, char value)</code> sets the value of this
ASTNode to the given character <code>value</code>.  If character is one of @c
+, @c -, @c *, @c / or @c ^, the node type will be to the appropriate
operator type.  For all other characters, the node type will be set to @c
AST_UNKNOWN.
@li <code>void ASTNode_setName(ASTNode_t *node, const char *name)</code> sets the value of
this AST node to the given <code>name</code>.  The node type will be set (to
@c AST_NAME) <em>only if</em> the AST node was previously an operator
(<code>isOperator(node) != 0</code>) or number (<code>isNumber(node) !=
0</code>).  This allows names to be set for @c AST_FUNCTIONs and the like.
@li <code>void ASTNode_setInteger(ASTNode_t *node, long value)</code> sets the value of the node
to the given integer <code>value</code>.  
@li <code>void ASTNode_setRational(ASTNode_t *node, long numerator, long denominator)</code> sets
the value of this ASTNode to the given rational <code>value</code> in two
parts: the numerator and denominator.  The node type is set to @c
AST_RATIONAL.
@li <code>void ASTNode_setReal(ASTNode_t *node, double value)</code> sets the value of this
ASTNode to the given real (double) <code>value</code> and sets the node type
to @c AST_REAL.
@li <code>void ASTNode_setRealWithExponent(ASTNode_t *node, double mantissa, long exponent)</code> sets
the value of this ASTNode to a real (double) using the two parts given: the
mantissa and the exponent.  The node type is set to @c AST_REAL_E.
@endif
<!--
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~ Python version ~~~~~~~~~~~~~~~~~~~~~~~~~~
-->
@if python
@li @link libsbml.ASTNode.setCharacter() ASTNode.setCharacter(char)@endlink
sets the value of this ASTNode to the given character.  If character is one
of @c +, @c -, @c *, @c / or @c ^, the node type will be to the appropriate
operator type.  For all other characters, the node type will be set to @c
AST_UNKNOWN.
@li @link libsbml.ASTNode.setName() ASTNode.setName(string)@endlink sets the
value of this AST node to the given name.  The node type will be set (to @c
AST_NAME) <em>only if</em> the AST node was previously an operator
(<code>isOperator(node) != 0</code>) or number (<code>isNumber(node) !=
0</code>).  This allows names to be set for @c AST_FUNCTIONs and the like.
@li @link libsbml.ASTNode.setValue() ASTNode.setValue(int)@endlink sets the
value of the node to the given integer.  Equivalent to the next method.
@li @link libsbml.ASTNode.setValue() ASTNode.setValue(long)@endlink sets the
value of the node to the given integer.
@li @link libsbml.ASTNode.setValue() ASTNode.setValue(long, long)@endlink
sets the value of this ASTNode to the given rational in two parts: the
numerator and denominator.  The node type is set to @c AST_RATIONAL.
@li @link libsbml.ASTNode.setValue() ASTNode.setValue(float)@endlink sets the
value of this ASTNode to the given real (float) and sets the node type to @c
AST_REAL.
@li @link libsbml.ASTNode.setValue() ASTNode.setValue(float, long)@endlink
sets the value of this ASTNode to the given real (float) in two parts: the
mantissa and the exponent.  The node type is set to @c AST_REAL_E.
@endif


Finally, ASTNode also defines some miscellaneous methods for manipulating
ASTs:

<!--
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~ C++ version ~~~~~~~~~~~~~~~~~~~~~~~~~~
-->
@if cpp
@li <code>ASTNode* @link ASTNode::ASTNode(ASTNodeType_t type)
ASTNode(ASTNodeType_t type) @endlink</code> creates a new ASTNode object
and returns a pointer to it.  The returned node will have the given
<code>type</code>, or a type of @c AST_UNKNOWN if no argument
<code>type</code> is explicitly given or the type code is unrecognized.
@li <code>unsigned int @link ASTNode::getNumChildren() getNumChildren()
@endlink</code> returns the number of children of this AST node or
<code>0</code> is this node has no children.
@li <code>void @link ASTNode::addChild(ASTNode* child) addChild(ASTNode*
child) @endlink</code> adds the given node as a child of this AST node.
Child nodes are added in left-to-right order.
@li <code>void @link ASTNode::prependChild(ASTNode* child)
prependChild(ASTNode* child) @endlink</code> adds the given node as a child
of this AST node.  This method adds child nodes in right-to-left order.
@li <code>ASTNode* @link ASTNode::getChild() getChild(unsigned int n)
 @endlink</code> returns the <code>n</code>th child of this
AST node or @c NULL if this node has no <code>n</code>th child [i.e., if
<code>n &gt; (node->getNumChildren() - 1)</code>, where <code>node</code>
is a pointer to a node].
@li <code>ASTNode* @link ASTNode::getLeftChild() getLeftChild()
@endlink</code> returns the left child of this AST node.  This is
equivalent to <code>getChild(0)</code>.
@li <code>ASTNode* @link ASTNode::getRightChild() getRightChild()
@endlink</code> returns the right child of this AST node or @c NULL if this
node has no right child.
@li <code>void @link ASTNode::swapChildren(ASTNode *that)
swapChildren(ASTNode *that) @endlink</code> swaps the children of this
ASTNode with the children of @c that ASTNode.
@li <code>void @link ASTNode::setType(ASTNodeType_t type)
setType(ASTNodeType_t type) @endlink</code> sets the type of this ASTNode
to the given <a href="_a_s_t_node_8h.html">ASTNodeType_t</a>
 enumeration value.
@endif
<!--
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~ C version ~~~~~~~~~~~~~~~~~~~~~~~~~~
-->
@if conly
@li <code>ASTNode_t* ASTNode_createWithType(ASTNodeType_t type)</code> creates a new
ASTNode object and returns a pointer to it.  The returned node will have the
given <code>type</code>, or a type of @c AST_UNKNOWN if no argument
<code>type</code> is explicitly given or the type code is unrecognized.
@li <code>unsigned int ASTNode_getNumChildren(const ASTNode_t *node)</code> returns the number of
children of this AST node or <code>0</code> is this node has no children.
@li <code>void ASTNode_addChild(ASTNode_t *node, ASTNode_t* child)</code> adds the given node as
a child of this AST node.  Child nodes are added in left-to-right order.
@li <code>void ASTNode_prependChild(ASTNode_t *node, ASTNode_t* child)</code> adds the given
node as a child of this AST node.  This method adds child nodes in
right-to-left order.
@li <code>ASTNode_t* ASTNode_getChild (const ASTNode_t *node, unsigned int n)</code> returns the
<code>n</code>th child of this AST node or @c NULL if this node has no
<code>n</code>th child [i.e., if <code>n &gt; (node->getNumChildren() -
1)</code>, where <code>node</code> is a pointer to a node].
@li <code>ASTNode_t* ASTNode_getLeftChild(const ASTNode_t *node)</code> returns the left child of
this AST node.  This is equivalent to <code>getChild(0)</code>.
@li <code>ASTNode_t* ASTNode_getRightChild(const ASTNode_t *node)</code> returns the right child of
this AST node or @c NULL if this node has no right child.
@li <code>void ASTNode_swapChildren(ASTNode_t *node, ASTNode *that)</code> swaps the children
of this ASTNode with the children of @c that ASTNode.
@li <code>void ASTNode_setType(ASTNode_t *node, ASTNodeType_t type)</code> sets the type of
this ASTNode to the given <a href="_a_s_t_node_8h.html">ASTNodeType_t</a>
enumeration value.
@endif
<!--
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~ Python version ~~~~~~~~~~~~~~~~~~~~~~~~~~
-->
@if python
@li <code>ASTNode</code> @link libsbml.ASTNode ASTNode.ASTNode(long)@endlink creates a new ASTNode object
and returns a pointer to it.  The returned node will have the type
identified by the code passed as the argument, or a type of @c AST_UNKNOWN if
no type is explicitly given or the type code is unrecognized.
@li <code>unsigned int</code> @link libsbml.ASTNode.getNumChildren() ASTNode.getNumChildren()@endlink returns the number
of children of this AST node or 0 is this node has no children.
@li @link libsbml.ASTNode.addChild() ASTNode.addChild(ASTNode)@endlink adds the given node
as a child of this AST node.  Child nodes are added in left-to-right order.
@li @link libsbml.ASTNode.prependChild() ASTNode.prependChild(ASTNode)@endlink adds the given
node as a child of this AST node.  This method adds child nodes in
right-to-left order.
@li <code>ASTNode</code> @link libsbml.ASTNode.getChild () ASTNode.getChild (unsigned int)@endlink returns the nth
child of this AST node or @c NULL if this node has no nth child (<code>n &gt;
(@link libsbml.ASTNode.getNumChildren() ASTNode.getNumChildren()@endlink - 1)</code>).
@li <code>ASTNode</code> @link libsbml.ASTNode.getLeftChild() ASTNode.getLeftChild()@endlink returns the left child of
this AST node.  This is equivalent to @link libsbml.ASTNode.getChild() ASTNode.getChild()@endlink;
@li <code>ASTNode</code> @link libsbml.ASTNode.getRightChild() ASTNode.getRightChild()@endlink
returns the right child of this AST node or @c NULL if this node has no right
child.
@li @link libsbml.ASTNode.swapChildren() ASTNode.swapChildren(ASTNode)@endlink swaps the
children of this ASTNode with the children of @c that ASTNode.
@li @link libsbml.ASTNode.setType() ASTNode.setType(long)@endlink
sets the type of this ASTNode to the type identified by the
type code passed as argument, or to @c AST_UNKNOWN if the type
is unrecognized.
@endif



@section math-reading Reading and Writing Mathematical Expressions into ASTs

As mentioned above, applications often can avoid working with raw MathML by
using either libSBML's text-string interface or the AST API.  However, when
needed, reading MathML content directly and creating ASTs is easily done in
libSBML using a method designed for this purpose:

@if cpp
@li <code>ASTNode* readMathMLFromString(const char* xml)</code> reads raw
MathML from a text string, constructs an AST from it, then returns the root
ASTNode of the resulting expression tree.
@endif
@if conly
@li <code>ASTNode_t* readMathMLFromString(const char* xml)</code> reads raw
MathML from a text string, constructs an AST from it, then returns the root
ASTNode_t of the resulting expression tree.
@endif
@if python
@li <code>ASTNode</code> @link libsbml.readMathMLFromString() readMathMLFromString(string)@endlink reads raw
MathML from a text string, constructs an AST from it, then returns the root
ASTNode of the resulting expression tree.
@endif

Similarly, writing out Abstract Syntax Tree structures is easily done using
the following method:

@if cpp
@li <code>char* writeMathMLToString(const ASTNode* node)</code> writes an
AST to a string.  The caller owns the character string returned and should free
it after it is no longer needed.
@endif
@if conly
@li <code>char* writeMathMLToString(const ASTNode_t* node)</code> writes an
AST to a string.  The caller owns the character string returned and should free
it after it is no longer needed.
@endif
@if python
@li <code>string</code> @link libsbml.writeMathMLToString() writeMathMLToString(ASTNode)@endlink writes an AST to a
string.  The caller owns the character string returned and should free it
after it is no longer needed.
@endif


<p> The <a href="#example-program">example program</a> given above
demonstrate the use of these methods.


*/
