.. include:: ../substitutions

.. oe:namespace:: OEChem

.. meta::
   :keywords: OEAddMols

.. oe:function:: OEAddMols

   .. oe:language:: python

      .. oe:api::

         OEAddMols(dst: OEMolBase, src: OEMolBase) -> amap: List[OEAtomBase], bmap: List[OEBondBase]
         OEAddMols(dst: OEMolBase, src: OEMolBase, delim: str) -> amap: List[OEAtomBase], bmap: List[OEBondBase]

      Adds the one molecule to another molecule.

      dst
        The destination molecule.

      src
        The molecule that will be added to the destination molecule.

      delim
        The delimiter used to concatenate the title of the two molecules.
        The empty string (*e.g.* ``""``) is a valid argument, and
        causes a direct concatenation of the two titles.
        If ``None`` is passed as the argument, no concatenation of
        titles occurs.
        If not specified ``_`` character will be used as to concatenate
        the titles together.

      amap
         Stores mappings between the atoms in the original ``src`` molecule and the
         newly created atoms in the ``dst`` molecule.
         The newly created atom that is corresponding to a source atom can be obtained
         by atom index lookup into the list.

         .. oe:source:: OEAddMols.py
            :language: python
            :noindent:
            :frag:     SNIPPET-OEADDMOL-ATOMMAP

      bmap
         Stores mappings between the bonds in the original ``src`` molecule and the
         newly created bonds in the ``dst`` molecule.
         The newly created bond that is corresponding to a source bond can be obtained
         by bond index lookup into the list.

         .. oe:source:: OEAddMols.py
            :language: python
            :noindent:
            :frag:     SNIPPET-OEADDMOL-BONDMAP

      **Example:**

      .. oe:source:: OEAddMols.py
         :language: python
         :noindent:
         :frag:     SNIPPET-OEADDMOLS

      The above code snippet will generate the following output:

      .. code-block:: console

         ('c1ccccc1.c1ccncc1', 'benzene+pyridine')
          6 C  7 C  8 N  9 C 10 C 11 C
          6 (6C-11C)  7 (6C-7C)  8 (7C-8N)  9 (8N-9C) 10 (9C-10C) 11 (10C-11C)


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

      .. oe:api::

         bool OEAddMols(OEMolBase& dst, const OEMolBase& src,
                        OEAtomBase** amap = (OEAtomBase **) 0,
                        OEBondBase** bmap = (OEBondBase **) 0)
         bool OEAddMols(OEMolBase& dst, const OEMolBase& src,
                        const char* delim,
                        OEAtomBase** amap = (OEAtomBase **) 0,
                        OEBondBase** bmap = (OEBondBase **) 0)

      Adds the one molecule to another molecule.

      dst
        The destination molecule.

      src
        The molecule that will be added to the destination molecule.

      delim
        The delimiter used to concatenate the title of the two molecules.
        The empty string (*e.g.* ``""``) is a valid argument, and
        causes a direct concatenation of the two titles.
        If ``(char *)0`` is passed as the argument, no concatenation of
        titles occurs.
        If not specified ``_`` character will be used as to concatenate
        the titles together.

      amap
         This parameter can be used to obtain mappings between the atoms
         in the original ``src`` molecule and the newly created atoms
         in the ``dst`` molecule.
         It is assumed that argument passed to ``amap`` is array of atom pointers
         of at least :oe:meth:`src.GetMaxAtomIdx()<OEChem::OEMolBase::GetMaxAtomIdx>` in
         size.

         The newly created atom corresponding to a source atom can be obtained
         by atom index lookup into the ``amap`` array.

      bmap
         This parameter can be used to obtain mappings between the bonds
         in the original ``src`` molecule and the newly created bonds
         in the ``dst`` molecule.
         It is assumed that argument passed to ``bmap`` is array of bond pointers
         of at least :oe:meth:`src.GetMaxBondIdx()<OEChem::OEMolBase::GetMaxAtomIdx>` in size.

         The newly created atom corresponding to a source atom can be obtained
         by atom index lookup into the ``bmap`` array.

   .. note::

      :oe:func:`OEChem::OEAddMols` will not generate bonds between the
      molecules added.

   .. seealso::

      .. oe:language:: c++

          * Example program :ref:`catmols.cpp<section_example_oechem_catmols>`

      .. oe:language:: python

          * Example program :ref:`catmols.py<section_example_oechem_catmols>`

      .. oe:language:: java

          * Example program :ref:`CatMols.java<section_example_oechem_catmols>`

      .. oe:language:: csharp

          * Example program :ref:`CatMols.cs<section_example_oechem_catmols>`
