public class ASTNode extends ASTBase
This class of objects is defined by libSBML only and has no direct equivalent in terms of SBML components. This class is not prescribed by the SBML specifications, although it is used to implement features defined in SBML.
Abstract Syntax Trees (ASTs) are a simple kind of data structure used in
libSBML for storing mathematical expressions. The ASTNode
is the
cornerstone of libSBML's AST representation. An AST 'node' represents the
most basic, indivisible part of a mathematical formula and come in many
types. For instance, there are node types to represent numbers (with
subtypes to distinguish integer, real, and rational numbers), names
(e.g., constants or variables), simple mathematical operators, logical
or relational operators and functions. LibSBML ASTs provide a canonical,
in-memory representation for all mathematical formulas regardless of
their original format (which might be MathML or might be text strings).
An AST node in libSBML is a recursive structure containing a pointer
to the node's value (which might be, for example, a number or a symbol)
and a list of children nodes. Each ASTNode
node may have none, one,
two, or more children depending on its type. The following diagram
illustrates an example of how the mathematical expression '1 +
2'
is represented as an AST with one plus node having two
integer children nodes for the numbers 1
and
2
. The figure also shows the corresponding MathML
representation:
Infix | AST | MathML |
---|---|---|
1 + 2
|
<math xmlns="http://www.w3.org/1998/Math/MathML">   <apply>     <plus/>     <cn type="integer"> 1 </cn>     <cn type="integer"> 2 </cn>   </apply> </math>
|
The following are other noteworthy points about the AST representation in libSBML:
ASTNode
are other ASTNode
objects. The list of
children is empty for nodes that are leaf elements, such as numbers.
For nodes that are actually roots of expression subtrees, the list of
children points to the parsed objects that make up the rest of the
expression.
For many applications, the details of ASTs are irrelevant because the applications can use the text-string based translation functions such as . If you find the complexity of using the AST representation of expressions too high for your purposes, perhaps the string-based functions will be more suitable.
Finally, it is worth noting that the AST and MathML handling code in libSBML remains written in C, not C++. (All of libSBML was originally written in C.) Readers may occasionally wonder why some aspects are more C-like and less object oriented, and that's one of the reasons.
Every ASTNode
has an associated type code to indicate whether, for
example, it holds a number or stands for an arithmetic operator.
The type is recorded as a value drawn from a
set of static integer constants defined in the class libsbmlConstants
. Their names begin with the characters AST_.
The list of possible types is quite long, because it covers all the mathematical functions that are permitted in SBML. The values are shown in the following table:
AST_CONSTANT_E | AST_FUNCTION_COT | AST_LOGICAL_NOT |
AST_CONSTANT_FALSE | AST_FUNCTION_COTH | AST_LOGICAL_OR |
AST_CONSTANT_PI | AST_FUNCTION_CSC | AST_LOGICAL_XOR |
AST_CONSTANT_TRUE | AST_FUNCTION_CSCH | AST_MINUS |
AST_DIVIDE | AST_FUNCTION_DELAY | AST_NAME |
AST_FUNCTION | AST_FUNCTION_EXP | AST_NAME_AVOGADRO (Level 3 only) |
AST_FUNCTION_ABS | AST_FUNCTION_FACTORIAL | AST_NAME_TIME |
AST_FUNCTION_ARCCOS | AST_FUNCTION_FLOOR | AST_PLUS |
AST_FUNCTION_ARCCOSH | AST_FUNCTION_LN | AST_POWER |
AST_FUNCTION_ARCCOT | AST_FUNCTION_LOG | AST_RATIONAL |
AST_FUNCTION_ARCCOTH | AST_FUNCTION_PIECEWISE | AST_REAL |
AST_FUNCTION_ARCCSC | AST_FUNCTION_POWER | AST_REAL_E |
AST_FUNCTION_ARCCSCH | AST_FUNCTION_ROOT | AST_RELATIONAL_EQ |
AST_FUNCTION_ARCSEC | AST_FUNCTION_SEC | AST_RELATIONAL_GEQ |
AST_FUNCTION_ARCSECH | AST_FUNCTION_SECH | AST_RELATIONAL_GT |
AST_FUNCTION_ARCSIN | AST_FUNCTION_SIN | AST_RELATIONAL_LEQ |
AST_FUNCTION_ARCSINH | AST_FUNCTION_SINH | AST_RELATIONAL_LT |
AST_FUNCTION_ARCTAN | AST_FUNCTION_TAN | AST_RELATIONAL_NEQ |
AST_FUNCTION_ARCTANH | AST_FUNCTION_TANH | AST_TIMES |
AST_FUNCTION_CEILING | AST_INTEGER | AST_UNKNOWN |
AST_FUNCTION_COS | AST_LAMBDA | |
AST_FUNCTION_COSH | AST_LOGICAL_AND |
The types have the following meanings:
'+'
), then the
node's type will be AST_PLUS
, AST_MINUS
, AST_TIMES
, AST_DIVIDE
, or
AST_POWER
, as appropriate.
AST_FUNCTION_
X, AST_LOGICAL_
X, or AST_RELATIONAL_
X, as appropriate. (Examples: AST_FUNCTION_LOG
, AST_RELATIONAL_LEQ
.)
AST_FUNCTION
(because it holds the
name of the function).
AST_LAMBDA
.
'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
.
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.)
avogadro
,
the value of the node will be AST_NAME_AVOGADRO.
AST_INTEGER
, AST_REAL
, AST_REAL_E
, or AST_RATIONAL
, as appropriate.
The text-string form of mathematical formulas produced by libsbml.formulaToString()
and
read by libsbml.parseFormula(String formula)
and
libsbml.parseL3Formula(String formula)
are in a simple C-inspired infix notation. A
formula in one of these two text-string formats can be handed to a program
that understands SBML mathematical expressions, or used as part of a
translation system. The libSBML distribution comes with example
programs in the 'examples'
subdirectory that demonstrate such things
as translating infix formulas into MathML and vice-versa.
Please see the documentation for the functions
libsbml.parseFormula(String formula)
and
libsbml.parseL3Formula(String formula)
for detailed explanations of the infix syntax they accept.
Constructor and Description |
---|
ASTNode(ASTNode orig)
Copy constructor creates a deep copy of the given
ASTNode . |
ASTNode(int type)
Creates a new
ASTNode . |
Modifier and Type | Method and Description |
---|---|
int |
addChild(ASTNode child)
Adds the given node as a child of this
ASTNode . |
int |
addSemanticsAnnotation(XMLNode sAnnotation)
|
boolean |
canonicalize()
Converts this
ASTNode to a canonical form. |
ASTBase |
deepCopy()
Creates a recursive copy of this node and all its children.
|
void |
delete()
Explicitly deletes the underlying native object.
|
boolean |
equals(java.lang.Object sb)
Equality comparison method for ASTNode.
|
int |
freeName()
Frees the name of this
ASTNode and sets it to null. |
char |
getCharacter()
Returns the value of this node as a single character.
|
ASTNode |
getChild(long n)
Returns the child at index n of this node.
|
java.lang.String |
getClassName()
Returns the MathML
class attribute value of this ASTNode . |
XMLAttributes |
getDefinitionURL()
Returns the MathML
definitionURL attribute value. |
java.lang.String |
getDefinitionURLString()
Returns the MathML
definitionURL attribute value as a string. |
int |
getDenominator()
Returns the value of the denominator of this node.
|
int |
getExponent()
Returns the exponent value of this
ASTNode . |
int |
getExtendedType()
Returns the extended type of this
ASTNode . |
java.lang.String |
getId()
Returns the MathML
id attribute value of this ASTNode . |
int |
getInteger()
Returns the value of this node as an integer.
|
ASTNode |
getLeftChild()
Returns the left child of this node.
|
ASTNodeList |
getListOfNodes()   |
double |
getMantissa()
Returns the mantissa value of this node.
|
java.lang.String |
getName()
Returns the value of this node as a string.
|
long |
getNumChildren()
Returns the number of children of this node.
|
int |
getNumerator()
Returns the value of the numerator of this node.
|
long |
getNumSemanticsAnnotations()
Returns the number of MathML
<semantics> element
elements on this node. |
java.lang.String |
getOperatorName()
Returns the value of this operator node as a string.
|
SBase |
getParentSBMLObject()
Returns the parent SBML object.
|
int |
getPrecedence()
Returns the precedence of this node in the infix math syntax of SBML
Level 1.
|
double |
getReal()
Returns the real-numbered value of this node.
|
ASTNode |
getRightChild()
Returns the right child of this node.
|
XMLNode |
getSemanticsAnnotation(long n)
Returns the nth MathML
<semantics> element on this
ASTNode . |
java.lang.String |
getStyle()
Returns the MathML
style attribute value of this ASTNode . |
int |
getType()
Returns the type of this
ASTNode . |
java.lang.String |
getUnits()
Returns the units of this
ASTNode . |
boolean |
hasCorrectNumberArguments()
Returns
true if this ASTNode has the correct number of children for
its type. |
int |
hashCode()
Returns a hashcode for this ASTNode object.
|
int |
hasTypeAndNumChildren(int type,
long numchildren)
Returns
true if this node is of a certain type with a specific number
of children. |
boolean |
hasUnits()
Returns
true if this node or any of its
children nodes have the attribute sbml:units . |
int |
insertChild(long n,
ASTNode newChild)
|
boolean |
isAvogadro()
Returns
true if this node represents the predefined
value for Avogadro's constant. |
boolean |
isBoolean()
Returns
true if this node has a Boolean type. |
boolean |
isConstant()
Returns
true if this node represents a MathML
constant. |
boolean |
isFunction()
Returns
true if this node represents a function. |
boolean |
isInfinity()
Returns
true if this node represents the special IEEE 754
value for infinity. |
boolean |
isInteger()
Returns
true if this node contains an integer value. |
boolean |
isLambda()
Returns
true if this node is a MathML
<lambda> . |
boolean |
isLog10()
Returns
true if this node represents a log10 function. |
boolean |
isLogical()
Returns
true if this node is a MathML logical operator. |
boolean |
isName()
Returns
true if this node is a user-defined variable name
or the symbols for time or Avogadro's constant. |
boolean |
isNaN()
Returns
true if this node represents the special IEEE 754
value 'not a number' (NaN). |
boolean |
isNegInfinity()
Returns
true if this node represents the special IEEE 754
value 'negative infinity'. |
boolean |
isNumber()
Returns
true if this node contains a number. |
boolean |
isOperator()
Returns
true if this node is a mathematical
operator. |
boolean |
isPiecewise()
Returns
true if this node is the MathML
<piecewise> construct. |
boolean |
isQualifier()
Predicate returning
true if this node is a MathML
qualifier. |
boolean |
isRational()
Returns
true if this node represents a rational number. |
boolean |
isReal()
Returns
true if this node can represent a real number. |
boolean |
isRelational()
Returns
true if this node is a MathML
relational operator. |
boolean |
isSemantics()
Predicate returning
true if this node is a MathML
semantics node. |
boolean |
isSetClass()
Returns
true if this node has a value for the MathML
attribute class. |
boolean |
isSetId()
Returns
true if this node has a value for the MathML
attribute id. |
boolean |
isSetParentSBMLObject()
Returns
true if this node has a value for the parent SBML
object. |
boolean |
isSetStyle()
Returns
true if this node has a value for the MathML
attribute style. |
boolean |
isSetUnits()
Returns
true if this node has the attribute
sbml:units . |
boolean |
isSetUserData()
Returns
true if this node has a user data object. |
boolean |
isSqrt()
Returns
true if this node represents a square root
function. |
boolean |
isUMinus()
Returns
true if this node is a unary minus operator. |
boolean |
isUnknown()
Returns
true if this node has an unknown type. |
boolean |
isUPlus()
Returns
true if this node is a unary plus operator. |
boolean |
isWellFormedASTNode()
|
int |
prependChild(ASTNode child)
Adds the given node as a child of this
ASTNode . |
void |
reduceToBinary()
Reduces this
ASTNode to a binary tree. |
int |
removeChild(long n)
Removes the nth child of this
ASTNode object. |
void |
renameSIdRefs(java.lang.String oldid,
java.lang.String newid)
Renames all the SIdRef attributes on this node and its child nodes.
|
void |
renameUnitSIdRefs(java.lang.String oldid,
java.lang.String newid)
Renames all the UnitSIdRef attributes on this node and its child nodes.
|
void |
replaceArgument(java.lang.String bvar,
ASTNode arg)
Replaces occurrences of a given name with a given
ASTNode . |
int |
replaceChild(long n,
ASTNode newChild)
|
boolean |
returnsBoolean()
Returns
true if this node returns a Boolean value. |
boolean |
returnsBoolean(Model model)
Returns
true if this node returns a Boolean value. |
int |
setCharacter(char value)
Sets the value of this
ASTNode to the given character. |
int |
setClassName(java.lang.String className)
Sets the MathML attribute
class of this ASTNode . |
int |
setDefinitionURL(java.lang.String url)
Sets the MathML attribute
definitionURL. |
int |
setDefinitionURL(XMLAttributes url)
Sets the MathML attribute
definitionURL. |
int |
setId(java.lang.String id)
Sets the MathML attribute
id of this ASTNode . |
int |
setName(java.lang.String name)
Sets the value of this
ASTNode to the given name. |
int |
setStyle(java.lang.String style)
Sets the MathML attribute
style of this ASTNode . |
int |
setType(int type)
Sets the type of this
ASTNode to the given type code. |
int |
setUnits(java.lang.String units)
Sets the units of this
ASTNode to units. |
int |
setValue(double value)
Sets the value of this
ASTNode to the given real (double ). |
int |
setValue(double mantissa,
int exponent)
Sets the value of this
ASTNode to the given real (double ) |
int |
setValue(int value)
Sets the value of this
ASTNode to the given (long ) integer |
int |
setValue(int numerator,
int denominator)
Sets the value of this
ASTNode to the given rational. |
int |
swapChildren(ASTNode that)
Swaps the children of this node with the children of another node.
|
int |
unsetClass()
Unsets the MathML
class attribute of this ASTNode . |
int |
unsetId()
Unsets the MathML
id attribute of this ASTNode . |
int |
unsetParentSBMLObject()
Unsets the parent SBML object.
|
int |
unsetStyle()
Unsets the MathML
style attribute of this ASTNode . |
int |
unsetUnits()
Unsets the units of this
ASTNode . |
int |
unsetUserData()
Unsets the user data of this node.
|
getUserData
public ASTNode(ASTNode orig)
ASTNode
.
orig
- the ASTNode
to be copied.public ASTNode(int type)
ASTNode
.
Unless the argument type
is given, the returned node will by
default have a type of AST_UNKNOWN
. If the type isn't supplied when caling this
constructor, the caller should set the node type to something else as
soon as possible using
ASTNode.setType(int)
.
type
- an optional
type
code indicating the type of node to create.
public int addChild(ASTNode child)
ASTNode
.
Child nodes are added in-order, from left to right.
child
- the ASTNode
instance to add
ASTNode.prependChild(ASTNode child)
,
ASTNode.replaceChild(long n, ASTNode child)
,
ASTNode.insertChild(long n, ASTNode child)
,
ASTNode.removeChild(long n)
,
ASTNode.isWellFormedASTNode()
ASTNode
object may change the
structure of the mathematical formula it represents, and may even render
the representation invalid. Callers need to be careful to use this method
in the context of other operations to create complete and correct
formulas. The method
ASTNode.isWellFormedASTNode()
may also be useful for checking the results of node modifications.
public int addSemanticsAnnotation(XMLNode sAnnotation)
XMLNode
as a MathML <semantics>
element to this ASTNode
.
The <semantics>
element is a MathML 2.0 construct
that can be used to associate additional information with a MathML
construct. The construct can be used to decorate a MathML expressions with
a sequence of one or more <annotation>
or
<annotation-xml>
elements. Each such element contains a
pair of items the first is a symbol that acts as an attribute or key, and
the second is the value associated with the attribute or key. Please refer
to the MathML 2.0 documentation, particularly the Section
5.2, Semantic Annotations for more information about these constructs.
sAnnotation
- the annotation to add.
ASTNode.getNumSemanticsAnnotations()
,
ASTNode.getSemanticsAnnotation(long n)
<semantics>
annotation construct, the truth is that
this construct has so far (at this time of this writing, which is early
2014) seen very little use in SBML software. The full implications of
using these annotations are still poorly understood. If you wish to
use this construct, we urge you to discuss possible uses and applications
on the SBML discussion lists, particularly sbml-discuss and/or sbml-interoperability.
public boolean canonicalize()
ASTNode
to a canonical form.
The rules determining the canonical form conversion are as follows:
AST_NAME
and the node name matches 'ExponentialE'
, 'Pi'
, 'True'
or
'False'
the node type is converted to the corresponding
AST_CONSTANT_
X type.
AST_FUNCTION
and the node name matches an SBML (MathML) function name, logical operator name, or
relational operator name, the node is converted to the corresponding
AST_FUNCTION_
X or
AST_LOGICAL_
X type.
SBML Level 1 function names are searched first thus, for
example, canonicalizing log
will result in a node type of AST_FUNCTION_LN
. (See the SBML
Level 1 Version 2 Specification, Appendix C.)
Sometimes, canonicalization of a node results in a structural
conversion of the node as a result of adding a child. For example, a
node with the SBML Level 1 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.
true
if this node was successfully converted to
canonical form, false
otherwise.public ASTBase deepCopy()
public void delete()
In general, application software will not need to call this method directly. The Java language binding for libSBML is implemented as a language wrapper that provides a Java interface to libSBML's underlying C++/C code. Some of the Java methods return objects that are linked to objects created not by Java code, but by C++ code. The Java objects wrapped around them will be deleted when the garbage collector invokes the corresponding C++ finalize()
methods for the objects. The finalize()
methods in turn call the ASTNode.delete()
method on the libSBML object.
This method is exposed in case calling programs want to ensure that the underlying object is freed immediately, and not at some arbitrary time determined by the Java garbage collector. In normal usage, callers do not need to invoke ASTNode.delete()
themselves.
public boolean equals(java.lang.Object sb)
Because the Java methods for libSBML are actually wrappers around code
implemented in C++ and C, certain operations will not behave as
expected. Equality comparison is one such case. An instance of a
libSBML object class is actually a proxy object
wrapping the real underlying C/C++ object. The normal ==
equality operator in Java will only compare the Java proxy objects,
not the underlying native object. The result is almost never what you
want in practical situations. Unfortunately, Java does not provide a
way to override ==
.
The alternative that must be followed is to use the
equals()
method. The equals
method on this
class overrides the default java.lang.Object one, and performs an
intelligent comparison of instances of objects of this class. The
result is an assessment of whether two libSBML Java objects are truly
the same underlying native-code objects.
The use of this method in practice is the same as the use of any other
Java equals
method. For example,
a.equals(
b)
returns
true
if a and b are references to the
same underlying object.
equals
 in class java.lang.Object
