libSBML C++ API  libSBML 5.13.0 C++ API
SBaseRef Class Reference
Inheritance diagram for SBaseRef:
[legend]

Detailed Description

{comp}

comp Base class for references to objects.

The SBaseRef class was introduced by the SBML Level 3 Hierarchical Model Composition (“comp”) package as the principle way by which submodel elements may be referenced. The SBaseRef class is usually found as the base class of a Port, Deletion, ReplacedElement, or ReplacedBy class, but may appear as an child of one of the above classes if the parent object references a Submodel.

An SBaseRef object must reference an element using exactly one of the optional attributes of the class. Subclasses of SBaseRef may define additional optional attributes that are legal ways to reference an element.

SBaseRef objects may reference elements that do not live in the Model parent of the SBaseRef object. However, the SBaseRef class itself does not provide a method of determining which Model or Submodel is being referenced. The subclasses of SBaseRef provide methods for this instead.

Once the Model to which the SBaseRef object is referencing has been established, there are four optional attributes defined in the SBaseRef class that are each methods of referencing an element:

  • "portRef" (type PortSIdRef): As its name implies, this attribute is used to refer to a port identifier, in the case when the reference being constructed with the SBaseRef is intended to refer to a port on a submodel. The namespace of the PortSIdRef value is the set of identifiers of type PortSId defined in the submodel, not the parent model.
  • "idRef" (type SIdRef): As its name implies, this attribute is used to refer to a regular identifier (i.e., the value of an "id" attribute on some other object), in the case when the reference being constructed with the SBaseRef is intended to refer to an object that does not have a port identifier. The namespace of the SIdRef value is the set of identifiers of type SId defined in the submodel, not the parent model.
  • "unitRef" (type UnitSIdRef): This attribute is used to refer to the identifier of a UnitDefinition object. The namespace of the UnitSIdRef value is the set of unit identifiers defined in the submodel, not the parent model. (Note that even though this attribute is of type UnitSIdRef, the reserved unit identifiers that are defined by SBML Level 3 (see Section 3.1.10 of the core specification) are *not* permitted as values of "unitRef". Reserved unit identifiers may not be replaced or deleted.)
  • "metaIdRef" (type IDREF): This attribute is used to refer to a "metaid" attribute value on some other object, in the case when the reference being constructed with the SBaseRef is intended to refer to an object that does not have a port identifier. The namespace of the "metaIdRef" value is the entire document in which the referenced model resides, but must refer to a subelement of the referenced model. Since meta identifiers are optional attributes of SBase, all SBML objects have the potential to have a meta identifier value.

An SBaseRef object may have up to one subcomponent named "sBaseRef", of type SBaseRef. This permits recursive structures to be constructed so that objects inside submodels can be referenced.

The form of such recursive references must be as follows. The highest-level SBaseRef object of such a chain (which will necessarily be an object of class Port, Deletion, ReplacedElement or ReplacedBy, because they are the only classes derived from the class SBaseRef) must refer to a Submodel object in the containing model. All child SBaseRef objects in the chain must refer to components inside the Model instance to which the Submodel refers.

Public Member Functions

virtual void clearReferencedElement ()
 Removes the saved referenced element, if it had been saved earlier. More...
 
virtual SBaseRefclone () const
 Creates and returns a deep copy of this SBaseRef object. More...
 
SBaseRefcreateSBaseRef ()
 Creates a new, empty SBaseRef, adds it to this SBaseRef and returns the created SBaseRef. More...
 
virtual ListgetAllElements (ElementFilter *filter=NULL)
 Returns a List of all child SBase* objects, including those nested to an arbitrary depth. More...
 
virtual SBasegetElementByMetaId (const std::string &metaid)
 Returns the first child element it can find with the given metaid, or itself if it has the given metaid, or NULL if no such object is found. More...
 
virtual SBasegetElementBySId (const std::string &id)
 Returns the first child element found that has the given id in the model-wide SId namespace, or NULL if no such object is found. More...
 
virtual const std::string & getElementName () const
 Returns the XML element name of this SBML object. More...
 
