API: simplify/improve the API for external variables

CMakeLists.txt

@@ -19,7 +19,7 @@ set(CMAKE_OSX_DEPLOYMENT_TARGET 10.15 CACHE STRING "Minimum OS X deployment vers
 set(PROJECT_NAME libCellML)
 set(PROJECT_URL https://libcellml.org)
 set(_PROJECT_VERSION 0.6.3)
-set(PROJECT_DEVELOPER_VERSION )
+set(PROJECT_DEVELOPER_VERSION)
 project(${PROJECT_NAME} VERSION ${_PROJECT_VERSION} LANGUAGES CXX)
 
 # Set policies that affect the build.

src/analyser.cpp

@@ -622,9 +622,7 @@ class Analyser::AnalyserImpl: public Logger::LoggerImpl
 
     void analyseModel(const ModelPtr &model);
 
-    AnalyserExternalVariablePtrs::const_iterator findExternalVariable(const ModelPtr &model,
-                                                                      const std::string &componentName,
-                                                                      const std::string &variableName) const;
+    AnalyserExternalVariablePtrs::const_iterator findExternalVariable(const VariablePtr &variable) const;
     AnalyserExternalVariablePtrs::const_iterator findExternalVariable(const AnalyserExternalVariablePtr &externalVariable) const;
 };
 
@@ -742,34 +740,36 @@ void Analyser::AnalyserImpl::analyseNode(const XmlNodePtr &node,
         //                 +-------------+
 
         auto childCount = mathmlChildCount(node);
-        AnalyserEquationAstPtr tempAst;
-        AnalyserEquationAstPtr astRightChild;
 
-        for (size_t i = childCount - 1; i > 0; --i) {
-            astRightChild = tempAst;
-            tempAst = AnalyserEquationAst::create();
+        analyseNode(mathmlChildNode(node, 0), ast, astParent, component, equation);
+
+        if (childCount >= 2) {
+            analyseNode(mathmlChildNode(node, 1), ast->mPimpl->mOwnedLeftChild, ast, component, equation);
+
+            if (childCount >= 3) {
+                AnalyserEquationAstPtr astRightChild;
+                AnalyserEquationAstPtr tempAst;
+
+                analyseNode(mathmlChildNode(node, childCount - 1), astRightChild, nullptr, component, equation);
+
+                for (auto i = childCount - 2; i > 1; --i) {
+                    tempAst = AnalyserEquationAst::create();
+
+                    analyseNode(mathmlChildNode(node, 0), tempAst, nullptr, component, equation);
+                    analyseNode(mathmlChildNode(node, i), tempAst->mPimpl->mOwnedLeftChild, tempAst, component, equation);
 
-            if (astRightChild != nullptr) {
-                if (i == childCount - 2) {
-                    astRightChild->swapLeftAndRightChildren();
-                    tempAst = astRightChild;
-                } else {
                     astRightChild->mPimpl->mParent = tempAst;
+
                     tempAst->mPimpl->mOwnedRightChild = astRightChild;
+                    astRightChild = tempAst;
                 }
-            }
 
-            if (i != childCount - 2) {
-                analyseNode(mathmlChildNode(node, 0), tempAst, nullptr, component, equation);
-            }
+                astRightChild->mPimpl->mParent = ast;
 
-            analyseNode(mathmlChildNode(node, i), tempAst->mPimpl->mOwnedLeftChild, tempAst, component, equation);
+                ast->mPimpl->mOwnedRightChild = astRightChild;
+            }
         }
 
-        analyseNode(mathmlChildNode(node, 0), tempAst, astParent, component, equation);
-
-        ast = tempAst;
-
         // Relational and logical operators.
 
     } else if (node->isMathmlElement("eq")) {
@@ -3308,16 +3308,10 @@ void Analyser::AnalyserImpl::analyseModel(const ModelPtr &model)
     }
 }
 
-AnalyserExternalVariablePtrs::const_iterator Analyser::AnalyserImpl::findExternalVariable(const ModelPtr &model,
-                                                                                          const std::string &componentName,
-                                                                                          const std::string &variableName) const
+AnalyserExternalVariablePtrs::const_iterator Analyser::AnalyserImpl::findExternalVariable(const VariablePtr &variable) const
 {
     return std::find_if(mExternalVariables.begin(), mExternalVariables.end(), [=](const auto &ev) {
-        auto variable = ev->variable();
-
-        return (owningModel(variable) == model)
-               && (owningComponent(variable)->name() == componentName)
-               && (variable->name() == variableName);
+        return ev->variable() == variable;
     });
 }
 
@@ -3405,6 +3399,19 @@ void Analyser::analyseModel(const ModelPtr &model)
     }
 }
 
