.. include:: ../substitutions

.. oe:namespace:: OEChem

.. meta::
   :keywords: OEWriteConstMolecule

.. oe:function:: OEWriteConstMolecule

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

      .. oe:api::

         unsigned OEWriteConstMolecule(oemolostream& ofs, const OEGraphMol& mol)
         unsigned OEWriteConstMolecule(oemolostream& ofs, const OEMol& mol)
         unsigned OEWriteConstMolecule(oemolostream& ofs, const OEQMol& mol)
         unsigned OEWriteConstMolecule(oemolostream& ofs, const OEMolBase& mol)
         unsigned OEWriteConstMolecule(oemolostream& ofs, const OEMCMolBase& mol
         unsigned OEWriteConstMolecule(oemolostream& ofs, const OEQMolBase& mol)

   .. oe:language:: python

      .. oe:api:: python

         OEWriteConstMolecule(ofs: oemolostream, mol: OEGraphMol) -> int
         OEWriteConstMolecule(ofs: oemolostream, mol: OEMol) -> int
         OEWriteConstMolecule(ofs: oemolostream, mol: OEQMol) -> int


   These functions provide high-level file format writers for multiple file
   formats.  These functions are built on top of **OEChem TK**'s low-level file
   format writers.  If needed, these functions will make a copy of the
   molecule in order to automatically invoke the appropriate perception
   routines (aromaticity, atom typing, chirality perception, residue
   perception, etc...) as required by the selected file format.
   This greatly simplifies the task of writing molecules to a stream,
   but may provide less control than calling the lower-level functions
   directly.

   Since these functions may make a copy of the molecule they'll generally
   be slower than the analogous :oe:func:`OEChem::OEWriteMolecule` functions,
   which modify the molecule directly.

   All of the overloads of :oe:func:`OEChem::OEWriteConstMolecule` functions
   return an error code from the :oe:constns:`OEChem::OEWriteMolReturnCode`
   namespace.
   A return code of ``0`` or :oe:const:`OEChem::OEWriteMolReturnCode::Success`
   indicates the write had no problems.

   ofs
     The output stream into which the molecule will be written.

     The file format controlled by the format field of the
     :ref:`oemolostream <OEChem_oemolostream>` which may be set and retrieved using
     the methods :oe:meth:`OEChem::oemolstreambase::SetFormat`, and
     :oe:meth:`OEChem::oemolstreambase::GetFormat` respectively.

     Additionally, the :oe:func:`OEChem::OEWriteConstMolecule` functions provide
     some level of control over the processing applied to a molecule prior
     to writing using **OEChem TK**'s file format flavor mechanism.
     Each output molecule stream maintains an independent 'flavor' value for
     each output file format that can be specified by
     :oe:meth:`OEChem::oemolstreambase::SetFlavor`.
     These 'flavors' are unsigned integer values that are the combination
     of bit patterns specified by the :oe:constns:`OEChem::OEOFlavor` namespace.
     The interpretation of each bit in a flavor depends upon the output file
     format to which it refers, and enables or disables processing
     associated with writing that output file format.

   mol
     The molecule that is written into the stream.

.. seealso::

   * :oe:constns:`OEChem::OEWriteMolReturnCode` namespace
   * :ref:`the OEFormat namespace <OEChem_OEFormat>`
   * :oe:constns:`OEChem::OEOFlavor` namespace
   * :oe:func:`OEChem::OEWriteMolecule` function

   .. oe:language:: c++

      * Example program :ref:`cliquealign.cpp<section_example_oechem_cliquealign>`

   .. oe:language:: python

      * Example program :ref:`cliquealign.py<section_example_oechem_cliquealign>`

   .. oe:language:: java

      * Example program :ref:`CliqueAlign.java<section_example_oechem_cliquealign>`

   .. oe:language:: csharp

      * Example program :ref:`CliqueAlign.cs<section_example_oechem_cliquealign>`
