.. include:: ../../toolkit-substitutions

.. oe:namespace:: OEChem

..  _OEChem_OEScreen:

.. oe:function:: OEScreen

   .. attention::

      |TWOLANGUAGE|

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

      .. oe:api::

         bool OEScreen(const OESubSearchScreen& query,
                       const OESubSearchScreen& target)

   .. oe:language:: python

      .. oe:api:: python

         OEScreen(query: OESubSearchScreen, target: OESubSearchScreen) -> bool

   Returns whether an :ref:`OESubSearchScreen <OEChem_OESubSearchScreen>` object generated
   for a target molecule can be matched to the :ref:`OESubSearchScreen <OEChem_OESubSearchScreen>`
   object generated for a query molecule.

   .. oe:language:: c++ python

     The code snippet below shows how to generate a screens for a query and a target molecule
     and how to compare them using :oe:func:`OEChem::OEScreen`.

     * :oe:func:`OEChem::OEScreen` will throw a warning and returns ``false`` if the type of the
       screens are different.
     * If the query screen has any bit 'on' that is 'off' in the target molecule (i.e. query
       has some feature that is not present in the target molecule), the :oe:func:`OEChem::OEScreen`
       function returns ``false`` and the target molecule can be eliminated
       from further consideration since it can not be successfully matched to the query.
     * If all the bits that are 'on' in the query screen are also 'on' in the target screen,
       :oe:func:`OEChem::OEScreen` returns ``true`` and match has to
       be validated by performing atom-by-atom substructure match
       (see also :ref:`OESubSearch <OEChem_OESubSearch>`).

   **Example**

   .. oe:source:: SubSearchScreen.cpp
      :language: c++
      :noindent:
      :frag:     SNIPPET

   .. oe:source:: SubSearchScreen.py
      :language: python
      :noindent:
      :frag:     SNIPPET

   .. note::

      All screens provided by **OEChem TK** are rigorously tested to make sure that
      they do not eliminate any matches that would succeed when utilizing the
      more elaborate atom-by-atom substructure search algorithm.

   .. seealso::

      * :oe:func:`OEChem::OEGetSubSearchScreenType` function
      * :oe:constns:`OEChem::OESubSearchScreenType` namespace
