.. oe:namespace:: OEChem

.. meta::
   :keywords: oemolistream, molistream


.. _OEChem_oemolistream:

.. oe:class:: oemolistream

   .. oe:api::

      class oemolistream : public oemolstreambase


   The :ref:`oemolistream <OEChem_oemolistream>` class provides a stream-like
   abstraction for reading molecules from files, strings or standard
   input.
   The :ref:`oemolistream <OEChem_oemolistream>` maintains the format and flavor
   of molecular reading for the stream.
   It also manages the conversion between multi-conformer molecules
   and single conformer molecules in cases where the molecule read
   into is not compatible with the file format (in the sense of a
   multi-conformer file format being read into a single-conformer
   molecule, or a single-conformer file format being read into a
   multi-conformer molecule).
   The :ref:`oemolistream <OEChem_oemolistream>` is capable of
   uncompressing gzip files while reading.

   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::

            oemolistream()

      .. oe:language:: python

         .. oe:api:: python

            oemolistream() -> oemolistream

      Default constructor.
      Creates a new :ref:`oemolistream <OEChem_oemolistream>` object
      that is connected to the standard input.

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

         .. oe:api::

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

      .. oe:language:: python

         .. oe:api:: python

            oemolistream(arg2: str) -> oemolistream
            oemolistream(fn: str) -> oemolistream

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

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

         .. oe:api::

            explicit oemolistream(OEPlatform::oeistream *, bool owned = true)

      .. oe:language:: python

         .. oe:api:: python

            oemolistream(arg2: oeistream, owned: bool = True) -> oemolistream

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

      .. warning::

         Only in C++ can an :ref:`oemolistream <OEChem_oemolistream>` object own an existing
         :ref:`oeistream <OEPlatform_oeistream>` object.

      .. oe:language:: python

         .. admonition:: Usage in Python

            .. code-block:: console

               i = oechem.oeistream()
               owned = True
               ifs = oechem.oemolistream(i, not owned)

      .. seealso::

         To associate a file or a stream with an
         :ref:`oemolistream <OEChem_oemolistream>` 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::oeistream &
      :language: c++

      .. oe:api::

         operator OEPlatform::oeistream &() const

   .. oe:method:: GetConfTest

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

         .. oe:api::

            const OEConfTestBase & GetConfTest() const

      .. oe:language:: python

         .. oe:api:: python

            GetConfTest() -> OEConfTestBase

   .. oe:language:: python

      .. oe:method:: GetOEMols

         .. oe:api::

            GetOEMols() -> <generator of OEMol objects>

         Returns a generator over all the molecules in the
         file or stream. Each molecule will be an
         :ref:`OEMol <OEChem_OEMol>` object. These are references to the
         molecules in the file or stream and so calling this method
         does not create copies of the molecules.

   .. oe:language:: python

   .. oe:method:: GetOEGraphMols

       .. oe:api::

          GetOEGraphMols() -> <generator of OEGraphMol objects>

       Returns a generator over all the  molecules in the
       input stream in the current order. Each molecule will be
       an :ref:`OEGraphMol <OEChem_OEGraphMol>` object. If opened on a
       multi-conformer :file:`.oeb` file, only the first conformer
       will be returned for each molecule record.

       .. note::

          Unlike ``OEChem::OEMolDatabase::GetOEGraphMols``, a reference to
          each molecule will be used for each iteration to avoid unnecessary
          copying of molecules.

   .. oe:method:: GetMCMolBases

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

         .. oe:api::

            OESystem::OEIterBase<OEChem::OEMCMolBase>* GetMCMolBases(bool single = false)

      .. oe:language:: python

         .. oe:api:: python

            GetMCMolBases(single: bool = False) -> Iterable[OEMol]

   .. oe:method:: GetMolBases

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

         .. oe:api::

            OESystem::OEIterBase<OEChem::OEMolBase>* GetMolBases()

      .. oe:language:: python

         .. oe:api:: python

            GetMolBases() -> Iterable[Union[OEGraphMol, OEMol, OEQMol]]

   .. oe:method: GetNextMol -- INTERNAL API TO HANDLE MULTI-CONFORMER MOLECULES

      .. oe:api::

         OEMolBase *GetNextMol()


   .. oe:method:: GetReadFailureCt

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

         .. oe:api::

            unsigned GetReadFailureCt() const

      .. oe:language:: python

         .. oe:api:: python

            GetReadFailureCt() -> int

   .. oe:method: HasNextMol -- INTERNAL API TO HANDKE MULTI-CONFORMER MOLECULES

      .. oe:api::

         bool HasNextMol() const

   .. oe:method:: IncrementReadFailureCt

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

         .. oe:api::

            void IncrementReadFailureCt()

      .. oe:language:: python

         .. oe:api:: python

            IncrementReadFailureCt() -> None

   .. oe:method: PeekNextMol -- INTERNAL API TO HANDKE MULTI-CONFORMER MOLECULES

      .. oe:api::

         OEMolBase *PeekNextMol()

   .. oe:method: PushNextMol -- INTERNAL API TO HANDKE MULTI-CONFORMER MOLECULES

      .. oe:api::

         void PushNextMol(OEMolBase *mol, oefpos_t pos = 0)

   .. oe:method:: ResetReadFailureCt

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

         .. oe:api::

            void ResetReadFailureCt()

      .. oe:language:: python

         .. oe:api:: python

            ResetReadFailureCt() -> None

   .. oe:method:: SetConfTest

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

         .. oe:api::

            bool SetConfTest(const OEConfTestBase &)

      .. oe:language:: python

         .. oe:api:: python

            SetConfTest(arg2: OEConfTestBase) -> bool

      Sets the functor class which is used to compare incoming graphs
      to determine whether they should be placed as conformers of a
      multi-conformer molecule or be returned individually as single
      molecules.
      The default conformer test never places separate graphs into a
      multi-conformer molecule (:ref:`OEDefaultConfTest <OEChem_OEDefaultConfTest>`).

      .. seealso::

         * :ref:`OEAbsCanonicalConfTest <OEChem_OEAbsCanonicalConfTest>`
         * :ref:`OEAbsoluteConfTest <OEChem_OEAbsoluteConfTest>`
         * :ref:`OEConfTestBase <OEChem_OEConfTestBase>`
         * :ref:`OEDefaultConfTest <OEChem_OEDefaultConfTest>`
         * :ref:`OEIsomericConfTest <OEChem_OEIsomericConfTest>`

   .. 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:`oemolistream <OEChem_oemolistream>` object.
      The set of valid formats are defined in the
      :ref:`the OEFormat namespace <OEChem_OEFormat>`.
      The set of valid bitmasks flavors are defined in the
      :oe:constns:`OEChem::OEIFlavor` 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:`oemolistream <OEChem_oemolistream>` constructors
      call 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:`oemolistream <OEChem_oemolistream>` object.
      The set of valid formats are defined in the
      :ref:`the OEFormat namespace <OEChem_OEFormat>`.
      By default, when reading from standard input, 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:: SetTracer

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

         .. oe:api::

            bool SetTracer(OESystem::OETracerBase* tracer, bool owntracer)

      .. oe:language:: python

         .. oe:api:: python

            SetTracer(tracer: OETracerBase, owntracer: bool) -> bool

      Registers the tracer, ``tracer``, to report the current progress
      of the :ref:`oemolistream <OEChem_oemolistream>` object on reading molecules.
      The second optional argument is used to indicate whether the
      :ref:`oemolistream <OEChem_oemolistream>` now owns the given
      :ref:`OETracerBase <OESystem_OETracerBase>` object and is therefore responsible for
      closing and destroying it when it itself is closed and/or
      destroyed.

      .. warning::

         Only in C++ can an :ref:`oemolistream <OEChem_oemolistream>` object own an existing
         :ref:`OETracerBase <OESystem_OETracerBase>` object.

      .. seealso::

         * :ref:`OETracerBase <OESystem_OETracerBase>`

   .. oe:method:: Setgz

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

         .. oe:api::

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

      .. oe:language:: python

         .. oe:api:: python

            Setgz(gz: bool, sptr: oeistream = None, owned: bool = False) -> bool

      Specifies that the contents of the
      :ref:`oemolistream <OEChem_oemolistream>` object are to be treated as compressed
      by GNU gzip compressed.  The decompression takes place on-the-fly.
      Usually the 'gz' property of a :ref:`oemolistream <OEChem_oemolistream>`
      object is determined implicitly from the file extension used to
      open the stream for reading.
      The current 'gz' property of the :ref:`oemolistream <OEChem_oemolistream>`
      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:`oemolistream <OEChem_oemolistream>` object.
      This method may be safely called multiple times.
      However :oe:meth:`OEChem::oemolistream::close` method is called
      from within the :ref:`oemolistream <OEChem_oemolistream>` destructor and
      therefore it is not necessary to call this explicitly under most
      circumstances.

   .. oe:method:: eof

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

         .. oe:api::

            bool eof() const

      .. oe:language:: python

         .. oe:api:: python

            eof() -> bool

   .. oe:method:: getbyte

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

         .. oe:api::

            int getbyte()

      .. oe:language:: python

         .. oe:api:: python

            getbyte() -> int

   .. oe:method:: getline

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

         .. oe:api::

            bool getline(char* buffer, oesize_t max)

      .. oe:language:: python

         .. oe:api:: python

            getline(buffer: str, max: oesize_t) -> bool

   .. oe:language:: c++ python

      .. oe:method:: openstring

         .. oe:api:: c++ python

            bool openstring(const std::string& str)
            bool openstring(const unsigned char* buffer, oesize_t len)

         Allows the :ref:`oemolistream <OEChem_oemolistream>` to read from a buffer in
         memory, instead of from a file or standard input.

         Internally, the :oe:meth:`OEChem::oemolistream::openstring`
         method make a copy of the specified file contents, allowing the
         :ref:`oemolistream <OEChem_oemolistream>` to continue to function
         independently of whether the original buffer is later modified
         or deallocated.

         .. note::
            Prior to calling :oe:meth:`OEChem::oemolistream::openstring` it
            is necessary to specify the format and whether or not the format is
            compressed with gzip.  These can be set with the
            :oe:meth:`OEChem::oemolistream::SetFormat` and
            :oe:meth:`OEChem::oemolistream::Setgz` methods respectively.

   .. oe:language:: java

      .. oe:method:: openByteArray

         .. oe:api:: java

            boolean openByteArray(byte[] byteArray)
            boolean openByteArray(char* byteArray, unsigned int len)

         Allows the :ref:`oemolistream <OEChem_oemolistream>` to read from a buffer in
         memory, instead of from a file or standard input.

         Internally, the :oe:meth:`OEChem::oemolistream::openByteArray`
         method make a copy of the specified file contents, allowing the
         :ref:`oemolistream <OEChem_oemolistream>` to continue to function
         independently of whether the original buffer is later modified
         or deallocated.

         .. note::
            Prior to calling :oe:meth:`OEChem::oemolistream::openByteArray` it
            is necessary to specify the format and whether or not the format is
            compressed with gzip.  These can be set with the
            :oe:meth:`OEChem::oemolistream::SetFormat` and
            :oe:meth:`OEChem::oemolistream::Setgz` methods respectively.

   .. oe:language:: csharp

      .. oe:method:: OpenByteArray

         .. oe:api:: csharp

            boolean OpenByteArray(byte[] buffer)
            boolean OpenByteArray(byte[] buffer, uint len)

         Allows the :ref:`oemolistream <OEChem_oemolistream>` to read from a buffer in
         memory, instead of from a file or standard input.

         Internally, the :oe:meth:`OEChem::oemolistream::OpenByteArray`
         method make a copy of the specified file contents, allowing the
         :ref:`oemolistream <OEChem_oemolistream>` to continue to function
         independently of whether the original buffer is later modified
         or deallocated.

         .. note::
            Prior to calling :oe:meth:`OEChem::oemolistream::OpenByteArray` it
            is necessary to specify the format and whether or not the format is
            compressed with gzip.  These can be set with the
            :oe:meth:`OEChem::oemolistream::SetFormat` and
            :oe:meth:`OEChem::oemolistream::Setgz` methods respectively.

   .. oe:method:: peekbyte

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

         .. oe:api::

            int peekbyte()

      .. oe:language:: python

         .. oe:api:: python

            peekbyte() -> int

   .. oe:method:: read

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

         .. oe:api::

            bool read(unsigned char* buffer, oesize_t len)

      .. oe:language:: python

         .. oe:api:: python

            read(buffer: str, len: oesize_t) -> bool

   .. oe:method:: rewind

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

         .. oe:api::

            void rewind()

      .. oe:language:: python

         .. oe:api:: python

            rewind() -> None

   .. oe:method:: seek

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

         .. oe:api::

            void seek(oefpos_t pos)

      .. oe:language:: python

         .. oe:api:: python

            seek(pos: oefpos_t) -> None

      Moves the position of the next valid read to the position indicated.
      This function takes account of gzip streams and molecule caching.

   .. oe:method:: size

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

         .. oe:api::

            oefpos_t size()

      .. oe:language:: python

         .. oe:api:: python

            size() -> oefpos_t

      Returns the size of the input stream if applicable to the current stream.
      The return type is a portable file-system pointer type.

   .. oe:method:: skip

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

         .. oe:api::

            bool skip(oefpos_t len)

      .. oe:language:: python

         .. oe:api:: python

            skip(len: oefpos_t) -> bool

   .. oe:method:: skipbyte

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

         .. oe:api::

            bool skipbyte()

      .. oe:language:: python

         .. oe:api:: python

            skipbyte() -> bool

   .. oe:method:: skipline

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

         .. oe:api::

            bool skipline()

      .. oe:language:: python

         .. oe:api:: python

            skipline() -> bool

   .. oe:method:: tell

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

         .. oe:api::

            oefpos_t tell()

      .. oe:language:: python

         .. oe:api:: python

            tell() -> oefpos_t

      Returns the current position of the next read.
      This function accounts for molecular caching.

      .. note::

         If you are reading an :file:`.oeb` file that was written as
         multi-conformer molecules and is being read with single conformer
         molecules, all of the conformers are read into cache at once,
         and the pointer will point to the beginning of a multi-conformer
         molecule rather than to a conformer inside a molecule.
