.. oe:namespace:: OESystem

.. meta::
   :keywords: OEDots, Dots


.. _OESystem_OEDots:

.. oe:class:: OEDots

   .. oe:api::

      class OEDots

   Provides a simple progress bar interface for command line
   applications. Dots, ``.``, characters are printed to
   :oe:const:`OEPlatform::OEPlatform::oeerr` to indicate to the user
   of the command line application that progress is indeed being made
   and the program is not hung indefinitely.

   .. seealso::

      A version of this class that is safe to used from multiple
      threads of computation: :ref:`OEThreadedDots <OESystem_OEThreadedDots>`.

   .. oe:method:: Constructors

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

         .. oe:api::

            OEDots(unsigned int bigstep, unsigned int smallstep,
                   const char * objectname = "",
                   const char * action = "processed")

      .. oe:language:: python

         .. oe:api:: python

            OEDots(bigstep: int, smallstep: int, objectname: str = "",
                   action: str = "processed") -> OEDots

      Controls how the following output gets updated::

         .......... 10000 things processed.
         .......... 20000 things processed.
         .......... 30000 things processed.
         .......... 40000 things processed.
         .......... 50000 things processed.
         .......... 60000 things processed.
         .......... 70000 things processed.
         .......... 80000 things processed.

      *bigstep*
        The number of elements before a new line is generated. The
        above example is a ``bigstep`` of ``10000``.

      *smallstep*
        The number of elements before a single new dot, ``.``, is
        printed.  The above example is a ``smallstep`` of ``1000``. Or
        10 dots per line.

      *objectname*
        A description of what is being processed. In the above
        example, this is "things".

      *action*
        A description of what is done to the 'objects'. In the above
        example, this is "processed".

   .. oe:method:: GetBigStep

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

         .. oe:api::

            unsigned int GetBigStep()

      .. oe:language:: python

         .. oe:api:: python

            GetBigStep() -> int

      Returns the ``bigstep`` size used to construct this instance.

   .. oe:method:: GetCounts

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

         .. oe:api::

            unsigned int GetCounts()

      .. oe:language:: python

         .. oe:api:: python

            GetCounts() -> int

      Returns the current number of elements counted by this instance.

   .. oe:method:: GetSmallStep

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

         .. oe:api::

            unsigned int GetSmallStep()

      .. oe:language:: python

         .. oe:api:: python

            GetSmallStep() -> int

      Returns the ``smallstep`` size used to construct this instance.

   .. oe:method:: SetBigStep

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

         .. oe:api::

            void SetBigStep(unsigned int s)

      .. oe:language:: python

         .. oe:api:: python

            SetBigStep(s: int) -> None

      Sets a new ``bigstep`` size for this instance.

   .. oe:method:: SetSmallStep

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

         .. oe:api::

            void SetSmallStep(unsigned int s)

      .. oe:language:: python

         .. oe:api:: python

            SetSmallStep(s: int) -> None

      Sets a new ``smallstep`` size for this instance.

   .. oe:method:: Total

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

         .. oe:api::

            void Total()

      .. oe:language:: python

         .. oe:api:: python

            Total() -> None

      Prints a final summary line like the following::

         Total: 80000 things processed.

      Typically only run once at the end of all processing.

   .. oe:method:: Update

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

         .. oe:api::

            void Update(unsigned int step = 1)
            void Update(const char symbol, unsigned int step = 1)

      .. oe:language:: python

         .. oe:api:: python

            Update(step: int = 1) -> None
            Update(symbol: str, step: int = 1) -> None

      Update the progress with the number of elements specified by
      ``step``. The default is ``1`` element, but any number can be
      specified. However, ``0`` is not a valid step size and will
      throw an error.  The second overload allows to specify a `symbol`
      to be displayed as progress, instead of a dot.

      .. note::

         Not thread-safe, see :ref:`OEThreadedDots <OESystem_OEThreadedDots>` if
         this method needs to be called from multiple threads.

.. seealso::

  .. oe:language:: c++

      * Example program :ref:`dots.cpp<section_example_oechem_dots>`

  .. oe:language:: python

      * Example program :ref:`dots.py<section_example_oechem_dots>`

  .. oe:language:: java

      * Example program :ref:`Dots.java<section_example_oechem_dots>`

  .. oe:language:: csharp

      * Example program :ref:`Dots.cs<section_example_oechem_dots>`
