.. include:: ../substitutions

.. oe:namespace:: OEChem

.. meta::
   :keywords: OEWriteMolecule

..  _oechem_oewritemolecule:

.. oe:function:: OEWriteMolecule

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

      .. oe:api::

         unsigned int OEWriteMolecule(oemolostream& ofs, OEGraphMol& mol)
         unsigned int OEWriteMolecule(oemolostream& ofs, OEMol& mol)
         unsigned int OEWriteMolecule(oemolostream& ofs, OEQMol& mol)
         unsigned int OEWriteMolecule(oemolothread& ofs, OEMolBase& mol)
         unsigned int OEWriteMolecule(oemolothread& ofs, OEMCMolBase& mol)
         unsigned int OEWriteMolecule(oemolothread& ofs, OEQMolBase& mol)

   .. oe:language:: python

      .. oe:api:: python

         OEWriteMolecule(ofs: oemolostream, mol: OEGraphMol) -> int
         OEWriteMolecule(ofs: oemolostream, mol: OEMol) -> int
         OEWriteMolecule(ofs: oemolostream, mol: OEQMol) -> int
         OEWriteMolecule(ofs: oemolothread, mol: OEGraphMol) -> 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 and may modify the molecule by automatically invoking
   the appropriate perception routines (aromaticity, atom typing, chirality
   perception, residue perception, etc...) as required by the selected
   output format.  This greatly simplifies the task of writing molecules
   to a stream, but may provide less control than calling the lower-level
   functions directly.

   There are a parallel set of :oe:func:`OEChem::OEWriteConstMolecule`
   functions which write identical output without modifying the given
   molecule.  These const functions will operate on a copy of the molecule
   if additional perception is required.

   All of the overloads of :oe:func:`OEChem::OEWriteMolecule` 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::OEWriteMolecule` 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::OEWriteConstMolecule` function

   .. oe:language:: c++

      * Example program :ref:`convert.cpp<section_example_oechem_convert>`

   .. oe:language:: python

      * Example program :ref:`convert.py<section_example_oechem_convert>`

   .. oe:language:: java

      * Example program :ref:`Convert.java<section_example_oechem_convert>`

   .. oe:language:: csharp

      * Example program :ref:`Convert.cs<section_example_oechem_convert>`