sb
- a reference to an object to which the current object
instance will be comparedtrue
if sb
refers to the same underlying
native object as this one, false
otherwisepublic int freeName()
ASTNode
and sets it to null.
This operation is only applicable to ASTNode
objects corresponding to
operators, numbers, or AST_UNKNOWN
. This method has no effect on other types of
nodes.
public char getCharacter()
This function should be called only when
ASTNode.getType()
returns
AST_PLUS
,
AST_MINUS
,
AST_TIMES
,
AST_DIVIDE
or
AST_POWER
.
ASTNode
as a single characterpublic ASTNode getChild(long n)
n
- the index of the child to get
ASTNode
or null
if this node has no nth
child (n >
ASTNode.getNumChildren()
- 1
).
ASTNode.getNumChildren()
,
ASTNode.getLeftChild()
,
ASTNode.getRightChild()
public java.lang.String getClassName()
class
attribute value of this ASTNode
.
getClassName
 in class ASTBase
ASTNode
, if any exists.
ASTNode.isSetClass()
,
ASTNode.setClassName(String id)
,
ASTNode.unsetClass()
public XMLAttributes getDefinitionURL()
definitionURL
attribute value.
definitionURL
attribute, in the form of
a libSBML XMLAttributes
object.
ASTNode.setDefinitionURL(XMLAttributes url)
,
ASTNode.setDefinitionURL(String url)
,
ASTNode.getDefinitionURLString()
public java.lang.String getDefinitionURLString()
definitionURL
attribute value as a string.
definitionURL
attribute, as a string.
ASTNode.getDefinitionURL()
,
ASTNode.setDefinitionURL(String url)
,
ASTNode.setDefinitionURL(XMLAttributes url)
public int getDenominator()
ASTNode
, or 1
if
this node has no numerical value.
ASTNode.getType()
returns
AST_RATIONAL
.
It will return 1
if the node type is another type, but since 1
may
be a valid value for the denominator of a rational number, it is
important to be sure that the node type is the correct type in order to
correctly interpret the returned value.public int getExponent()
ASTNode
.
ASTNode
, or 0
if this
is not a type of node that has an exponent.
ASTNode.getType()
returns AST_REAL_E
.
It will return 0
if the node type is another type, but since 0
may
be a valid value, it is important to be sure that the node type is the
correct type in order to correctly interpret the returned value.public int getExtendedType()
ASTNode
.
The type may be either a core integer type code or a value of a type code defined by an SBML Level 3 package.
getExtendedType
 in class ASTBase