virtual const std::string & getIdRef () const
 Returns the value of the "idRef" attribute of this SBaseRef. More...
 
virtual const std::string & getMetaIdRef () const
 Returns the value of the "metaIdRef" attribute of this SBaseRef. More...
 
virtual int getNumReferents () const
 Returns how many elements are being referred to by this SBaseRef. More...
 
virtual const std::string & getPortRef () const
 Returns the value of the "portRef" attribute of this SBaseRef. More...
 
virtual SBasegetReferencedElement ()
 Returns the object pointed to by this element. More...
 
virtual SBasegetReferencedElementFrom (Model *model)
 Examines the referenced Model for the referenced object, and returns it, if found. More...
 
const SBaseRefgetSBaseRef () const
 Get the child sBaseRef of this sBaseRef. More...
 
SBaseRefgetSBaseRef ()
 Get the child sBaseRef of this SBaseRef. More...
 
virtual int getTypeCode () const
 Returns the libSBML type code of this object instance. More...
 
virtual const std::string & getUnitRef () const
 Returns the value of the "unitRef" attribute of this SBaseRef. More...
 
virtual bool hasRequiredAttributes () const
 Returns true if getNumReferents() is exactly 1. More...
 
virtual bool isSetIdRef () const
 Predicate returning true or false depending on whether this SBaseRef's "idRef" attribute has been set. More...
 
virtual bool isSetMetaIdRef () const
 Predicate returning true or false depending on whether this SBaseRef's "metaIdRef" attribute has been set. More...
 
virtual bool isSetPortRef () const
 Predicate returning true or false depending on whether this SBaseRef's "portRef" attribute has been set. More...
 
bool isSetSBaseRef () const
 Predicate for testing whether the sBaseRef for this SBaseRef is set. More...
 
virtual bool isSetUnitRef () const
 Predicate returning true or false depending on whether this SBaseRef's "unitRef" attribute has been set. More...
 
SBaseRefoperator= (const SBaseRef &source)
 Assignment operator. More...
 
virtual int performDeletion ()
 DEPRECATED FUNCTION: DO NOT USE. More...
 
virtual int removeFromParentAndDelete ()
 Finds this SBaseRef's parent, which can either be a List or can be another SBaseRef, and tells it to remove this. More...
 
virtual void renameSIdRefs (const std::string &oldid, const std::string &newid)
 
virtual int saveReferencedElement ()
 Finds and stores the referenced object by finding the Model it needs to point to, calling 'saveReferencedElement' on its parent (which will also be a SBaseRef or one of its subclasses), and the storing the result. More...
 
 SBaseRef (unsigned int level=CompExtension::getDefaultLevel(), unsigned int version=CompExtension::getDefaultVersion(), unsigned int pkgVersion=CompExtension::getDefaultPackageVersion())
 Creates a new SBaseRef with the given level, version, and package version. More...
 
 SBaseRef (CompPkgNamespaces *compns)
 Creates a new SBaseRef with the given CompPkgNamespaces object. More...
 
 SBaseRef (const SBaseRef &source)
 Copy constructor. More...
 
virtual int setIdRef (const std::string &id)
 Sets the value of the "idRef" attribute of this SBaseRef. More...
 
virtual int setMetaIdRef (const std::string &id)
 Sets the value of the "metaIdRef" attribute of this SBaseRef. More...
 
virtual int setPortRef (const std::string &id)
 Sets the value of the "portRef" attribute of this SBaseRef. More...
 
int setSBaseRef (const SBaseRef *sBaseRef)
 Sets the sBaseRef definition of this SBaseRef to a copy of the given SBaseRef object instance. More...
 
virtual int setUnitRef (const std::string &id)
 Sets the value of the "unitRef" attribute of this SBaseRef. More...
 
virtual int unsetIdRef ()
 Unsets the value of the "idRef" attribute of this SBaseRef. More...
 
virtual int unsetMetaIdRef ()
 Unsets the value of the "metaIdRef" attribute of this SBaseRef. More...
 
