libSBML C API  libSBML 5.8.0 C API
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
ASTNode.h File Reference

Detailed Description

Abstract Syntax Tree (AST) for representing formula trees.

Author
Ben Bornstein
Include dependency graph for ASTNode.h:
This graph shows which files directly or indirectly include this file:

Typedefs

typedef int(* ASTNodePredicate )(const ASTNode_t *node)
 A pointer to a function that takes an ASTNode and returns true (non-zero) or false (0). More...
 

Enumerations

enum  ASTNodeType_t {
  AST_PLUS = 43,
  AST_MINUS = 45,
  AST_TIMES = 42,
  AST_DIVIDE = 47,
  AST_POWER = 94,
  AST_INTEGER = 256,
  AST_REAL,
  AST_REAL_E,
  AST_RATIONAL,
  AST_NAME,
  AST_NAME_AVOGADRO,
  AST_NAME_TIME,
  AST_CONSTANT_E,
  AST_CONSTANT_FALSE,
  AST_CONSTANT_PI,
  AST_CONSTANT_TRUE,
  AST_LAMBDA,
  AST_FUNCTION,
  AST_FUNCTION_ABS,
  AST_FUNCTION_ARCCOS,
  AST_FUNCTION_ARCCOSH,
  AST_FUNCTION_ARCCOT,
  AST_FUNCTION_ARCCOTH,
  AST_FUNCTION_ARCCSC,
  AST_FUNCTION_ARCCSCH,
  AST_FUNCTION_ARCSEC,
  AST_FUNCTION_ARCSECH,
  AST_FUNCTION_ARCSIN,
  AST_FUNCTION_ARCSINH,
  AST_FUNCTION_ARCTAN,
  AST_FUNCTION_ARCTANH,
  AST_FUNCTION_CEILING,
  AST_FUNCTION_COS,
  AST_FUNCTION_COSH,
  AST_FUNCTION_COT,
  AST_FUNCTION_COTH,
  AST_FUNCTION_CSC,
  AST_FUNCTION_CSCH,
  AST_FUNCTION_DELAY,
  AST_FUNCTION_EXP,
  AST_FUNCTION_FACTORIAL,
  AST_FUNCTION_FLOOR,
  AST_FUNCTION_LN,
  AST_FUNCTION_LOG,
  AST_FUNCTION_PIECEWISE,
  AST_FUNCTION_POWER,
  AST_FUNCTION_ROOT,
  AST_FUNCTION_SEC,
  AST_FUNCTION_SECH,
  AST_FUNCTION_SIN,
  AST_FUNCTION_SINH,
  AST_FUNCTION_TAN,
  AST_FUNCTION_TANH,
  AST_LOGICAL_AND,
  AST_LOGICAL_NOT,
  AST_LOGICAL_OR,
  AST_LOGICAL_XOR,
  AST_RELATIONAL_EQ,
  AST_RELATIONAL_GEQ,
  AST_RELATIONAL_GT,
  AST_RELATIONAL_LEQ,
  AST_RELATIONAL_LT,
  AST_RELATIONAL_NEQ,
  AST_UNKNOWN
}
 ASTNodeType_t is the enumeration of possible ASTNode types. More...
 

Functions

int ASTNode_addChild (ASTNode_t *node, ASTNode_t *child)
 Adds the given node as a child of this ASTNode. More...
 
int ASTNode_addSemanticsAnnotation (ASTNode_t *node, XMLNode_t *annotation)
 Adds the given XMLNode as a semantic annotation of this ASTNode. More...
 
int ASTNode_canonicalize (ASTNode_t *node)
 Attempts to convert this ASTNode to a canonical form and returns true (non-zero) if the conversion succeeded, false (0) otherwise. More...
 
ASTNode_t * ASTNode_create (void)
 Creates a new ASTNode and returns a pointer to it. More...
 
ASTNode_t * ASTNode_createFromToken (Token_t *token)
 Creates a new ASTNode from the given Token and returns a pointer to it. More...
 
ASTNode_t * ASTNode_createWithType (ASTNodeType_t type)
 Creates a new ASTNode and sets its type to the given ASTNodeType. More...
 
ASTNode_t * ASTNode_deepCopy (const ASTNode_t *node)
 
void ASTNode_fillListOfNodes (const ASTNode_t *node, ASTNodePredicate predicate, List_t *lst)
 This method is identical in functionality to ASTNode_getListOfNodes(), except the List is passed-in by the caller. More...
 
void ASTNode_free (ASTNode_t *node)
 Frees the given ASTNode including any child nodes. More...
 
int ASTNode_freeName (ASTNode_t *node)
 Frees the name of this ASTNode and sets it to NULL. More...
 
char ASTNode_getCharacter (const ASTNode_t *node)
 
ASTNode_t * ASTNode_getChild (const ASTNode_t *node, unsigned int n)
 
const char * ASTNode_getClass (const ASTNode_t *node)
 Get the mathml class of this ASTNode. More...
 
long ASTNode_getDenominator (const ASTNode_t *node)
 
long ASTNode_getExponent (const ASTNode_t *node)
 
const char * ASTNode_getId (const ASTNode_t *node)
 Get the mathml id of this ASTNode. More...
 
long ASTNode_getInteger (const ASTNode_t *node)
 
ASTNode_t * ASTNode_getLeftChild (const ASTNode_t *node)
 
List_t * ASTNode_getListOfNodes (const ASTNode_t *node, ASTNodePredicate predicate)
 Performs a depth-first search (DFS) of the tree rooted at node and returns the List of nodes where predicate(node) returns true. More...
 
double ASTNode_getMantissa (const ASTNode_t *node)
 
const char * ASTNode_getName (const ASTNode_t *node)
 
unsigned int ASTNode_getNumChildren (const ASTNode_t *node)
 
long ASTNode_getNumerator (const ASTNode_t *node)
 
unsigned int ASTNode_getNumSemanticsAnnotations (ASTNode_t *node)
 Get the number of semantic annotation elements inside this node. More...
 
SBase_t * ASTNode_getParentSBMLObject (ASTNode_t *node)
 Returns the parent SBML structure of the given ASTNode_t structure. More...
 