ASTNode
.
ASTNode.getType()
ASTNode
is of a type from a package, the
value returned by ASTNode.getType()
will be AST_ORIGINATES_IN_PACKAGE
and getExtendedType() will return a package-specific type code.
To find out the possible package-specific types (if any), please
consult the documentation for the particular package.
public java.lang.String getId()
id
attribute value of this ASTNode
.
getId
 in class ASTBase
ASTNode
.
ASTNode.isSetId()
,
ASTNode.setId(String id)
,
ASTNode.unsetId()
public int getInteger()
If this node type is AST_RATIONAL
, this method returns the value of the numerator.
ASTNode
as a (long
) integer.
ASTNode.getType()
returns
AST_INTEGER
or
AST_RATIONAL
.
It will return 0
if the node type is not one of these, but since
0
may be a valid value for integer, it is important to be sure that
the node type is one of the expected types in order to understand if
0
is the actual value.public ASTNode getLeftChild()
ASTNode
. This is equivalent to calling
ASTNode.getChild(long)
with an argument of 0.
ASTNode.getNumChildren()
,
ASTNode.getChild(long n)
,
ASTNode.getRightChild()
public ASTNodeList getListOfNodes()
public double getMantissa()
If ASTNode.getType()
returns
AST_REAL
, this method is
identical to ASTNode.getReal()
.
ASTNode
, or 0
if this
node is not a type that has a real-numbered value.
ASTNode.getType()
returns
AST_REAL_E
,
AST_REAL
or
AST_NAME_AVOGADRO
. It
will return 0
if the node type is another type, but since 0
may be
a valid value, it is important to be sure that the node type is the
correct type in order to correctly interpret the returned value.public java.lang.String getName()
This function may be called on nodes that (1) are not operators, i.e.,
nodes for which ASTNode.isOperator()
returns false
, and (2) are not numbers, i.e.,
ASTNode.isNumber()
returns false.
ASTNode
as a string, or null
if it is
a node that does not have a name equivalent (e.g., if it is a number).public long getNumChildren()
ASTNode
, or 0 is this node has
no children.public int getNumerator()
This function should be called only when
ASTNode.getType()
returns
AST_RATIONAL
or
AST_INTEGER
.
ASTNode
.public long getNumSemanticsAnnotations()
<semantics>
element
elements on this node.
The <semantics>
element is a MathML 2.0 construct
that can be used to associate additional information with a MathML
construct. The construct can be used to decorate a MathML expressions with
a sequence of one or more <annotation>
or
<annotation-xml>
elements. Each such element contains a
pair of items the first is a symbol that acts as an attribute or key, and
the second is the value associated with the attribute or key. Please refer
to the MathML 2.0 documentation, particularly the Section
5.2, Semantic Annotations for more information about these constructs.
ASTNode
.
ASTNode.addSemanticsAnnotation(XMLNode sAnnotation)
,
ASTNode.getSemanticsAnnotation(long n)
<semantics>
annotation construct, the truth is that
this construct has so far (at this time of this writing, which is early
2014) seen very little use in SBML software. The full implications of
using these annotations are still poorly understood. If you wish to
use this construct, we urge you to discuss possible uses and applications
on the SBML discussion lists, particularly sbml-discuss and/or sbml-interoperability.
public java.lang.String getOperatorName()
This function may be called on nodes that are operators, i.e., nodes for
which ASTNode.isOperator()
returns
true.
ASTNode
as a string (or null
if not
an operator).public SBase getParentSBMLObject()
getParentSBMLObject
 in class ASTBase
