.. oe:namespace:: OEChem

.. meta::
   :keywords: oemolostream, molostream


.. _OEChem_oemolostream:

.. oe:class:: oemolostream

   .. oe:api::

      class oemolostream : public oemolstreambase

   The :ref:`oemolostream <OEChem_oemolostream>` class provides a stream-like
   abstraction for writing molecules to files, streams or standard
   output.
   The :ref:`oemolostream <OEChem_oemolostream>` maintains the format and flavor
   of the writer used when writing molecules.
   The :ref:`oemolostream <OEChem_oemolostream>` is capable of
   compressing gzip files while writing.

   The following methods are publicly inherited from :ref:`oemolstreambase <OEChem_oemolstreambase>`:

   ========================================================================== ========================================================================= =========================================================================
   :oe:meth:`ClearCSVHeader<OEChem::oemolstreambase::ClearCSVHeader>`         :oe:meth:`GetFlavor<OEChem::oemolstreambase::GetFlavor>`                  :oe:meth:`SetFormat<OEChem::oemolstreambase::SetFormat>`
   :oe:meth:`GetBinaryIOHandler<OEChem::oemolstreambase::GetBinaryIOHandler>` :oe:meth:`GetFormat<OEChem::oemolstreambase::GetFormat>`                  :oe:meth:`close<OEChem::oemolstreambase::close>`
   :oe:meth:`GetCSVHeader<OEChem::oemolstreambase::GetCSVHeader>`             :oe:meth:`Getgz<OEChem::oemolstreambase::Getgz>`                          :oe:meth:`open<OEChem::oemolstreambase::open>`
   :oe:meth:`GetFileName<OEChem::oemolstreambase::GetFileName>`               :oe:meth:`SetFlavor<OEChem::oemolstreambase::SetFlavor>`
   ========================================================================== ========================================================================= =========================================================================

   .. oe:method:: Constructors

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

         .. oe:api::

            oemolostream()

      .. oe:language:: python

         .. oe:api:: python

            oemolostream() -> oemolostream

      Creates a new :ref:`oemolostream <OEChem_oemolostream>` object
      that is connected to standard output.


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

         .. oe:api::

            explicit oemolostream(const char* fname)
            explicit oemolostream(const std::string& fname)

      .. oe:language:: python

         .. oe:api:: python

            oemolostream(name: str) -> oemolostream
            oemolostream(fn: str) -> oemolostream

      Creates a new :ref:`oemolostream <OEChem_oemolostream>` object and opens
      the file specified by the given name ('fname').

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

         .. oe:api::

            explicit oemolostream(OEPlatform::oeostream *, bool owned = true)

      .. oe:language:: python

         .. oe:api:: python

            oemolostream(arg2: oeostream, owned: bool = True) -> oemolostream

      Creates a new :ref:`oemolostream <OEChem_oemolostream>` object from the
      existing :ref:`oeostream <OEPlatform_oeostream>` object.
      The second optional argument is used to indicate whether the new
      :ref:`oemolostream <OEChem_oemolostream>` now owns the given
      :ref:`oeostream <OEPlatform_oeostream>` and is therefore responsible for
      closing and destroying it when it itself is closed and/or
      destroyed.

      .. warning::

         Only in C++ can an :ref:`oemolostream <OEChem_oemolostream>` object own an existing
         :ref:`oeostream <OEPlatform_oeostream>` object.

      .. oe:language:: python

         .. admonition:: Usage in Python

            .. code-block:: console

               i = oechem.oeostream()
               owned = True
               ofs = oechem.oemolostream(i, not owned)

      .. seealso::

         To associate a file or a stream with an
         :ref:`oemolostream <OEChem_oemolostream>` after it has been created, see the
         :oe:meth:`OEChem::oemolstreambase::open` method.

   .. oe:method:: operator bool

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

         .. oe:api::

            operator bool() const

      .. oe:language:: python

         .. oe:api:: python

            IsValid() -> bool

   .. oe:method:: operator OEPlatform::oeostream &
      :language: c++

      .. oe:api::

         operator OEPlatform::oeostream &() const

   .. oe:language:: c++ python

      .. oe:method:: GetString

         .. oe:api:: c++ python

            std::string GetString(void)

         Returns the contents of the in-memory buffer associated with the
         :ref:`oemolostream <OEChem_oemolostream>` object.
         The :ref:`oemolostream <OEChem_oemolostream>` object must previously have
         been opened for writing to an in-memory buffer using the
         :oe:meth:`OEChem::oemolostream::openstring` method.

   .. oe:language:: java

      .. oe:method:: getByteArray

         .. oe:api:: java

            byte[] getByteArray()

         Returns the contents of the in-memory buffer associated with the
         :ref:`oemolostream <OEChem_oemolostream>` object.
         The :ref:`oemolostream <OEChem_oemolostream>` object must previously have
         been opened for writing to an in-memory buffer using the
         :oe:meth:`OEChem::oemolostream::openstring` method.

   .. oe:language:: csharp

      .. oe:method:: GetByteArray

         .. oe:api:: csharp

            byte[] GetByteArray()

         Returns the contents of the in-memory buffer associated with the
         :ref:`oemolostream <OEChem_oemolostream>` object.
         The :ref:`oemolostream <OEChem_oemolostream>` object must previously have
         been opened for writing to an in-memory buffer using the
         :oe:meth:`OEChem::oemolostream::openstring` method.

   .. oe:method:: SetFlavor

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

         .. oe:api::

            bool SetFlavor(unsigned int format, unsigned int flavor)

      .. oe:language:: python

         .. oe:api:: python

            SetFlavor(format: int, flavor: int) -> bool

      Sets the file flavor for a given format associated with the
      :ref:`oemolostream <OEChem_oemolostream>` object.
      The set of valid formats are defined int the
      :ref:`the OEFormat namespace <OEChem_OEFormat>`.
      The set of valid bitmasks flavors are defined in the
      :oe:constns:`OEChem::OEOFlavor` namespace.
      The current flavor can be queried using the
      :oe:meth:`OEChem::oemolstreambase::GetFlavor` method.
      Each format has its own specific flavor which must be set
      separately.
      The :ref:`oemolostream <OEChem_oemolostream>` constructors
      calls the :oe:func:`OEChem::OESetDefaultFlavors` function
      to set the flavors for all of the formats to their default state.

   .. oe:method:: SetFormat

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

         .. oe:api::

            bool SetFormat(unsigned int format)

      .. oe:language:: python

         .. oe:api:: python

            SetFormat(format: int) -> bool

      Sets the file format associated with the
      :ref:`oemolostream <OEChem_oemolostream>` object.
      The set of valid formats are defined in the
      :ref:`the OEFormat namespace <OEChem_OEFormat>`.
      By default, when writing to standard output, the associated
      file format is :oe:const:`OEChem::OEFormat::SMI`.
      The file format property of an :ref:`oemolistream <OEChem_oemolistream>`
      may be retrieved using the
      :oe:meth:`OEChem::oemolstreambase::GetFormat` method.

      .. note::

         The file format property is also set automatically by
         :oe:meth:`OEChem::oemolstreambase::open` based upon the file
         extension of the specified filename.

   .. oe:method:: SetString

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

         .. oe:api::

            void SetString(const char* c)
            void SetString(const unsigned char* c, oesize_t size)

      .. oe:language:: python

         .. oe:api:: python

            SetString(c: str) -> None
            SetString(c: str, size: oesize_t) -> None

      Allows the :ref:`oemolostream <OEChem_oemolostream>` to be opened for
      writing to a buffer and specify the initial contents of the
      buffer.

      .. oe:language:: c++ python

         The contents of in-memory buffer when writing to a string may be
         obtained using the :oe:meth:`OEChem::oemolostream::GetString`
         method.

      .. oe:language:: java

         The contents of in-memory buffer when writing to a string may be
         obtained using the :oe:meth:`OEChem::oemolostream::getByteArray`
         method.

      .. oe:language:: csharp

         The contents of in-memory buffer when writing to a string may be
         obtained using the :oe:meth:`OEChem::oemolostream::GetByteArray`
         method.

   .. oe:method:: Setgz

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

         .. oe:api::

            bool Setgz(bool gz, OEPlatform::oeostream* sptr = 0, bool = false)

      .. oe:language:: python

         .. oe:api:: python

            Setgz(gz: bool, sptr: oeostream = None, arg4: bool = False) -> bool

      Specifies that the contents of the
      :ref:`oemolostream <OEChem_oemolostream>` object should be GNU gzip
      compressed
      The compression takes place on-the-fly.
      Usually the 'gz' property of a :ref:`oemolostream <OEChem_oemolostream>`
      object is determined implicitly from the file extension used to
      open the stream for writing.
      The current 'gz' property of the :ref:`oemolostream <OEChem_oemolostream>`
      object can be retrieved using the
      :oe:meth:`OEChem::oemolstreambase::Getgz` method.

   .. oe:method:: close

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

         .. oe:api::

            void close()

      .. oe:language:: python

         .. oe:api:: python

            close() -> None

      Closes the :ref:`oemolostream <OEChem_oemolostream>` object.
      This method may be safely called multiple times.

   .. oe:method:: flush

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

         .. oe:api::

            oemolostream& flush()

      .. oe:language:: python

         .. oe:api:: python

            flush() -> oemolostream

   .. oe:method:: openstring

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

         .. oe:api::

            bool openstring()
            bool openstring(bool gzip)

      .. oe:language:: python

         .. oe:api:: python

            openstring() -> bool
            openstring(gzip: bool) -> bool

      Allows the :ref:`oemolostream <OEChem_oemolostream>` to write to a buffer in
      memory, instead of to a file or standard output.

      .. oe:language:: c++ python

         Calling :oe:meth:`OEChem::oemolostream::openstring` instructs the
         :ref:`oemolostream <OEChem_oemolostream>` object to start accumulating
         output in a buffer, which can later be retrieved by calling the
         :oe:meth:`OEChem::oemolostream::GetString` method.

      .. oe:language:: java

         Calling :oe:meth:`OEChem::oemolostream::openstring` instructs the
         :ref:`oemolostream <OEChem_oemolostream>` object to start accumulating
         output in a buffer, which can later be retrieved by calling the
         :oe:meth:`OEChem::oemolostream::getByteArray` method.

      .. oe:language:: csharp

         Calling :oe:meth:`OEChem::oemolostream::openstring` instructs the
         :ref:`oemolostream <OEChem_oemolostream>` object to start accumulating
         output in a buffer, which can later be retrieved by calling the
         :oe:meth:`OEChem::oemolostream::GetByteArray` method.

      The form that accepts a 'gzip' argument can be used to instruct
      the :ref:`oemolostream <OEChem_oemolostream>` object to compress the contents
      of the in-memory buffer.

   .. oe:method:: put

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

         .. oe:api::

            oemolostream& put(char c)

      .. oe:language:: python

         .. oe:api:: python

            put(c: str) -> oemolostream

   .. oe:method:: tell

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

         .. oe:api::

            oefpos_t tell()

      .. oe:language:: python

         .. oe:api:: python

            tell() -> oefpos_t

   .. oe:method:: write

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

         .. oe:api::

            oemolostream& write(const char* str, oesize_t size)

      .. oe:language:: python

         .. oe:api:: python

            write(str: str, size: oesize_t) -> oemolostream