int ASTNode_getPrecedence (const ASTNode_t *node)
 
double ASTNode_getReal (const ASTNode_t *node)
 
ASTNode_t * ASTNode_getRightChild (const ASTNode_t *node)
 
XMLNode_t * ASTNode_getSemanticsAnnotation (ASTNode_t *node, unsigned int n)
 Get the nth semantic annotation of this node. More...
 
const char * ASTNode_getStyle (const ASTNode_t *node)
 Get the mathml style of this ASTNode. More...
 
ASTNodeType_t ASTNode_getType (const ASTNode_t *node)
 
const char * ASTNode_getUnits (const ASTNode_t *node)
 Get the units of this ASTNode. More...
 
void * ASTNode_getUserData (ASTNode_t *node)
 Returns the user data that has been previously set by setUserData(). More...
 
int ASTNode_hasCorrectNumberArguments (ASTNode_t *node)
 Predicate returning non-zero (true) or zero (false) depending on whether this ASTNode has the correct number of children for it's type. More...
 
int ASTNode_hasUnits (const ASTNode_t *node)
 Predicate returning true (non-zero) if this node or any of its children nodes have sbml:units. More...
 
int ASTNode_insertChild (ASTNode_t *node, unsigned int n, ASTNode_t *newChild)
 Insert the second ASTNode_t structure at point n in the list of children of the first ASTNode_t structure. More...
 
int ASTNode_isAvogadro (const ASTNode_t *node)
 
int ASTNode_isBoolean (const ASTNode_t *node)
 
int ASTNode_isConstant (const ASTNode_t *node)
 
int ASTNode_isFunction (const ASTNode_t *node)
 
int ASTNode_isInfinity (const ASTNode_t *node)
 
int ASTNode_isInteger (const ASTNode_t *node)
 
int ASTNode_isLambda (const ASTNode_t *node)
 
int ASTNode_isLog10 (const ASTNode_t *node)
 
int ASTNode_isLogical (const ASTNode_t *node)
 
int ASTNode_isName (const ASTNode_t *node)
 
int ASTNode_isNaN (const ASTNode_t *node)
 
int ASTNode_isNegInfinity (const ASTNode_t *node)
 
int ASTNode_isNumber (const ASTNode_t *node)
 
int ASTNode_isOperator (const ASTNode_t *node)
 
int ASTNode_isPiecewise (const ASTNode_t *node)
 
int ASTNode_isRational (const ASTNode_t *node)
 
int ASTNode_isReal (const ASTNode_t *node)
 
int ASTNode_isRelational (const ASTNode_t *node)
 
int ASTNode_isSetClass (const ASTNode_t *node)
 
int ASTNode_isSetId (const ASTNode_t *node)
 
int ASTNode_isSetStyle (const ASTNode_t *node)
 
int ASTNode_isSetUnits (const ASTNode_t *node)
 Predicate returning true (non-zero) if this node has sbml:units. More...
 
int ASTNode_isSqrt (const ASTNode_t *node)
 
int ASTNode_isUMinus (const ASTNode_t *node)
 
int ASTNode_isUnknown (const ASTNode_t *node)
 
int ASTNode_isUPlus (const ASTNode_t *node)
 
int ASTNode_isWellFormedASTNode (ASTNode_t *node)
 Predicate returning non-zero (true) or zero (false) depending on whether this ASTNode is well-formed. More...
 
int ASTNode_prependChild (ASTNode_t *node, ASTNode_t *child)
 Adds the given node as a child of this ASTNode. More...
 
void ASTNode_reduceToBinary (ASTNode_t *node)
 Reduces the given ASTNode_t structure to a binary tree e.g. More...
 
int ASTNode_removeChild (ASTNode_t *node, unsigned int n)
 Removes child n of the given ASTNode_t structure. More...
 
void ASTNode_replaceArgument (ASTNode_t *node, const char *bvar, ASTNode_t *arg)
 Replaces occurences of a name within the given ASTNode_t structure with the name/value/formula represented by the second argument ASTNode_t e.g. More...
 
int ASTNode_replaceChild (ASTNode_t *node, unsigned int n, ASTNode_t *newChild)
 Replaces the nth child of the given ASTNode_t structure with the second ASTNode_t structure. More...
 
int ASTNode_returnsBoolean (const ASTNode_t *node)
 
int ASTNode_returnsBooleanForModel (const ASTNode_t *node, const Model_t *model)
 
int ASTNode_setCharacter (ASTNode_t *node, char value)
 Sets the value of this ASTNode to the given character. More...
 
int ASTNode_setClass (ASTNode_t *node, const char *className)
 Sets the mathml class of this ASTNode to className. More...
 
int ASTNode_setId (ASTNode_t *node, const char *id)
 Sets the mathml id of this ASTNode to id. More...
 
int ASTNode_setInteger (ASTNode_t *node, long value)
 Sets the value of this ASTNode to the given (long) integer and sets the node type to AST_INTEGER. More...
 
int ASTNode_setName (ASTNode_t *node, const char *name)
 Sets the value of this ASTNode to the given name. More...
 
int ASTNode_setRational (ASTNode_t *node, long numerator, long denominator)
 Sets the value of this ASTNode to the given rational in two parts: the numerator and denominator. More...
 
int ASTNode_setReal (ASTNode_t *node, double value)
 Sets the value of this ASTNode to the given real (double) and sets the node type to AST_REAL. More...
 
int ASTNode_setRealWithExponent (ASTNode_t *node, double mantissa, long exponent)
 Sets the value of this ASTNode to the given real (double) in two parts: the mantissa and the exponent. More...
 
int ASTNode_setStyle (ASTNode_t *node, const char *style)
 Sets the mathml style of this ASTNode to style. More...
 
int ASTNode_setType (ASTNode_t *node, ASTNodeType_t type)
 Sets the type of this ASTNode to the given ASTNodeType_t value. More...
 
int ASTNode_setUnits (ASTNode_t *node, const char *units)
 Sets the units of this ASTNode to units. More...
 