ASTNode
.
ASTNode.isSetParentSBMLObject()
,
#setParentSBMLObject(SBase sb)
public int getPrecedence()
For more information about the infix syntax, see the discussion about text string formulas at the top of the
documentation for ASTNode
.
ASTNode
public double getReal()
This function performs the necessary arithmetic if the node type is
AST_REAL_E
(mantissa *
10 exponent) or
AST_RATIONAL
(numerator / denominator).
ASTNode
as a real (double), or 0
if this is not a node that holds a number.
ASTNode
has a
numerical value type. It will return 0
if the node type is another
type, but since 0
may be a valid value, it is important to be sure
that the node type is the correct type in order to correctly interpret
the returned value.public ASTNode getRightChild()
ASTNode
, or null
if this node has no
right child. If
ASTNode.getNumChildren()
> 1
, then this is equivalent to:
getChild( getNumChildren() - 1 )
ASTNode.getNumChildren()
,
ASTNode.getLeftChild()
,
ASTNode.getChild(long n)
public XMLNode getSemanticsAnnotation(long n)
<semantics>
element on this
ASTNode
.
The <semantics>
element is a MathML 2.0 construct
that can be used to associate additional information with a MathML
construct. The construct can be used to decorate a MathML expressions with
a sequence of one or more <annotation>
or
<annotation-xml>
elements. Each such element contains a
pair of items the first is a symbol that acts as an attribute or key, and
the second is the value associated with the attribute or key. Please refer
to the MathML 2.0 documentation, particularly the Section
5.2, Semantic Annotations for more information about these constructs.
n
- the index of the annotation to return. Callers should
use ASTNode.getNumSemanticsAnnotations()
to first find out how
many annotations there are.
ASTNode
, or null
if this node has
no nth annotation (n >
ASTNode.getNumSemanticsAnnotations()
- 1
).
ASTNode.addSemanticsAnnotation(XMLNode sAnnotation)
,
ASTNode.getNumSemanticsAnnotations()
<semantics>
annotation construct, the truth is that
this construct has so far (at this time of this writing, which is early
2014) seen very little use in SBML software. The full implications of
using these annotations are still poorly understood. If you wish to
use this construct, we urge you to discuss possible uses and applications
on the SBML discussion lists, particularly sbml-discuss and/or sbml-interoperability.
public java.lang.String getStyle()
style
attribute value of this ASTNode
.
getStyle
 in class ASTBase
