.. include:: ../substitutions

.. oe:namespace:: OEChem

.. meta::
   :keywords: OECreateMolDatabaseIdx

.. oe:function:: OECreateMolDatabaseIdx

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

      .. oe:api::

         bool OECreateMolDatabaseIdx(const std::string& databaseFileName)
         bool OECreateMolDatabaseIdx(const std::string& databaseFileName,
                                     const std::string& indexFileName)

   .. oe:language:: python

      .. oe:api:: python

         OECreateMolDatabaseIdx(databaseFileName: str) -> bool
         OECreateMolDatabaseIdx(databaseFileName: str, indexFileName: str) -> bool

   Creates an index file parallel to the file named by
   ``databaseFileName`` to improve the performance of
   :oe:meth:`OEChem::OEMolDatabase::Open` as described by the
   :ref:`section_index_files` section. If
   :oe:meth:`OEChem::OEMolDatabase::Open` detects the presence of a
   parallel :file:`.idx` file, the file position offsets will be read
   from the :file:`.idx` file instead of having to stream the entire
   file off of disk to find the offsets during the call to
   :oe:meth:`OEChem::OEMolDatabase::Open`.

   The index file name created is based upon the
   ``databaseFileName`` passed, optionally accounting for
   :file:`.gz`. The following table demonstrates the pattern used to
   create index file names:

   =================== =====================
   Database File Name  Index File Name
   =================== =====================
   database.oeb        database.oeb.idx
   database.oeb.gz     database.oeb.idx.gz
   =================== =====================

   The overload of the function that takes an ``indexFileName`` will
   write the index to that file name instead.

   Returns ``false`` if the function fails to create the index file
   for any reason, e.g., unable to open the file specified by
   ``databaseFileName``.

   **Example**

   .. oe:source:: CreateMolDBIdx.cpp
      :language: c++
      :caption:  Creates an index file
      :refnum:   1
      :frag:     SNIPPET-CreateMolDBIdx

   .. oe:source:: CreateMolDBIdx.py
      :language: python
      :caption:  Creates an index file
      :refnum:   1
      :frag:     SNIPPET-CreateMolDBIdx

   .. oe:source:: CreateMolDBIdx.java
      :language: java
      :caption:  Creates an index file
      :refnum:   1
      :frag:     SNIPPET-CreateMolDBIdx

   .. oe:source:: CreateMolDBIdx.cs
      :language: csharp
      :caption:  Creates an index file
      :refnum:   1
      :frag:     SNIPPET-CreateMolDBIdx

   .. note::

      :file:`.idx` files can be concatenated together. Care must be
      taken to concatenate the corresponding database files together
      in the exact same order.

.. ################################################################
   #
   ################################################################

