.. include:: ../../toolkit-substitutions

.. oe:namespace:: OEBio

..  _OEBio_OEUpdateDesignUnit:

.. oe:function:: OEUpdateDesignUnit

   .. attention::

      |TWOLANGUAGE|

   .. oe:language:: c++ java csharp

      .. oe:api::

         bool OEUpdateDesignUnit(OEDesignUnit& du,
                                 const OEChem::OEMolBase& mol,
                                 const unsigned componentId,
                                 const bool retainStyle = false,
                                 const int listIndex = -1)

   .. oe:language:: python

      .. oe:api:: python

         OEUpdateDesignUnit(du: OEDesignUnit,
                            mol: Union[OEGraphMol,OEMol,OEQMol],
                            componentId: int, retainStyle: bool = False,
                            listIndex: int = -1) -> bool

   This function updates an existing :ref:`OEDesignUnit <OEBio_OEDesignUnit>`
   object ``du`` by setting the component given by ``componentId``
   with the input molecule ``mol``, the input molecule must be valid (not empty). 
   The component ID should be specified from constants in the 
   :oe:constns:`OEBio::OEDesignUnitComponents` namespace.
   The optional parameter ``retainStyle`` retains the style on the input molecule, 
   otherwise undergoes standard OEDesignUnit object styling (default).
   If the update function is called with an empty molecule the function returns false.
   In the event the update operation fails due to the inability to update a specific component,
   the function returns false, and the input ``du`` is cleared.
   
    .. note::

       List components, co-factors, excipients etc. are updated by appending to the list. 
       To modify one of them, we recommend getting all the molecule components from a 
       list (e.g. co-facors), clearing that component in the designunit and adding
       the co-factors back where one or more have been modified.

    .. warning::

       Updating the content of a design unit invalidates the :ref:`OEReceptor <OEBio_OEReceptor>` object stored on the design unit
       and it will be removed as part of the update.

   .. seealso::
      
      * :ref:`OEDesignUnit <OEBio_OEDesignUnit>` class
      * :oe:constns:`OEBio::OEDesignUnitComponents` namespace
      * :oe:func:`OEBio::OESubsetDesignUnit` function


   **Examples**

   The example below demonstrate how to use
   :oe:func:`OEBio::OEUpdateDesignUnit` to
   update an existing :ref:`OEDesignUnit <OEBio_OEDesignUnit>` object.

   .. oe:source:: DesignUnit.py
      :language: python
      :noindent:
      :frag:     SNIPPET-OEUpdateDesignUnit

   .. oe:source:: DesignUnit.cpp
      :language: c++
      :noindent:
      :frag:     SNIPPET-OEUpdateDesignUnit