ASTNode
, if any exists.
ASTNode.isSetStyle()
,
ASTNode.setStyle(String id)
,
ASTNode.unsetStyle()
public int getType()
ASTNode
.
The value returned is one of the Core AST type codes such as
AST_LAMBDA
,
AST_PLUS
, etc.
getType
 in class ASTBase
ASTNode
.
ASTNode.getExtendedType()
ASTNode
is
a construct created by a package rather than libSBML Core, then
getType() will return AST_ORIGINATES_IN_PACKAGE
. Callers can then obtain the
package-specific type by calling getExtendedType().
public java.lang.String getUnits()
ASTNode
.
SBML Level 3 Version 1 introduced the ability to include an
attribute sbml:units
on MathML cn
elements
appearing in SBML mathematical formulas. The value of this attribute can
be used to indicate the unit of measurement to be associated with the
number in the content of the cn
element. The value of this
attribute must be the identifier of a unit of measurement defined by SBML
or the enclosing Model. Here, the sbml
portion is an XML
namespace prefix that must be associated with the SBML namespace for SBML
Level 3. The following example illustrates how this attribute can be
used to define a number with value 10
and unit of measurement
second
:
<math xmlns="http://www.w3.org/1998/Math/MathML" xmlns:sbml="http://www.sbml.org/sbml/level3/version1/core"> <cn type="integer" sbml:units="second"> 10 </cn> </math>
ASTNode
.
libsbml.parseL3Formula(String formula)
sbml:units
attribute is only available in SBML
Level 3. It may not be used in Levels 1&ndash2 of SBML.
public boolean hasCorrectNumberArguments()
true
if this ASTNode
has the correct number of children for
its type.
For example, an ASTNode
with type AST_PLUS
expects 2 child nodes.
hasCorrectNumberArguments
 in class ASTBase
true
if this ASTNode
has the appropriate number of children
for its type, false
otherwise.
ASTNode.isWellFormedASTNode()
public int hashCode()
hashCode
 in class java.lang.Object