int ASTNode_setUserData (ASTNode_t *node, void *userData)
 Sets the user data of this node. More...
 
int ASTNode_swapChildren (ASTNode_t *node, ASTNode_t *that)
 Swap the children of this ASTNode with the children of that ASTNode. More...
 
int ASTNode_unsetClass (ASTNode_t *node)
 Unsets the mathml class of this ASTNode. More...
 
int ASTNode_unsetId (ASTNode_t *node)
 Unsets the mathml id of this ASTNode. More...
 
int ASTNode_unsetStyle (ASTNode_t *node)
 Unsets the mathml style of this ASTNode. More...
 
int ASTNode_unsetUnits (ASTNode_t *node)
 Unsets the units of this ASTNode. More...
 

Typedef Documentation

typedef int(* ASTNodePredicate)(const ASTNode_t *node)

A pointer to a function that takes an ASTNode and returns true (non-zero) or false (0).

See Also
ASTNode_getListOfNodes()
ASTNode_fillListOfNodes()

Enumeration Type Documentation

ASTNodeType_t is the enumeration of possible ASTNode types.

Each ASTNode has a type whose value is one of the elements of this enumeration. The types have the following meanings:

  • If the node is basic mathematical operator (e.g., "+"), then the node's type will be AST_PLUS, AST_MINUS, AST_TIMES, AST_DIVIDE, or AST_POWER, as appropriate.

  • If the node is a predefined function or operator from SBML Level 1 (in the string-based formula syntax used in Level 1) or SBML Level 2 and 3 (in the subset of MathML used in SBML Levels 2 and 3), then the node's type will be either AST_FUNCTION_ X, AST_LOGICAL_ X, or AST_RELATIONAL_ X, as appropriate. (Examples: AST_FUNCTION_LOG, AST_RELATIONAL_LEQ.)

  • If the node refers to a user-defined function, the node's type will be AST_FUNCTION (because it holds the name of the function).

  • If the node is a lambda expression, its type will be AST_LAMBDA.

  • If the node is a predefined constant ("ExponentialE", "Pi", "True" or "False"), then the node's type will be AST_CONSTANT_E, AST_CONSTANT_PI, AST_CONSTANT_TRUE, or AST_CONSTANT_FALSE.

  • (Levels 2 and 3 only) If the node is the special MathML csymbol time, the value of the node will be AST_NAME_TIME. (Note, however, that the MathML csymbol delay is translated into a node of type AST_FUNCTION_DELAY. The difference is due to the fact that time is a single variable, whereas delay is actually a function taking arguments.)

  • (Level 3 only) If the node is the special MathML csymbol avogadro, the value of the node will be AST_NAME_AVOGADRO.

  • If the node contains a numerical value, its type will be AST_INTEGER, AST_REAL, AST_REAL_E, or AST_RATIONAL, as appropriate.
See Also
ASTNode::getType()
ASTNode::canonicalize()
Enumerator
AST_PLUS 
AST_MINUS 
AST_TIMES 
AST_DIVIDE 
AST_POWER 
AST_INTEGER 
AST_REAL 
AST_REAL_E 
AST_RATIONAL 
AST_NAME 
AST_NAME_AVOGADRO 
AST_NAME_TIME 
AST_CONSTANT_E 
AST_CONSTANT_FALSE 
AST_CONSTANT_PI 
AST_CONSTANT_TRUE 
AST_LAMBDA 
AST_FUNCTION 
AST_FUNCTION_ABS 
AST_FUNCTION_ARCCOS 
AST_FUNCTION_ARCCOSH 
AST_FUNCTION_ARCCOT 
AST_FUNCTION_ARCCOTH 
AST_FUNCTION_ARCCSC 
AST_FUNCTION_ARCCSCH 
AST_FUNCTION_ARCSEC 
AST_FUNCTION_ARCSECH 
AST_FUNCTION_ARCSIN 
AST_FUNCTION_ARCSINH 
AST_FUNCTION_ARCTAN 
AST_FUNCTION_ARCTANH 
AST_FUNCTION_CEILING 
AST_FUNCTION_COS 
AST_FUNCTION_COSH 
AST_FUNCTION_COT 
AST_FUNCTION_COTH 
AST_FUNCTION_CSC 
AST_FUNCTION_CSCH 
AST_FUNCTION_DELAY 
AST_FUNCTION_EXP 
AST_FUNCTION_FACTORIAL 
AST_FUNCTION_FLOOR 
AST_FUNCTION_LN 
AST_FUNCTION_LOG 
AST_FUNCTION_PIECEWISE 
AST_FUNCTION_POWER 
AST_FUNCTION_ROOT 
AST_FUNCTION_SEC 
AST_FUNCTION_SECH 
AST_FUNCTION_SIN 
AST_FUNCTION_SINH 
AST_FUNCTION_TAN 
AST_FUNCTION_TANH 
AST_LOGICAL_AND 
AST_LOGICAL_NOT 
AST_LOGICAL_OR 
AST_LOGICAL_XOR 
AST_RELATIONAL_EQ 
AST_RELATIONAL_GEQ 
AST_RELATIONAL_GT 
AST_RELATIONAL_LEQ 
AST_RELATIONAL_LT 
AST_RELATIONAL_NEQ 
AST_UNKNOWN 

Function Documentation

int ASTNode_addChild ( ASTNode_t *  node,
ASTNode_t *  child 
)

Adds the given node as a child of this ASTNode.

Child nodes are added in-order from "left-to-right".

Child nodes are added in-order from "left-to-right".

Returns
integer value indicating success/failure of the function. The possible values returned by this function are:
  • LIBSBML_OPERATION_SUCCESS
  • LIBSBML_OPERATION_FAILED
  • LIBSBML_INVALID_OBJECT
int ASTNode_addSemanticsAnnotation ( ASTNode_t *  node,
XMLNode_t *  annotation 
)

Adds the given XMLNode as a semantic annotation of this ASTNode.