virtual int unsetPortRef ()
 Unsets the value of the "portRef" attribute of this SBaseRef. More...
 
virtual int unsetSBaseRef ()
 Unsets the child SBaseRef of this SBaseRef. More...
 
virtual int unsetUnitRef ()
 Unsets the value of the "unitRef" attribute of this SBaseRef. More...
 
virtual ~SBaseRef ()
 Destructor. More...
 

Constructor & Destructor Documentation

§ SBaseRef() [1/3]

SBaseRef::SBaseRef ( unsigned int  level = CompExtension::getDefaultLevel(),
unsigned int  version = CompExtension::getDefaultVersion(),
unsigned int  pkgVersion = CompExtension::getDefaultPackageVersion() 
)

Creates a new SBaseRef with the given level, version, and package version.

Parameters
levelthe SBML Level
versionthe Version within the SBML Level
pkgVersionthe version of the package

§ SBaseRef() [2/3]

SBaseRef::SBaseRef ( CompPkgNamespaces compns)

Creates a new SBaseRef with the given CompPkgNamespaces object.

Parameters
compnsthe namespace to use

§ SBaseRef() [3/3]

SBaseRef::SBaseRef ( const SBaseRef source)

Copy constructor.

§ ~SBaseRef()

SBaseRef::~SBaseRef ( )
virtual

Destructor.

Member Function Documentation

§ clearReferencedElement()

void SBaseRef::clearReferencedElement ( )
virtual

Removes the saved referenced element, if it had been saved earlier.

§ clone()

SBaseRef * SBaseRef::clone ( ) const
virtual

Creates and returns a deep copy of this SBaseRef object.

Returns
a (deep) copy of this SBaseRef object

Reimplemented in ReplacedElement, Deletion, Port, and ReplacedBy.

§ createSBaseRef()

SBaseRef * SBaseRef::createSBaseRef ( )

Creates a new, empty SBaseRef, adds it to this SBaseRef and returns the created SBaseRef.

Returns
the newly created SBaseRef object instance.

§ getAllElements()

List * SBaseRef::getAllElements ( ElementFilter filter = NULL)
virtual

Returns a List of all child SBase* objects, including those nested to an arbitrary depth.

Returns
a List* of pointers to all children objects.

§ getElementByMetaId()

SBase * SBaseRef::getElementByMetaId ( const std::string &  metaid)
virtual

Returns the first child element it can find with the given metaid, or itself if it has the given metaid, or NULL if no such object is found.

Parameters
metaidstring representing the metaid of objects to find
Returns
a pointer to the SBase element with the given metaid.

§ getElementBySId()

SBase * SBaseRef::getElementBySId ( const std::string &  id)
virtual

Returns the first child element found that has the given id in the model-wide SId namespace, or NULL if no such object is found.

Parameters
idstring representing the id of objects to find
Returns
a pointer to the SBase element with the given id.

§ getElementName()

const std::string & SBaseRef::getElementName ( ) const
virtual

Returns the XML element name of this SBML object.

Returns
the name of this element, as a text string.

Reimplemented in ReplacedElement, Deletion, Port, and ReplacedBy.

§ getIdRef()

const string & SBaseRef::getIdRef ( ) const
virtual

Returns the value of the "idRef" attribute of this SBaseRef.

Returns
the value of the "idRef" attribute of this SBaseRef.

§ getMetaIdRef()

const string & SBaseRef::getMetaIdRef ( ) const
virtual

Returns the value of the "metaIdRef" attribute of this SBaseRef.

Returns
the value of the "metaIdRef" attribute of this SBaseRef.

§ getNumReferents()

int SBaseRef::getNumReferents ( ) const
virtual

Returns how many elements are being referred to by this SBaseRef.

A valid SBaseRef will have exactly one. Possible referents are portRef, idRef, unitRef, and metaIdRef.

Returns
integer value between 0 and 4: the number of different ways this element points to its referent.

Reimplemented in ReplacedElement.

§ getPortRef()