public int hasTypeAndNumChildren(int type, long numchildren)
true
if this node is of a certain type with a specific number
of children.
Designed for use in cases where it is useful to discover if the node is a unary not or unary minus, or a times node with no children, etc.
public boolean hasUnits()
true
if this node or any of its
children nodes have the attribute sbml:units
.
SBML Level 3 Version 1 introduced the ability to include an
attribute sbml:units
on MathML cn
elements
appearing in SBML mathematical formulas. The value of this attribute can
be used to indicate the unit of measurement to be associated with the
number in the content of the cn
element. The value of this
attribute must be the identifier of a unit of measurement defined by SBML
or the enclosing Model. Here, the sbml
portion is an XML
namespace prefix that must be associated with the SBML namespace for SBML
Level 3. The following example illustrates how this attribute can be
used to define a number with value 10
and unit of measurement
second
:
<math xmlns="http://www.w3.org/1998/Math/MathML" xmlns:sbml="http://www.sbml.org/sbml/level3/version1/core"> <cn type="integer" sbml:units="second"> 10 </cn> </math>
true
if this ASTNode
or its children has units associated
with it, false
otherwise.
ASTNode.isSetUnits()
,
ASTNode.setUnits(String units)
sbml:units
attribute is only available in SBML
Level 3. It may not be used in Levels 1&ndash2 of SBML.
public int insertChild(long n, ASTNode newChild)
n
- long the index of the ASTNode
being addednewChild
- ASTNode
to insert as the nth child
ASTNode.addChild(ASTNode child)
,
ASTNode.prependChild(ASTNode child)
,
ASTNode.replaceChild(long n, ASTNode child)
,
ASTNode.removeChild(long n)
ASTNode
object may change the
structure of the mathematical formula it represents, and may even render
the representation invalid. Callers need to be careful to use this method
in the context of other operations to create complete and correct
formulas. The method
ASTNode.isWellFormedASTNode()
may also be useful for checking the results of node modifications.
public boolean isAvogadro()
true
if this node represents the predefined
value for Avogadro's constant.
SBML Level 3 introduced a predefined MathML <csymbol>
for the value of Avogadro's constant. LibSBML stores this internally as
a node of type AST_NAME_AVOGADRO
.
This method returns true
if this node has that type.
isAvogadro
 in class ASTBase
true
if this ASTNode
is the special symbol avogadro,
false
otherwise.
libsbml.parseL3Formula(String formula)
public boolean isBoolean()
true
if this node has a Boolean type.
The ASTNode
objects that have Boolean types are the logical operators,
relational operators, and the constants true
or false.
public boolean isConstant()
true
if this node represents a MathML
constant.
Examples of MathML constants include such things as pi.
isConstant
 in class ASTBase
true
if this ASTNode
is a MathML constant, false
otherwise.
true
for nodes of type AST_NAME_AVOGADRO
in SBML Level 3.public boolean isFunction()
true
if this node represents a function.
The three types of functions in SBML are MathML functions (e.g.,
abs()
), SBML Level 1 functions (in the SBML
Level 1 math syntax), and user-defined functions (using
FunctionDefinition
in SBML Level 2 and 3).
isFunction
 in class ASTBase
true
if this ASTNode
is a function, false
otherwise.public boolean isInfinity()
true
if this node represents the special IEEE 754
value for infinity.
true
if this ASTNode
is the special IEEE 754 value infinity,
false
otherwise.public boolean isInteger()
true
if this node contains an integer value.
isInteger
 in class ASTBase
true
if this ASTNode
is of type AST_INTEGER
, false
otherwise.public boolean isLambda()
true
if this node is a MathML
<lambda>
.
isLambda
 in class ASTBase
true
if this ASTNode
is of type AST_LAMBDA
, false
otherwise.public boolean isLog10()
true
if this node represents a log10
function.
More precisely, this predicate returns true
if the node type is AST_FUNCTION_LOG
with two
children, the first of which is an AST_INTEGER
equal to 10.
true
if the given ASTNode
represents a log10
() function,
false
otherwise.
libsbml.parseL3Formula(String formula)
public boolean isLogical()
true
if this node is a MathML logical operator.
The possible MathML logical operators are and
, or
, not
, and
xor.
public boolean isName()
true
if this node is a user-defined variable name
or the symbols for time or Avogadro's constant.
SBML Levels 2 and 3 provides <csymbol>
definitions for 'time' and 'avogadro', which can be used to represent
simulation time and Avogadro's constant in MathML.
public boolean isNaN()
true
if this node represents the special IEEE 754
value 'not a number' (NaN).
true
if this ASTNode
is the special IEEE 754 NaN, false
otherwise.public boolean isNegInfinity()
true
if this node represents the special IEEE 754
value 'negative infinity'.
true
if this ASTNode
is the special IEEE 754 value negative
infinity, false
otherwise.public boolean isNumber()
true
if this node contains a number.
public boolean isOperator()
true
if this node is a mathematical
operator.
The possible mathematical operators in the MathML syntax supported by
SBML are +
, -
, *
, /
and ^
(power).
isOperator
 in class ASTBase
true
if this ASTNode
is an operator, false
otherwise.public boolean isPiecewise()
true
if this node is the MathML
<piecewise>
construct.
isPiecewise
 in class ASTBase
true
if this ASTNode
is a MathML piecewise
function,
false
otherwise.public boolean isQualifier()
true
if this node is a MathML
qualifier.
The MathML qualifier node types are bvar
, degree
, base
,
piece
, and otherwise.
isQualifier
 in class ASTBase
true
if this ASTNode
is a MathML qualifier, false
otherwise.public boolean isRational()
true
if this node represents a rational number.
isRational
 in class ASTBase
true
if this ASTNode
is of type AST_RATIONAL
,
false
otherwise.public boolean isReal()
true
if this node can represent a real number.
More precisely, this node must be of one of the following types: AST_REAL
, AST_REAL_E
or AST_RATIONAL
.
public boolean isRelational()
true
if this node is a MathML
relational operator.
The MathML relational operators are ==
, >=
,
>
, <
, and !=
.
isRelational
 in class ASTBase
true
if this ASTNode
is a MathML relational operator,
false
otherwise.public boolean isSemantics()
true
if this node is a MathML
semantics node.
isSemantics
 in class ASTBase
true
if this ASTNode
is a MathML semantics node, false
otherwise.public boolean isSetClass()
true
if this node has a value for the MathML
attribute class.
isSetClass
 in class ASTBase
ASTNode
has an attribute class, false
otherwise.
ASTNode.isSetId()
,
ASTNode.isSetStyle()
,
ASTNode.setClassName(String id)
,
ASTNode.unsetClass()
public boolean isSetId()
true
if this node has a value for the MathML
attribute id.
isSetId
 in class ASTBase