Parameters
nodethe ASTNode_t to which the annotation is to be added.
annotationthe XMLNode_t representing the annotation to add.
Returns
integer value indicating success/failure of the function. The possible values returned by this function are:
  • LIBSBML_OPERATION_SUCCESS
  • LIBSBML_OPERATION_FAILED
  • LIBSBML_INVALID_OBJECT
int ASTNode_canonicalize ( ASTNode_t *  node)

Attempts to convert this ASTNode to a canonical form and returns true (non-zero) if the conversion succeeded, false (0) otherwise.

The rules determining the canonical form conversion are as follows:

1. If the node type is AST_NAME and the node name matches "ExponentialE", "Pi", "True" or "False" the node type is converted to the corresponding AST_CONSTANT type.

2. If the node type is an AST_FUNCTION and the node name matches an L1 or L2 (MathML) function name, logical operator name, or relational operator name, the node is converted to the corresponding AST_FUNCTION, AST_LOGICAL or AST_CONSTANT type.

L1 function names are searched first, so canonicalizing "log" will result in a node type of AST_FUNCTION_LN (see L1 Specification, Appendix C).

Some canonicalizations result in a structural converion of the nodes (by adding a child). For example, a node with L1 function name "sqr" and a single child node (the argument) will be transformed to a node of type AST_FUNCTION_POWER with two children. The first child will remain unchanged, but the second child will be an ASTNode of type AST_INTEGER and a value of 2. The function names that result in structural changes are: log10, sqr and sqrt.

Attempts to convert this ASTNode to a canonical form and returns true (non-zero) if the conversion succeeded, false (0) otherwise.

The rules determining the canonical form conversion are as follows:

1. If the node type is AST_NAME and the node name matches "ExponentialE", "Pi", "True" or "False" the node type is converted to the corresponding AST_CONSTANT type.

2. If the node type is an AST_FUNCTION and the node name matches an L1 or L2 (MathML) function name, logical operator name, or relational operator name, the node is converted to the correspnding AST_FUNCTION, AST_LOGICAL or AST_CONSTANT type.

L1 function names are searched first, so canonicalizing "log" will result in a node type of AST_FUNCTION_LN (see L1 Specification, Appendix C).

Some canonicalizations result in a structural converion of the nodes (by adding a child). For example, a node with L1 function name "sqr" and a single child node (the argument) will be transformed to a node of type AST_FUNCTION_POWER with two children. The first child will remain unchanged, but the second child will be an ASTNode of type AST_INTEGER and a value of 2. The function names that result in structural changes are: log10, sqr and sqrt.

ASTNode_t* ASTNode_create ( void  )

Creates a new ASTNode and returns a pointer to it.

The returned node will have a type of AST_UNKNOWN and should be set to something else as soon as possible.

The returned node will have a type of AST_UNKNOWN and should be set to something else as soon as possible.

ASTNode_t* ASTNode_createFromToken ( Token_t token)

Creates a new ASTNode from the given Token and returns a pointer to it.

The returned ASTNode will contain the same data as the Token.

ASTNode_t* ASTNode_createWithType ( ASTNodeType_t  type)

Creates a new ASTNode and sets its type to the given ASTNodeType.

ASTNode_t* ASTNode_deepCopy ( const ASTNode_t *  node)
Returns
a copy of this ASTNode and all its children. The caller owns the returned ASTNode and is reponsible for freeing it.
void ASTNode_fillListOfNodes ( const ASTNode_t *  node,
ASTNodePredicate  predicate,
List_t *  lst 
)

This method is identical in functionality to ASTNode_getListOfNodes(), except the List is passed-in by the caller.

void ASTNode_free ( ASTNode_t *  node)

Frees the given ASTNode including any child nodes.

int ASTNode_freeName ( ASTNode_t *  node)

Frees the name of this ASTNode and sets it to NULL.

This operation is only applicable to ASTNode objects corresponding to operators, numbers, or AST_UNKNOWN. This method will have no effect on other types of nodes.

Frees the name of this ASTNode and sets it to NULL.

the node is not an operator, number or AST_UNKNOWN.

Returns
integer value indicating success/failure of the function. The possible values returned by this function are:
  • LIBSBML_OPERATION_SUCCESS
  • LIBSBML_UNEXPECTED_ATTRIBUTE
  • LIBSBML_INVALID_OBJECT
char ASTNode_getCharacter ( const ASTNode_t *  node)
Returns
the value of this ASTNode as a single character. This function should be called only when ASTNode_getType() is one of AST_PLUS, AST_MINUS, AST_TIMES, AST_DIVIDE or AST_POWER.
the value of this ASTNode as a single character. This function should be called only when ASTNode_getType() is one of AST_PLUS, AST_MINUS, AST_TIMES, AST_DIVIDE or AST_POWER.
ASTNode_t* ASTNode_getChild ( const ASTNode_t *  node,
unsigned int  n 
)
Returns
the nth child of this ASTNode or NULL if this node has no nth child (n > ASTNode_getNumChildren() - 1).
the nth child of this ASTNode or NULL if this node has no nth child (n > ASTNode_getNumChildren() - 1).
const char* ASTNode_getClass ( const ASTNode_t *  node)

Get the mathml class of this ASTNode.

Returns
the mathml class of this ASTNode.
long ASTNode_getDenominator ( const ASTNode_t *  node)
Returns
the value of the denominator of this ASTNode. This function should be called only when ASTNode_getType() == AST_RATIONAL.
the value of the denominator of this ASTNode. This function should be called only when ASTNode_getType() == AST_RATIONAL.
long ASTNode_getExponent ( const ASTNode_t *  node)
Returns
the value of the exponent of this ASTNode. This function should be called only when ASTNode_getType() is AST_REAL_E or AST_REAL.
the value of the exponent of this ASTNode. This function should be called only when ASTNode_getType() is AST_REAL_E or AST_REAL.
const char* ASTNode_getId ( const ASTNode_t *  node)

Get the mathml id of this ASTNode.