const string & SBaseRef::getPortRef ( ) const
virtual

Returns the value of the "portRef" attribute of this SBaseRef.

Returns
the value of the "portRef" attribute of this SBaseRef.

§ getReferencedElement()

SBase * SBaseRef::getReferencedElement ( )
virtual

Returns the object pointed to by this element.

If that element was previously found and set with 'saveReferencedElement', that element is returned; otherwise, 'saveReferencedElement' is called first, and the found element is returned.

§ getReferencedElementFrom()

SBase * SBaseRef::getReferencedElementFrom ( Model model)
virtual

Examines the referenced Model for the referenced object, and returns it, if found.

Parameters
modelthe Model in which to look for the object referenced by this SBaseRef.
Returns
the element in the referenced Model to which this SBaseRef refers. If this object references an object in a Submodel, the returned object will be in the instantiated Model in that Submodel.

Reimplemented in ReplacedElement.

§ getSBaseRef() [1/2]

const SBaseRef * SBaseRef::getSBaseRef ( ) const

Get the child sBaseRef of this sBaseRef.

Returns
the const SBaseRef child of this SBaseRef, or NULL if none exists.

§ getSBaseRef() [2/2]

SBaseRef * SBaseRef::getSBaseRef ( )

Get the child sBaseRef of this SBaseRef.

Returns
the SBaseRef child of this SBaseRef, or NULL if none exists.

§ getTypeCode()

int SBaseRef::getTypeCode ( ) const
virtual

Returns the libSBML type code of this object instance.

LibSBML attaches an identifying code to every kind of SBML object. These are integer constants known as SBML type codes. The names of all the codes begin with the characters SBML_. The set of possible type codes for core elements is defined in the enumeration SBMLTypeCode_t, and in addition, libSBML plug-ins for SBML Level 3 packages define their own extra enumerations of type codes (e.g., SBMLLayoutTypeCode_t for the Level 3 Layout package). Note that different Level 3 package plug-ins may use overlapping type codes; to identify the package to which a given object belongs, call the getPackageName() method on the object.
Returns
the SBML type code for this object: SBML_COMP_SBASEREFendif

Reimplemented in ReplacedElement, Deletion, Port, and ReplacedBy.

§ getUnitRef()

const string & SBaseRef::getUnitRef ( ) const
virtual

Returns the value of the "unitRef" attribute of this SBaseRef.

Returns
the value of the "unitRef" attribute of this SBaseRef.

§ hasRequiredAttributes()

bool SBaseRef::hasRequiredAttributes ( ) const
virtual

Returns true if getNumReferents() is exactly 1.

Returns
boolean: 'true' if the attributes are correctly set; 'false' if not.

Reimplemented in Port, and Replacing.

§ isSetIdRef()

bool SBaseRef::isSetIdRef ( ) const
virtual

Predicate returning true or false depending on whether this SBaseRef's "idRef" attribute has been set.

Returns
true if this SBaseRef's "idRef" attribute has been set, otherwise false is returned.

§ isSetMetaIdRef()

bool SBaseRef::isSetMetaIdRef ( ) const
virtual

Predicate returning true or false depending on whether this SBaseRef's "metaIdRef" attribute has been set.

Returns
true if this SBaseRef's "metaIdRef" attribute has been set, otherwise false is returned.

§ isSetPortRef()

bool SBaseRef::isSetPortRef ( ) const
virtual

Predicate returning true or false depending on whether this SBaseRef's "portRef" attribute has been set.

Returns
true if this SBaseRef's "portRef" attribute has been set, otherwise false is returned.

§ isSetSBaseRef()

bool SBaseRef::isSetSBaseRef ( ) const

Predicate for testing whether the sBaseRef for this SBaseRef is set.

Returns
true if the sBaseRef of this SBaseRef is set, false otherwise.

§ isSetUnitRef()

bool SBaseRef::isSetUnitRef ( ) const
virtual

Predicate returning true or false depending on whether this SBaseRef's "unitRef" attribute has been set.

Returns
true if this SBaseRef's "unitRef" attribute has been set, otherwise false is returned.