ASTNode
has an attribute id, false
otherwise.
ASTNode.isSetClass()
,
ASTNode.isSetStyle()
,
ASTNode.setId(String id)
,
ASTNode.unsetId()
public boolean isSetParentSBMLObject()
true
if this node has a value for the parent SBML
object.
isSetParentSBMLObject
 in class ASTBase
ASTNode
has an parent SBML object set, false
otherwise.
ASTNode.getParentSBMLObject()
,
#setParentSBMLObject(SBase sb)
public boolean isSetStyle()
true
if this node has a value for the MathML
attribute style.
isSetStyle
 in class ASTBase
ASTNode
has an attribute style, false
otherwise.
ASTNode.isSetClass()
,
ASTNode.isSetId()
,
ASTNode.setStyle(String id)
,
ASTNode.unsetStyle()
public boolean isSetUnits()
true
if this node has the attribute
sbml:units
.
SBML Level 3 Version 1 introduced the ability to include an
attribute sbml:units
on MathML cn
elements
appearing in SBML mathematical formulas. The value of this attribute can
be used to indicate the unit of measurement to be associated with the
number in the content of the cn
element. The value of this
attribute must be the identifier of a unit of measurement defined by SBML
or the enclosing Model. Here, the sbml
portion is an XML
namespace prefix that must be associated with the SBML namespace for SBML
Level 3. The following example illustrates how this attribute can be
used to define a number with value 10
and unit of measurement
second
:
<math xmlns="http://www.w3.org/1998/Math/MathML" xmlns:sbml="http://www.sbml.org/sbml/level3/version1/core"> <cn type="integer" sbml:units="second"> 10 </cn> </math>
true
if this ASTNode
has units associated with it, false
otherwise.
ASTNode.hasUnits()
,
ASTNode.setUnits(String units)
sbml:units
attribute is only available in SBML
Level 3. It may not be used in Levels 1&ndash2 of SBML.
public boolean isSetUserData()
true
if this node has a user data object.
isSetUserData
 in class ASTBase
ASTNode
has a user data object set, false
otherwise.public boolean isSqrt()
true
if this node represents a square root
function.
More precisely, the node type must be AST_FUNCTION_ROOT
with two
children, the first of which is an AST_INTEGER
node having value equal to 2.
true
if the given ASTNode
represents a sqrt()
function, false
otherwise.public boolean isUMinus()
true
if this node is a unary minus operator.
A node is defined as a unary minus node if it is of type AST_MINUS
and has exactly one child.
For numbers, unary minus nodes can be 'collapsed' by negating the
number. In fact,
libsbml.parseFormula(String formula)
does this during its parsing process, and
libsbml.parseL3Formula(String formula)
has a configuration option that allows this behavior to be turned
on or off. However, unary minus nodes for symbols
(AST_NAME
) cannot
be 'collapsed', so this predicate function is necessary.
true
if this ASTNode
is a unary minus, false
otherwise.
libsbml.parseL3Formula(String formula)
public boolean isUnknown()
true
if this node has an unknown type.
'Unknown' nodes have the type AST_UNKNOWN
. Nodes with unknown types will not appear in an
ASTNode
tree returned by libSBML based upon valid SBML input the only
situation in which a node with type AST_UNKNOWN
may appear is immediately after having create a
new, untyped node using the ASTNode
constructor. Callers creating
nodes should endeavor to set the type to a valid node type as soon as
possible after creating new nodes.
isUnknown
 in class ASTBase
true
if this ASTNode
is of type AST_UNKNOWN
, false
otherwise.public boolean isUPlus()
true
if this node is a unary plus operator.
A node is defined as a unary plus node if it is of type AST_PLUS
and has exactly one child.
true
if this ASTNode
is a unary plus, false
otherwise.public boolean isWellFormedASTNode()
true
if this ASTNode
is well-formed, false
otherwise.
ASTNode.hasCorrectNumberArguments()
ASTNode
may be well-formed, with each node and its children
having the appropriate number of children for the given type, but may
still be invalid in the context of its use within an SBML model.
public int prependChild(ASTNode child)
ASTNode
.
This method adds child nodes from right to left.
child
- the ASTNode
instance to add
ASTNode.addChild(ASTNode child)
,
ASTNode.replaceChild(long n, ASTNode child)
,
ASTNode.insertChild(long n, ASTNode child)
,
ASTNode.removeChild(long n)
ASTNode
object may change the
structure of the mathematical formula it represents, and may even render
the representation invalid. Callers need to be careful to use this method
in the context of other operations to create complete and correct
formulas. The method
ASTNode.isWellFormedASTNode()
may also be useful for checking the results of node modifications.
public void reduceToBinary()
public int removeChild(long n)
ASTNode
object.
n
- long the index of the child to remove
ASTNode.addChild(ASTNode child)
,
ASTNode.prependChild(ASTNode child)
,
ASTNode.replaceChild(long n, ASTNode child)
,
ASTNode.insertChild(long n, ASTNode child)
ASTNode
object may change the
structure of the mathematical formula it represents, and may even render
the representation invalid. Callers need to be careful to use this method
in the context of other operations to create complete and correct
formulas. The method
ASTNode.isWellFormedASTNode()
may also be useful for checking the results of node modifications.
public void renameSIdRefs(java.lang.String oldid, java.lang.String newid)
oldid
- the old identifier.newid
- the new identifier.public void renameUnitSIdRefs(java.lang.String oldid, java.lang.String newid)
The only place UnitSIDRefs appear in MathML <cn>
elements, so the effects of this method are limited to that.
oldid
- the old identifier.newid
- the new identifier.public void replaceArgument(java.lang.String bvar, ASTNode arg)
ASTNode
.
For example, if the formula in this ASTNode
is x + y
,
then the <bvar>
is x
and arg
is an ASTNode
representing the real value 3.
This method substitutes 3
for
x
within this ASTNode
object.
bvar
- a string representing the variable name to be substituted.
arg
- an ASTNode
representing the name/value/formula to use as
a replacement.public int replaceChild(long n, ASTNode newChild)
n
- long the index of the child to replacenewChild
- ASTNode
to replace the nth child
ASTNode.addChild(ASTNode child)
,
ASTNode.prependChild(ASTNode child)
,
ASTNode.insertChild(long n, ASTNode child)
,
ASTNode.removeChild(long n)
ASTNode
object may change the
structure of the mathematical formula it represents, and may even render
the representation invalid. Callers need to be careful to use this method
in the context of other operations to create complete and correct
formulas. The method
ASTNode.isWellFormedASTNode()
may also be useful for checking the results of node modifications.
public boolean returnsBoolean()
true
if this node returns a Boolean value.
This function looks at the whole ASTNode
rather than just the top level
of the ASTNode
. Thus, it will consider return values from piecewise
statements. In addition, if this ASTNode
uses a function call to a
user-defined function, the return value of the corresponding
FunctionDefinition
object will be determined. Note that this is only
possible where the ASTNode
can trace its parent Model
that is, the
ASTNode
must represent the <math>
element of some
SBML object that has already been added to an instance of an
SBMLDocument
.
public boolean returnsBoolean(Model model)
true
if this node returns a Boolean value.
This function looks at the whole ASTNode
rather than just the top level
of the ASTNode
. Thus, it will consider return values from piecewise
statements. In addition, if this ASTNode
uses a function call to a
user-defined function, the return value of the corresponding
FunctionDefinition
object will be determined. Note that this is only
possible where the ASTNode
can trace its parent Model
that is, the
ASTNode
must represent the <math>
element of some
SBML object that has already been added to an instance of an
SBMLDocument
.
public int setCharacter(char value)
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
.
value
- the character value to which the node's value should be
set.
public int setClassName(java.lang.String className)
class
of this ASTNode
.
setClassName
 in class ASTBase