Returns
the mathml id of this ASTNode.
long ASTNode_getInteger ( const ASTNode_t *  node)
Returns
the value of this ASTNode as a (long) integer. This function should be called only when ASTNode_getType() == AST_INTEGER.
the value of this ASTNode as a (long) integer. This function should be called only when ASTNode_getType() == AST_INTEGER.
ASTNode_t* ASTNode_getLeftChild ( const ASTNode_t *  node)
Returns
the left child of this ASTNode. This is equivalent to ASTNode_getChild(node, 0);
List_t* ASTNode_getListOfNodes ( const ASTNode_t *  node,
ASTNodePredicate  predicate 
)

Performs a depth-first search (DFS) of the tree rooted at node and returns the List of nodes where predicate(node) returns true.

The typedef for ASTNodePredicate is:

int (*ASTNodePredicate) (const ASTNode_t *node);

where a return value of non-zero represents true and zero represents false.

The List returned is owned by the caller and should be freed with List_free(). The ASTNodes in the list, however, are not owned by the caller (as they still belong to the tree itself) and therefore should not be freed. That is, do not call List_freeItems().

Performs a depth-first search (DFS) of the tree rooted at node and returns the List of nodes where predicate(node) returns true.

The typedef for ASTNodePredicate is:

int (*ASTNodePredicate) (const ASTNode_t *node);

where a return value of non-zero represents true and zero represents false.

The List returned is owned by the caller and should be freed with List_free(). The ASTNodes in the list, however, are not owned by the caller (as they still belong to the tree itself) and therefore should not be freed. That is, do not call List_freeItems().

double ASTNode_getMantissa ( const ASTNode_t *  node)
Returns
the value of the mantissa of this ASTNode. This function should be called only when ASTNode_getType() is AST_REAL_E or AST_REAL. If AST_REAL, this method is identical to ASTNode_getReal().
the value of the mantissa of this ASTNode. This function should be called only when ASTNode_getType() is AST_REAL_E or AST_REAL. If AST_REAL, this method is identical to ASTNode_getReal().
const char* ASTNode_getName ( const ASTNode_t *  node)
Returns
the value of this ASTNode as a string. This function may be called on nodes that are not operators (ASTNode_isOperator(node) == 0) or numbers (ASTNode_isNumber(node) == 0).
the value of this ASTNode as a string. This function may be called on nodes that are not operators (ASTNode_isOperator(node) == 0) or numbers (ASTNode_isNumber(node) == 0).
unsigned int ASTNode_getNumChildren ( const ASTNode_t *  node)
Returns
the number of children of this ASTNode or 0 is this node has no children.
long ASTNode_getNumerator ( const ASTNode_t *  node)
Returns
the value of the numerator of this ASTNode. This function should be called only when ASTNode_getType() == AST_RATIONAL.
unsigned int ASTNode_getNumSemanticsAnnotations ( ASTNode_t *  node)

Get the number of semantic annotation elements inside this node.

Parameters
nodethe ASTNode_t structure to query.
Returns
the number of annotations of this ASTNode.
SBase_t* ASTNode_getParentSBMLObject ( ASTNode_t *  node)

Returns the parent SBML structure of the given ASTNode_t structure.

Parameters
nodethe ASTNode_t of which to return the parent.
Returns
the parent SBML SBase_t structure of this ASTNode_t.
int ASTNode_getPrecedence ( const ASTNode_t *  node)
Returns
the precedence of this ASTNode (as defined in the SBML L1 specification).
double ASTNode_getReal ( const ASTNode_t *  node)
Returns
the value of this ASTNode as a real (double). This function should be called only when ASTNode_isReal(node) != 0.

This function performs the necessary arithmetic if the node type is AST_REAL_E (mantissa * 10exponent) or AST_RATIONAL (numerator / denominator).

Returns
the value of this ASTNode as a real (double). This function should be called only when ASTNode_isReal(node) != 0.

This function performs the necessary arithmetic if the node type is AST_REAL_E (mantissa * $10^exponent$) or AST_RATIONAL (numerator / denominator).

ASTNode_t* ASTNode_getRightChild ( const ASTNode_t *  node)
Returns
the right child of this ASTNode or NULL if this node has no right child. If ASTNode_getNumChildren(node) > 1, then this is equivalent to:

ASTNode_getChild(node, ASTNode_getNumChildren(node) - 1);

Returns
the right child of this ASTNode or NULL if this node has no right child. If ASTNode_getNumChildren(node) > 1, then this is equivalent to:

ASTNode_getChild(node, ASTNode_getNumChildren(node) - 1);

XMLNode_t* ASTNode_getSemanticsAnnotation ( ASTNode_t *  node,
unsigned int  n 
)

Get the nth semantic annotation of this node.

Parameters
nodethe ASTNode_t structure to query.
nunsigned int the index of the annotation to be retrieved.
Returns
the nth annotation of this ASTNode, or NULL if this node has no nth annotation (n > ASTNode_getNumSemanticsAnnotations() - 1).
const char* ASTNode_getStyle ( const ASTNode_t *  node)

Get the mathml style of this ASTNode.

Returns
the mathml style of this ASTNode.
ASTNodeType_t ASTNode_getType ( const ASTNode_t *  node)
Returns
the type of this ASTNode.
const char* ASTNode_getUnits ( const ASTNode_t *  node)

Get the units of this ASTNode.

Only applies to cn elements

Returns
the units of this ASTNode.
void* ASTNode_getUserData ( ASTNode_t *  node)

Returns the user data that has been previously set by setUserData().

Parameters
nodedefines the node of interest.
Returns
the user data of this node. NULL if no user data has been.
See Also
ASTNode_setUserData
int ASTNode_hasCorrectNumberArguments ( ASTNode_t *  node)

Predicate returning non-zero (true) or zero (false) depending on whether this ASTNode has the correct number of children for it's type.

For example, an ASTNode with type AST_PLUS expects 2 child nodes.

Note
This function performs a check on the toplevel node only. Child nodes are not checked.
See Also
ASTNode_isWellFormedASTNode()
Parameters
nodedefines the node of interest.
Returns
non-zero (true) if this ASTNode is has appropriate number of children for it's type, zero (false) otherwise.
int ASTNode_hasUnits ( const ASTNode_t *  node)

Predicate returning true (non-zero) if this node or any of its children nodes have sbml:units.