§ operator=()

SBaseRef & SBaseRef::operator= ( const SBaseRef source)

Assignment operator.

§ performDeletion()

int SBaseRef::performDeletion ( )
virtual

DEPRECATED FUNCTION: DO NOT USE.

Deletes the referenced object, plus any other elements that element points to through ReplacedElement or ReplacedBy children. Instead of calling this function directly, use 'CompModelPlugin::instantiateSubmodels' instead, which deals with all the intricacies of replacements and deletions, and gives you access to the non-flattened hierarchical form of the model.

§ removeFromParentAndDelete()

int SBaseRef::removeFromParentAndDelete ( )
virtual

Finds this SBaseRef's parent, which can either be a List or can be another SBaseRef, and tells it to remove this.

Reimplemented in ReplacedBy.

§ renameSIdRefs()

void SBaseRef::renameSIdRefs ( const std::string &  oldid,
const std::string &  newid 
)
virtual

Reimplemented in ReplacedElement, Port, and Replacing.

§ saveReferencedElement()

int SBaseRef::saveReferencedElement ( )
virtual

Finds and stores the referenced object by finding the Model it needs to point to, calling 'saveReferencedElement' on its parent (which will also be a SBaseRef or one of its subclasses), and the storing the result.

Reimplemented in Deletion, Port, and Replacing.

§ setIdRef()

int SBaseRef::setIdRef ( const std::string &  id)
virtual

Sets the value of the "idRef" attribute of this SBaseRef.

This method fails if the id is not a valid syntax for an SIdRef (LIBSBML_INVALID_ATTRIBUTE_VALUEendif

Examples:
spec_example2.cpp, spec_example3.cpp, and spec_example4.cpp.

§ setMetaIdRef()

int SBaseRef::setMetaIdRef ( const std::string &  id)
virtual

Sets the value of the "metaIdRef" attribute of this SBaseRef.

This method fails if the id is not a valid syntax for an IDREF (LIBSBML_INVALID_ATTRIBUTE_VALUEendif

§ setPortRef()

int SBaseRef::setPortRef ( const std::string &  id)
virtual

Sets the value of the "portRef" attribute of this SBaseRef.

Fails if the id is not a valid syntax for a PortSIdRef (LIBSBML_INVALID_ATTRIBUTE_VALUEendif

Reimplemented in Port.

Examples:
spec_example3.cpp, and spec_example4.cpp.

§ setSBaseRef()

int SBaseRef::setSBaseRef ( const SBaseRef sBaseRef)

Sets the sBaseRef definition of this SBaseRef to a copy of the given SBaseRef object instance.

This method fails if the added sBaseRef does not match the level/version/package of the parent object or if the added sBaseRef cannot be copied.

Parameters
sBaseRefthe SBaseRef object instance to use.

§ setUnitRef()

int SBaseRef::setUnitRef ( const std::string &  id)
virtual

Sets the value of the "unitRef" attribute of this SBaseRef.

This method fails if the id is not a valid syntax for a UnitSIdRef (LIBSBML_INVALID_ATTRIBUTE_VALUEendif

§ unsetIdRef()

int SBaseRef::unsetIdRef ( )
virtual

Unsets the value of the "idRef" attribute of this SBaseRef.

Examples:
spec_example3.cpp, and spec_example4.cpp.

§ unsetMetaIdRef()

int SBaseRef::unsetMetaIdRef ( )
virtual

Unsets the value of the "metaIdRef" attribute of this SBaseRef.

§ unsetPortRef()

int SBaseRef::unsetPortRef ( )
virtual

Unsets the value of the "portRef" attribute of this SBaseRef.

§ unsetSBaseRef()

int SBaseRef::unsetSBaseRef ( )
virtual

Unsets the child SBaseRef of this SBaseRef.

Deletes the former SBaseRef child, if one existed.

§ unsetUnitRef()

int SBaseRef::unsetUnitRef ( )
virtual

Unsets the value of the "unitRef" attribute of this SBaseRef.