className
- string
representing the MathML class for this node.
ASTNode.isSetClass()
,
Object.getClass()
,
ASTNode.unsetClass()
setClass()
, but in Java it is renamed
setClassName()
to avoid a name collision with Java's
standard object method of the same name.
public int setDefinitionURL(java.lang.String url)
definitionURL.
url
- the URL value for the definitionURL
attribute.
ASTNode.setDefinitionURL(XMLAttributes url)
,
ASTNode.getDefinitionURL()
,
ASTNode.getDefinitionURLString()
public int setDefinitionURL(XMLAttributes url)
definitionURL.
url
- the URL value for the definitionURL
attribute.
ASTNode.setDefinitionURL(String url)
,
ASTNode.getDefinitionURL()
,
ASTNode.getDefinitionURLString()
public int setId(java.lang.String id)
id
of this ASTNode
.
setId
 in class ASTBase
id
- string
representing the identifier.
ASTNode.isSetId()
,
ASTNode.getId()
,
ASTNode.unsetId()
public int setName(java.lang.String name)
ASTNode
to the given name.
As a side effect, this ASTNode
object's type will be reset to
AST_NAME
if (and only
if) the ASTNode
was previously an operator (i.e.,
ASTNode.isOperator()
returns true
), number
(i.e., ASTNode.isNumber()
returns true
), or unknown.
This allows names to be set for AST_FUNCTION
nodes and the like.
name
- the string containing the name to which this node's value
should be set.
public int setStyle(java.lang.String style)
style
of this ASTNode
.
setStyle
 in class ASTBase
style
- string
representing the identifier.
ASTNode.isSetStyle()
,
ASTNode.getStyle()
,
ASTNode.unsetStyle()
public int setType(int type)
ASTNode
to the given type code.
setType
 in class ASTBase
type
- the type to which this node should be set.
ASTNode.getType()
,
ASTNode.setType(int Type)
public int setUnits(java.lang.String units)
ASTNode
to units.
The units will be set only if this ASTNode
object represents a
MathML <cn>
element, i.e., represents a number.
Callers may use
ASTNode.isNumber()
to inquire whether the node is of that type.
SBML Level 3 Version 1 introduced the ability to include an
attribute sbml:units
on MathML cn
elements
appearing in SBML mathematical formulas. The value of this attribute can
be used to indicate the unit of measurement to be associated with the
number in the content of the cn
element. The value of this
attribute must be the identifier of a unit of measurement defined by SBML
or the enclosing Model. Here, the sbml
portion is an XML
namespace prefix that must be associated with the SBML namespace for SBML
Level 3. The following example illustrates how this attribute can be
used to define a number with value 10
and unit of measurement
second
:
<math xmlns="http://www.w3.org/1998/Math/MathML" xmlns:sbml="http://www.sbml.org/sbml/level3/version1/core"> <cn type="integer" sbml:units="second"> 10 </cn> </math>
units
- string
representing the unit identifier.
ASTNode.isSetUnits()
,
ASTNode.hasUnits()
sbml:units
attribute is only available in SBML
Level 3. It may not be used in Levels 1&ndash2 of SBML.
public int setValue(double value)
ASTNode
to the given real (double
).
As a side effect, this operation sets the node type to AST_REAL
.
This is functionally equivalent to:
setValue(value, 0)
value
- the double
format number to which this node's value
should be set.
public int setValue(double mantissa, int exponent)
ASTNode
to the given real (double
)
As a side effet, this operation sets the node type to
AST_REAL_E
.
mantissa
- the mantissa of this node's real-numbered value.exponent
- the exponent of this node's real-numbered value.
public int setValue(int value)
ASTNode
to the given (long
) integer
As a side effect, this operation sets the node type to AST_INTEGER
.
value
- the integer to which this node's value should be set.
public int setValue(int numerator, int denominator)
ASTNode
to the given rational.
As a side effect, this operation sets the node type to AST_RATIONAL
.
numerator
- the numerator value of the rational.denominator
- the denominator value of the rational.
public int swapChildren(ASTNode that)
that
- the other node whose children should be used to replace
this node's children.
public int unsetClass()
class
attribute of this ASTNode
.
unsetClass
 in class ASTBase
public int unsetId()
id
attribute of this ASTNode
.
public int unsetParentSBMLObject()
unsetParentSBMLObject
 in class ASTBase
public int unsetStyle()
style
attribute of this ASTNode
.
unsetStyle
 in class ASTBase
public int unsetUnits()
ASTNode
.
public int unsetUserData()
The user data 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.
unsetUserData
 in class ASTBase