Returns
true if this ASTNode or its children has units, false otherwise.
int ASTNode_insertChild ( ASTNode_t *  node,
unsigned int  n,
ASTNode_t *  newChild 
)

Insert the second ASTNode_t structure at point n in the list of children of the first ASTNode_t structure.

Parameters
nodethe ASTNode_t within which to insert a child.
nunsigned int the index of the ASTNode_t being added
newChildASTNode_t to insert as the nth child
Returns
integer value indicating success/failure of the function. The possible values returned by this function are:
  • LIBSBML_OPERATION_SUCCESS
  • LIBSBML_INDEX_EXCEEDS_SIZE
  • LIBSBML_INVALID_OBJECT
Note
inserting a child within an ASTNode may result in an inaccurate representation.
int ASTNode_isAvogadro ( const ASTNode_t *  node)
Returns
true (non-zero) if this ASTNode is the special symbol avogadro, false (0) otherwise.
int ASTNode_isBoolean ( const ASTNode_t *  node)
Returns
true (non-zero) if this ASTNode is a boolean (a logical operator, a relational operator, or the constants true or false), false (0) otherwise.
int ASTNode_isConstant ( const ASTNode_t *  node)
Returns
true (non-zero) if this ASTNode is a MathML constant (true, false, pi, exponentiale), false (0) otherwise.
int ASTNode_isFunction ( const ASTNode_t *  node)
Returns
true (non-zero) if this ASTNode is a function in SBML L1, L2 (MathML) (everything from abs() to tanh()) or user-defined, false (0) otherwise.
true (non-zero) if this ASTNode is a function in SBML L1, L2 (MathML) (everything from abs() to tanh()) or user-defined, false (0) otherwise.
int ASTNode_isInfinity ( const ASTNode_t *  node)
Returns
true if this ASTNode is the special IEEE 754 value infinity, false otherwise.
int ASTNode_isInteger ( const ASTNode_t *  node)
Returns
true (non-zero) if this ASTNode is of type AST_INTEGER, false (0) otherwise.
true (non-zero) if this ASTNode is of type AST_INTEGER, false (0) otherwise.
int ASTNode_isLambda ( const ASTNode_t *  node)
Returns
true (non-zero) if this ASTNode is of type AST_LAMBDA, false (0) otherwise.
true (non-zero) if this ASTNode is of type AST_LAMBDA, false (0) otherwise.
int ASTNode_isLog10 ( const ASTNode_t *  node)
Returns
true (non-zero) if the given ASTNode represents a log10() function, false (0) otherwise.

More precisley, the node type is AST_FUNCTION_LOG with two children the first of which is an AST_INTEGER equal to 10.

Returns
true (non-zero) if the given ASTNode represents a log10() function, false (0) otherwise.

More precisley, the node type is AST_FUNCTION_LOG with two children the first of which is an AST_INTEGER equal to 10.

int ASTNode_isLogical ( const ASTNode_t *  node)
Returns
true (non-zero) if this ASTNode is a MathML logical operator (and, or, not, xor), false (0) otherwise.
int ASTNode_isName ( const ASTNode_t *  node)
Returns
true (non-zero) if this ASTNode is a user-defined variable name in SBML L1, L2 (MathML) or the special symbols delay or time, false (0) otherwise.
int ASTNode_isNaN ( const ASTNode_t *  node)
Returns
true (non-zero) if this ASTNode is the special IEEE 754 value not a number, false (0) otherwise.
int ASTNode_isNegInfinity ( const ASTNode_t *  node)
Returns
true if this ASTNode is the special IEEE 754 value negative infinity, false otherwise.
int ASTNode_isNumber ( const ASTNode_t *  node)
Returns
true (non-zero) if this ASTNode is a number, false (0) otherwise.

This is functionally equivalent to:

Returns
true (non-zero) if this ASTNode is a number, false (0) otherwise.

This is functionally equivalent to:

ASTNode_isInteger(node) || ASTNode_isReal(node).

int ASTNode_isOperator ( const ASTNode_t *  node)
Returns
true (non-zero) if this ASTNode is an operator, false (0) otherwise. Operators are: +, -, *, / and \^ (power).
int ASTNode_isPiecewise ( const ASTNode_t *  node)
Returns
true (non-zero) if this ASTNode is a piecewise function, false (0) otherwise.
int ASTNode_isRational ( const ASTNode_t *  node)
Returns
true (non-zero) if this ASTNode is of type AST_RATIONAL, false (0) otherwise.
true (non-zero) if this ASTNode is of type AST_RATIONAL, false (0) otherwise.
int ASTNode_isReal ( const ASTNode_t *  node)
Returns
true (non-zero) if the value of this ASTNode can represented as a real number, false (0) otherwise.

To be a represented as a real number, this node must be of one of the following types: AST_REAL, AST_REAL_E or AST_RATIONAL.

Returns
true (non-zero) if the value of this ASTNode can represented as a real number, false (0) otherwise.

To be a represented as a real number, this node must be of one of the following types: AST_REAL, AST_REAL_E or AST_RATIONAL.

int ASTNode_isRelational ( const ASTNode_t *  node)
Returns
true (non-zero) if this ASTNode is a MathML relational operator (==, >=, >, <=, < !=), false (0) otherwise.
int ASTNode_isSetClass ( const ASTNode_t *  node)
Returns
true (non-zero) if this ASTNode has a mathml class, false (0) otherwise.
int ASTNode_isSetId ( const ASTNode_t *  node)
Returns
true (non-zero) if this ASTNode has a mathml id, false (0) otherwise.
int ASTNode_isSetStyle ( const ASTNode_t *  node)
Returns
true (non-zero) if this ASTNode has a mathml style, false (0) otherwise.
int ASTNode_isSetUnits ( const ASTNode_t *  node)

Predicate returning true (non-zero) if this node has sbml:units.

Only applies to cn elements.

Returns
true if this ASTNode has units, false otherwise.
int ASTNode_isSqrt ( const ASTNode_t *  node)
Returns
true (non-zero) if the given ASTNode represents a sqrt() function, false (0) otherwise.