+bool Analyser::addExternalVariable(const VariablePtr &variable)
+{
+    for (const auto &externalVariable : pFunc()->mExternalVariables) {
+        if (externalVariable->variable() == variable) {
+            return false;
+        }
+    }
+
+    pFunc()->mExternalVariables.push_back(AnalyserExternalVariable::create(variable));
+
+    return true;
+}
+
 bool Analyser::addExternalVariable(const AnalyserExternalVariablePtr &externalVariable)
 {
     if (std::find(pFunc()->mExternalVariables.begin(), pFunc()->mExternalVariables.end(), externalVariable) == pFunc()->mExternalVariables.end()) {
@@ -3427,11 +3434,9 @@ bool Analyser::removeExternalVariable(size_t index)
     return false;
 }
 
-bool Analyser::removeExternalVariable(const ModelPtr &model,
-                                      const std::string &componentName,
-                                      const std::string &variableName)
+bool Analyser::removeExternalVariable(const VariablePtr &variable)
 {
-    auto result = pFunc()->findExternalVariable(model, componentName, variableName);
+    auto result = pFunc()->findExternalVariable(variable);
 
     if (result != pFunc()->mExternalVariables.end()) {
         pFunc()->mExternalVariables.erase(result);
@@ -3460,11 +3465,9 @@ void Analyser::removeAllExternalVariables()
     pFunc()->mExternalVariables.clear();
 }
 
-bool Analyser::containsExternalVariable(const ModelPtr &model,
-                                        const std::string &componentName,
-                                        const std::string &variableName) const
+bool Analyser::containsExternalVariable(const VariablePtr &variable) const
 {
-    return pFunc()->findExternalVariable(model, componentName, variableName) != pFunc()->mExternalVariables.end();
+    return pFunc()->findExternalVariable(variable) != pFunc()->mExternalVariables.end();
 }
 
 bool Analyser::containsExternalVariable(const AnalyserExternalVariablePtr &externalVariable) const
@@ -3481,11 +3484,9 @@ AnalyserExternalVariablePtr Analyser::externalVariable(size_t index) const
     return nullptr;
 }
 
-AnalyserExternalVariablePtr Analyser::externalVariable(const ModelPtr &model,
-                                                       const std::string &componentName,
-                                                       const std::string &variableName) const
+AnalyserExternalVariablePtr Analyser::externalVariable(const VariablePtr &variable) const
 {
-    auto result = pFunc()->findExternalVariable(model, componentName, variableName);
+    auto result = pFunc()->findExternalVariable(variable);
 
     if (result != pFunc()->mExternalVariables.end()) {
         return *result;

src/api/libcellml/analyser.h

@@ -59,10 +59,23 @@ class LIBCELLML_EXPORT Analyser: public Logger
     void analyseModel(const ModelPtr &model);
 
     /**
+     * @brief Add a @ref VariablePtr as an external variable to this @ref Analyser.
+     *
+     * Add the given @ref VariablePtr as an external variable to this @ref Analyser, but only if it has not already been
+     * added.
+     *
+     * @param variable The @ref Variable to add as an external variable.
+     *
+     * @return @c true if the variable was added, @c false otherwise.
+     */
+    bool addExternalVariable(const VariablePtr &variable);
+
+    /**
+     * @overload
+     *
      * @brief Add an @ref AnalyserExternalVariable to this @ref Analyser.
      *
-     * Add the given @ref AnalyserExternalVariable to this @ref Analyser, but only
-     * if the given @ref AnalyserExternalVariable has not already been added.
+     * Add the given @ref AnalyserExternalVariable to this @ref Analyser, but only if it has not already been added.
      *
      * @param externalVariable The @ref AnalyserExternalVariable to add.
      *
@@ -73,150 +86,107 @@ class LIBCELLML_EXPORT Analyser: public Logger
     /**
      * @brief Remove the @ref AnalyserExternalVariable at the given @p index.
      *
-     * Remove the @ref AnalyserExternalVariable with the given @p index. The
-     * @p index must be in the range [0, \#externalVariables).
+     * Remove the @ref AnalyserExternalVariable with the given @p index. The @p index must be in the range
+     * [0, \#externalVariables).
      *
      * @param index The index of the @ref AnalyserExternalVariable to remove.
      *
-     * @return @c true if the @ref AnalyserExternalVariable was removed, @c false
-     * otherwise.
+     * @return @c true if the @ref AnalyserExternalVariable was removed, @c false otherwise.
      */
     bool removeExternalVariable(size_t index);
 
     /**
      * @overload
      *
-     * @brief Remove the @ref AnalyserExternalVariable with the given
-     * @p variableName in the @ref Component with the given @p componentName in
-     * the given @p model.
+     * @brief Remove the @ref AnalyserExternalVariable for the given @p variable.
      *
-     * Remove the @ref AnalyserExternalVariable found that matches the given
-     * @p variableName in the @ref Component with the given @p componentName in
-     * the given @p model.
+     * Remove the @ref AnalyserExternalVariable found that matches the given @p variable.
      *
-     * @param model The pointer to the @ref Model which contains the
-     * @ref AnalyserExternalVariable to remove.
-     * @param componentName The name of the @ref Component which contains the
-     * @ref AnalyserExternalVariable to remove.
-     * @param variableName The name of the @ref AnalyserExternalVariable to
-     * remove.
+     * @param variable The @ref Variable for which to remove the @ref AnalyserExternalVariable.
      *
-     * @return @c true if the @ref AnalyserExternalVariable was removed, @c false
-     * otherwise.
+     * @return @c true if the @ref AnalyserExternalVariable was removed, @c false otherwise.
      */
-    bool removeExternalVariable(const ModelPtr &model,
-                                const std::string &componentName,
-                                const std::string &variableName);
+    bool removeExternalVariable(const VariablePtr &variable);
 
     /**
      * @overload
      *
-     * @brief Remove the @ref AnalyserExternalVariable with the given pointer.
+     * @brief Remove the @ref AnalyserExternalVariable for the given @p externalVariable.
      *
-     * Remove the @ref AnalyserExternalVariable with the pointer
-     * @p externalVariable.
+     * Remove the @ref AnalyserExternalVariable for the given @p externalVariable.
      *
-     * @param externalVariable The pointer to the @ref AnalyserExternalVariable to remove.
+     * @param externalVariable The @ref AnalyserExternalVariable to remove.
      *
-     * @return @c true if the @ref AnalyserExternalVariable was removed, @c false
-     * otherwise.
+     * @return @c true if the @ref AnalyserExternalVariable was removed, @c false otherwise.
      */
     bool removeExternalVariable(const AnalyserExternalVariablePtr &externalVariable);
 
     /**
-     * @brief Remove all @ref AnalyserExternalVariable items from this
-     * @ref Analyser.
+     * @brief Remove all the @ref AnalyserExternalVariable items from this @ref Analyser.
      *
-     * Clear all @ref AnalyserExternalVariable items that have been added to this
-     * @ref Analyser.
+     * Remove all the @ref AnalyserExternalVariable items that were added to this @ref Analyser.
      */
     void removeAllExternalVariables();
 
     /**
-     * @brief Test to see if the @ref AnalyserExternalVariable with the given
-     * @p variableName in the @ref Component with the given @p componentName in
-     * the given @p model is contained within this @ref Analyser.
-     *
-     * Test to see if the @ref AnalyserExternalVariable with the the given
-     * @p variableName in the @ref Component with the given @p componentName in
-     * the given @p model is contained within this @ref Analyser. Return @c true
-     * if the @ref AnalyserExternalVariable is in the @ref Analyser and @c false
+     * @brief Test to see if an @ref AnalyserExternalVariable for the given @p variable is contained within this
+     * @ref Analyser.
+     *
+     * Test to see if an @ref AnalyserExternalVariable for the the given @p variable is contained within this
+     * @ref Analyser. Return @c true if an @ref AnalyserExternalVariable is in this @ref Analyser and @c false
      * otherwise.
      *
-     * @param model The pointer to the @ref Model which contains the
-     * @ref AnalyserExternalVariable to test.
-     * @param componentName The name of the @ref Component which contains the
-     * @ref AnalyserExternalVariable to test.
-     * @param variableName The name of the @ref AnalyserExternalVariable to test.
+     * @param variable The @ref Variable to test.
      *
-     * @return @c true if the @ref AnalyserExternalVariable is in this @ref Analyser
-     * and @c false otherwise.
+     * @return @c true if an @ref AnalyserExternalVariable is in this @ref Analyser, @c false otherwise.
      */
-    bool containsExternalVariable(const ModelPtr &model,
-                                  const std::string &componentName,
-                                  const std::string &variableName) const;
+    bool containsExternalVariable(const VariablePtr &variable) const;
 
     /**
      * @overload
      *
-     * @brief Test to see if the @ref AnalyserExternalVariable with the given
-     * pointer is contained within this @ref Analyser.
+     * @brief Test to see if an @ref AnalyserExternalVariable for the given @p externalVariable is contained within this
+     * @ref Analyser.
      *
-     * Test to see if the @ref AnalyserExternalVariable with the given pointer is
-     * contained within this @ref Analyser. Return @c true if the
-     * @ref AnalyserExternalVariable is in the @ref Analyser and @c false otherwise.
+     * Test to see if an @ref AnalyserExternalVariable for the given @p externalVariable is contained within this
+     * @ref Analyser. Return @c true if an @ref AnalyserExternalVariable is in this @ref Analyser, @c false otherwise.
      *
-     * @param externalVariable The pointer to the @ref AnalyserExternalVariable to remove.
+     * @param externalVariable The @ref AnalyserExternalVariable to test.
      *
-     * @return @c true if the @ref AnalyserExternalVariable is in this @ref Analyser
-     * and @c false otherwise.
+     * @return @c true if an @ref AnalyserExternalVariable is in this @ref Analyser, @c false otherwise.
      */
     bool containsExternalVariable(const AnalyserExternalVariablePtr &externalVariable) const;
 
     /**
      * @brief Get the @ref AnalyserExternalVariable at the given @p index.
      *
-     * Return a reference to the @ref AnalyserExternalVariable at the given
-     * @p index. The @p index must be in the range [0, \#externalVariables).
+     * Return the @ref AnalyserExternalVariable at the given @p index. The @p index must be in the range
+     * [0, \#externalVariables).
      *
      * @param index The index of the @ref AnalyserExternalVariable to return.
      *
-     * @return The @ref AnalyserExternalVariable at the given @p index on success,
-     * @c nullptr on failure.
+     * @return The @ref AnalyserExternalVariable at the given @p index on success, @c nullptr on failure.
      */
     AnalyserExternalVariablePtr externalVariable(size_t index) const;
 
     /**
      * @overload
      *
-     * @brief Get the @ref AnalyserExternalVariable with the given @p name.
+     * @brief Get the @ref AnalyserExternalVariable for the given @p variable.
      *
-     * Return the @ref AnalyserExternalVariable with the given @p variableName in
-     * the @ref Component with the given @p componentName in the given @p model.
-     * If no such @ref AnalyserExternalVariable is contained within the
-     * @ref Analyser, a @c nullptr is returned.
+     * Return the @ref AnalyserExternalVariable for the given @p variable. If no such @ref AnalyserExternalVariable is
+     * contained within this @ref Analyser, a @c nullptr is returned.
      *
-     * @param model The pointer to the @ref Model which contains the
-     * @ref AnalyserExternalVariable to retrieve.
-     * @param componentName The name of the @ref Component which contains the
-     * @ref AnalyserExternalVariable to retrieve.
-     * @param variableName The name of the @ref AnalyserExternalVariable to
-     * retrieve.
+     * @param variable The @ref Variable for which to retrieve the @ref AnalyserExternalVariable.
      *
-     * @return The @ref AnalyserExternalVariable with the given @p variableName in
-     * the @ref Component with the given @p componentName in the given @p model on
-     * success, @c nullptr on failure.
+     * @return The @ref AnalyserExternalVariable for the given @p variable on success, @c nullptr on failure.
      */
-    AnalyserExternalVariablePtr externalVariable(const ModelPtr &model,
-                                                 const std::string &componentName,
-                                                 const std::string &variableName) const;
+    AnalyserExternalVariablePtr externalVariable(const VariablePtr &variable) const;
 
     /**
-     * @brief Get the number of @ref AnalyserExternalVariable items in this
-     * @ref Analyser.
+     * @brief Get the number of @ref AnalyserExternalVariable items in this @ref Analyser.
      *
-     * Return the number of @ref AnalyserExternalVariable items the @ref Analyser
-     * contains.
+     * Return the number of @ref AnalyserExternalVariable items this @ref Analyser contains.
      *
      * @return The number of @ref AnalyserExternalVariable items.
      */

src/bindings/interface/analyser.i

@@ -17,19 +17,16 @@
 "Adds a variable as an external variable to this analyser.";
 
 %feature("docstring") libcellml::Analyser::removeExternalVariable
-"Removes an external variable specified by 1) an index, 2) a :class:`Model` object, component name and variable
-name, or 3) a :class:`Variable` object. Returns `True` on success.";
+"Removes an external variable specified by 1) an index, 2) a :class:`Variable` object, or 3) an :class:`AnalyserExternalVariable` object. Returns `True` on success.";
 
 %feature("docstring") libcellml::Analyser::removeAllExternalVariables
 "Removes all external variables from this analyser.";
 
 %feature("docstring") libcellml::Analyser::containsExternalVariable
-"Tests if an external variable, specified by 1) a :class:`Model` object, component name and variable name, or 2)
-an :class:`AnalyserExternalVariable` object, is contained within this analyser.";
+"Tests if an external variable, specified by 1) a :class:`Variable` object, or 2) an :class:`AnalyserExternalVariable` object, is contained within this analyser.";
 
 %feature("docstring") libcellml::Analyser::externalVariable
-"Returns the external variable, specified by 1) an index, or 2) a :class:`Model` object, component name and
-variable name.";
+"Returns the external variable, specified by 1) an index, or 2) a :class:`Variable` object.";
 
 %feature("docstring") libcellml::Analyser::externalVariableCount
 "Returns the number of external variables this analyser contains.";