More precisley, the node type is AST_FUNCTION_ROOT with two children the first of which is an AST_INTEGER equal to 2.

Returns
true (non-zero) if the given ASTNode represents a sqrt() function, false (0) otherwise.

More precisley, the node type is AST_FUNCTION_ROOT with two children the first of which is an AST_INTEGER equal to 2.

int ASTNode_isUMinus ( const ASTNode_t *  node)
Returns
true (non-zero) if this ASTNode is a unary minus, false (0) otherwise.

For numbers, unary minus nodes can be "collapsed" by negating the number. In fact, does this during its parse, and

has a configuration option that allows this behavior to be turned on or off. However, unary minus nodes for symbols (AST_NAMES) cannot be "collapsed", so this predicate function is necessary.

A node is defined as a unary minus node if it is of type AST_MINUS and has exactly one child.

Returns
true (non-zero) if this ASTNode is a unary minus, false (0) otherwise.

For numbers, unary minus nodes can be "collapsed" by negating the number. In fact, SBML_parseFormula() does this during its parse. However, unary minus nodes for symbols (AST_NAMES) cannot be "collapsed", so this predicate function is necessary.

A node is defined as a unary minus node if it is of type AST_MINUS and has exactly one child.

int ASTNode_isUnknown ( const ASTNode_t *  node)
Returns
true (non-zero) if this ASTNode is of type AST_UNKNOWN, false (0) otherwise.
true (non-zero) if this ASTNode is of type AST_UNKNOWN, false (0) otherwise.
int ASTNode_isUPlus ( const ASTNode_t *  node)
Returns
true (non-zero) if this ASTNode is a unary plus, false (0) otherwise.
int ASTNode_isWellFormedASTNode ( ASTNode_t *  node)

Predicate returning non-zero (true) or zero (false) depending on whether this ASTNode is well-formed.

Note
An ASTNode may be well-formed, i.e. each node and it's children have the appropriate number of children for the given type, but may still be invalid in the context of an SBML model.
See Also
ASTNode_hasCorrectNumberArguments()
Parameters
nodedefines the node of interest.
Returns
non-zero (true) if this ASTNode is well-formed, zero (false) otherwise.
int ASTNode_prependChild ( ASTNode_t *  node,
ASTNode_t *  child 
)

Adds the given node as a child of this ASTNode.

This method adds child nodes from "right-to-left".

This method adds child nodes from "right-to-left".

Returns
integer value indicating success/failure of the function. The possible values returned by this function are:
  • LIBSBML_OPERATION_SUCCESS
  • LIBSBML_OPERATION_FAILED
  • LIBSBML_INVALID_OBJECT
void ASTNode_reduceToBinary ( ASTNode_t *  node)

Reduces the given ASTNode_t structure to a binary tree e.g.

if the formula in this ASTNode is and(x, y, z) then the formula of the reduced node would be and(and(x, y), z)

Parameters
nodethe ASTNode_t structure to reduce
int ASTNode_removeChild ( ASTNode_t *  node,
unsigned int  n 
)

Removes child n of the given ASTNode_t structure.

Parameters
nodethe ASTNode_t from which to remove a child.
nunsigned int the index of the child to remove
Returns
integer value indicating success/failure of the function. The possible values returned by this function are:
  • LIBSBML_OPERATION_SUCCESS
  • LIBSBML_INDEX_EXCEEDS_SIZE
  • LIBSBML_INVALID_OBJECT
Note
removing a child from an ASTNode may result in an inaccurate representation.
void ASTNode_replaceArgument ( ASTNode_t *  node,
const char *  bvar,
ASTNode_t *  arg 
)

Replaces occurences of a name within the given ASTNode_t structure with the name/value/formula represented by the second argument ASTNode_t e.g.

if the formula in this ASTNode is x + y; bvar is x and arg is an ASTNode representing the real value 3 replaceArgument substitutes 3 for x within this ASTNode

Parameters
nodethe ASTNode_t structure to replace argument
bvara string representing the variable name to be substituted
argan ASTNode representing the name/value/formula to substitute
int ASTNode_replaceChild ( ASTNode_t *  node,
unsigned int  n,
ASTNode_t *  newChild 
)

Replaces the nth child of the given ASTNode_t structure with the second ASTNode_t structure.

Parameters
nodethe ASTNode_t within which to replace a child.
nunsigned int the index of the child to replace
newChildASTNode_t structure to replace the nth child
Returns
integer value indicating success/failure of the function. The possible values returned by this function are:
  • LIBSBML_OPERATION_SUCCESS
  • LIBSBML_INDEX_EXCEEDS_SIZE
Note
replacing a child within an ASTNode may result in an inaccurate representation.
int ASTNode_returnsBoolean ( const ASTNode_t *  node)
Returns
true (non-zero) if this ASTNode returns a boolean, false (0) otherwise.
int ASTNode_returnsBooleanForModel ( const ASTNode_t *  node,
const Model_t *  model 
)
Returns
true (non-zero) if this ASTNode returns a boolean, false (0) otherwise.
int ASTNode_setCharacter ( ASTNode_t *  node,
char  value 
)

Sets the value of this ASTNode to the given character.

If character is one of '+', '-', '*', '/' or '\^', the node type will be set accordingly. For all other characters, the node type will be set to AST_UNKNOWN.

If character is one of '+', '-', '*', '/' or '\^', the node type will be set accordingly. For all other characters, the node type will be set to AST_UNKNOWN.

Returns
integer value indicating success/failure of the function. The possible values returned by this function are:
  • LIBSBML_OPERATION_SUCCESS
  • LIBSBML_INVALID_OBJECT
int ASTNode_setClass ( ASTNode_t *  node,
const char *  className 
)

Sets the mathml class of this ASTNode to className.

Parameters
nodethe ASTNode to set
classNamestring representing the identifier.
Returns
integer value indicating success/failure of the function. The possible values returned by this function are:
int ASTNode_setId ( ASTNode_t *  node,
const char *  id 
)

Sets the mathml id of this ASTNode to id.

Parameters
nodethe ASTNode to set
idstring representing the identifier.
Returns
integer value indicating success/failure of the function. The possible values returned by this function are:
int ASTNode_setInteger ( ASTNode_t *  node,
long  value 
)

Sets the value of this ASTNode to the given (long) integer and sets the node type to AST_INTEGER.

Sets the value of this ASTNode to the given (long) integer and sets the node type to AST_INTEGER.

Returns
integer value indicating success/failure of the function. The possible values returned by this function are:
  • LIBSBML_OPERATION_SUCCESS
  • LIBSBML_INVALID_OBJECT
int ASTNode_setName ( ASTNode_t *  node,
const char *  name 
)

Sets the value of this ASTNode to the given name.

The node type will be set (to AST_NAME) ONLY IF the ASTNode was previously an operator (ASTNode_isOperator(node) != 0) or number (ASTNode_isNumber(node) != 0). This allows names to be set for AST_FUNCTIONs and the like.

The node type will be set (to AST_NAME) ONLY IF the ASTNode was previously an operator (ASTNode_isOperator(node) != 0) or number (ASTNode_isNumber(node) != 0). This allows names to be set for AST_FUNCTIONs and the like.

Returns
integer value indicating success/failure of the function. The possible values returned by this function are:
  • LIBSBML_OPERATION_SUCCESS
  • LIBSBML_INVALID_OBJECT
int ASTNode_setRational ( ASTNode_t *  node,
long  numerator,
long  denominator 
)

Sets the value of this ASTNode to the given rational in two parts: the numerator and denominator.

The node type is set to AST_RATIONAL.

The node type is set to AST_RATIONAL.

Returns
integer value indicating success/failure of the function. The possible values returned by this function are:
  • LIBSBML_OPERATION_SUCCESS
  • LIBSBML_INVALID_OBJECT
int ASTNode_setReal ( ASTNode_t *  node,
double  value 
)

Sets the value of this ASTNode to the given real (double) and sets the node type to AST_REAL.

This is functionally equivalent to:

Sets the value of this ASTNode to the given real (double) and sets the node type to AST_REAL.

This is functionally equivalent to:

ASTNode_setRealWithExponent(node, value, 0);

Returns
integer value indicating success/failure of the function. The possible values returned by this function are:
  • LIBSBML_OPERATION_SUCCESS
  • LIBSBML_INVALID_OBJECT
int ASTNode_setRealWithExponent ( ASTNode_t *  node,
double  mantissa,
long  exponent 
)

Sets the value of this ASTNode to the given real (double) in two parts: the mantissa and the exponent.

The node type is set to AST_REAL_E.

The node type is set to AST_REAL_E.

Returns
integer value indicating success/failure of the function. The possible values returned by this function are:
  • LIBSBML_OPERATION_SUCCESS
  • LIBSBML_INVALID_OBJECT
int ASTNode_setStyle ( ASTNode_t *  node,
const char *  style 
)

Sets the mathml style of this ASTNode to style.

Parameters
nodethe ASTNode to set
stylestring representing the identifier.
Returns
integer value indicating success/failure of the function. The possible values returned by this function are:
int ASTNode_setType ( ASTNode_t *  node,
ASTNodeType_t  type 
)

Sets the type of this ASTNode to the given ASTNodeType_t value.

Sets the type of this ASTNode to the given ASTNodeType_t value.

Returns
integer value indicating success/failure of the function. The possible values returned by this function are:
  • LIBSBML_OPERATION_SUCCESS
  • LIBSBML_INVALID_ATTRIBUTE_VALUE
  • LIBSBML_INVALID_OBJECT
int ASTNode_setUnits ( ASTNode_t *  node,
const char *  units 
)

Sets the units of this ASTNode to units.

The units will be set only if the ASTNode represents an <cn> element. Use isNumber().

Parameters
nodethe ASTNode to set
unitsstring representing units
Returns
integer value indicating success/failure of the function. The possible values returned by this function are:
  • LIBSBML_OPERATION_SUCCESS
  • LIBSBML_UNEXPECTED_ATTRIBUTE
  • LIBSBML_INVALID_ATTRIBUTE_VALUE
  • LIBSBML_INVALID_OBJECT
int ASTNode_setUserData ( ASTNode_t *  node,
void *  userData 
)

Sets the user data of this node.

This can be used by the application developer to attach custom information to the node. In case of a deep copy this attribute will passed as it is. The attribute will be never interpreted by this class.

Parameters
nodedefines the node of which the user data should be set.
userDataspecifies the new user data.
Returns
integer value indicating success/failure of the function. The possible values returned by this function are:
  • LIBSBML_OPERATION_SUCCESS
  • LIBSBML_OPERATION_FAILED
  • LIBSBML_INVALID_OBJECT
int ASTNode_swapChildren ( ASTNode_t *  node,
ASTNode_t *  that 
)

Swap the children of this ASTNode with the children of that ASTNode.

Parameters
nodethe first ASTNode_t structure
thatASTNode_t structure with which children will swapped
Returns
integer value indicating success/failure of the function. The possible values returned by this function are:
  • LIBSBML_OPERATION_SUCCESS
  • LIBSBML_INVALID_OBJECT
int ASTNode_unsetClass ( ASTNode_t *  node)

Unsets the mathml class of this ASTNode.

Returns
integer value indicating success/failure of the function. The possible values returned by this function are:
int ASTNode_unsetId ( ASTNode_t *  node)

Unsets the mathml id of this ASTNode.

Returns
integer value indicating success/failure of the function. The possible values returned by this function are:
int ASTNode_unsetStyle ( ASTNode_t *  node)

Unsets the mathml style of this ASTNode.

Returns
integer value indicating success/failure of the function. The possible values returned by this function are:
int ASTNode_unsetUnits ( ASTNode_t *  node)

Unsets the units of this ASTNode.

Returns
integer value indicating success/failure of the function. The possible values returned by this function are:
  • LIBSBML_OPERATION_SUCCESS
  • LIBSBML_UNEXPECTED_ATTRIBUTE
  • LIBSBML_OPERATION_FAILED
  • LIBSBML_INVALID_OBJECT