Class AuxVarManager
===================

Constructor
-----------

.. _aux-var-manager:

AuxVarManager(free_var: int)

  The Auxiliary Variable Manager, returns fresh variables to the encoder. Therefore
  it is initialized with the first fresh variable *free_var*. Hence it is assumed
  that all variables in the original constraints are smaller than this first fresh
  variable.

  >>> from pypblib import pblib
  >>> aux_var = pblib.AuxVarManager(5)


Methods summary
---------------

+-------------------------------+-------------------------------------------------------------------------------------------+
|    Return Type                |                   Methods                                                                 |
+===============================+===========================================================================================+
|       int                     |   :ref:`get_variable() <get-variable>`                                                    |
+-------------------------------+-------------------------------------------------------------------------------------------+
|       void                    |   :ref:`free_variable(var: int) <free-variable>`                                          |
+-------------------------------+-------------------------------------------------------------------------------------------+
|       void                    |   :ref:`free_variables(vars: [int]) <free-variables>`                                     |
+-------------------------------+-------------------------------------------------------------------------------------------+
|       void                    |   :ref:`free_range_variables(var_start: int, var_end: int) <free-range-variables>`        |
+-------------------------------+-------------------------------------------------------------------------------------------+
|       int                     |   :ref:`get_biggest_returned_auxvar()() <get-biggest-returned-auxvar>`                    |
+-------------------------------+-------------------------------------------------------------------------------------------+
|       void                    |   :ref:`reset_aux_var_to(first_free_var: int) <reset-aux-var-to>`                         |
+-------------------------------+-------------------------------------------------------------------------------------------+



Methods details
---------------

.. _get-variable:

  .. method:: get_variable() -> int

  Returns the first free variable if all variables between 1 and the biggest variable are been used. Otherwise returns an unused variable between 1 and the biggest used variable. From that moment the returned variable is considered as used.

.. warning::
  As you can see in the next example, in the case of unused variables between 1 and the biggest variable, the returned variable could be random.


  >>> from pypblib import pblib
  >>> aux = pblib.AuxVarManager(10)
  >>> aux.get_variable()
  10
  >>> aux.get_variable()
  11
  >>> aux.free_variables([1, 3, 5, 7, 9])
  >>> aux.get_variable()
  9
  >>> aux.get_variable()
  1
  >>> aux.get_variable()
  3


.. _free-variable:

  .. method:: free_variable(var: int)

  Frees an used variable to refill the gap later on.

  >>> from pypblib import pblib
  >>> aux = pblib.AuxVarManager(9)
  >>> aux.free_variable(3)
  >>> aux.get_variable()
  3


.. _free-variables:

  .. method:: free_variables(vars: [int])

  Frees the used variables specified in the list.

  >>> from pypblib import pblib
  >>> aux = pblib.AuxVarManager(10)
  >>> aux.free_variables([1, 3, 5, 7, 9])
  >>> aux.get_variable()
  9
  >>> aux.get_variable()
  1


.. _free-range-variables:

  .. method:: free_range_variables(var_start: int, var_end: int)

  Frees the range of used variables between the specified start and end. Both limits are included.

  >>> from pypblib import pblib
  >>> aux = pblib.AuxVarManager(10)
  >>> aux.free_range_variables(3, 5)
  >>> aux.get_variable()
  5
  >>> aux.get_variable()
  4
  >>> aux.get_variable()
  3
  >>> aux.get_variable()
  10


.. _get-biggest-returned-auxvar:

  .. method:: get_biggest_returned_auxvar() -> int

  Returns the biggest used variable. Hence every variable between this (including)
  number and *free_var* (probably) occurs in some clause database.

  >>> from pypblib import pblib
  >>> aux_var = pblib.AuxVarManager(5)
  >>> print(aux_var.get_biggest_returned_auxvar())
  4


.. _reset-aux-var-to:

  .. method:: reset_aux_var_to(first_free_var: int)

  Resets the first free variable with the specified integer.

  >>> from pypblib import pblib
  >>> aux = pblib.AuxVarManager(10)
  >>> aux.get_biggest_returned_auxvar()
  9
  >>> aux.reset_aux_var_to(20)
  >>> aux.get_biggest_returned_auxvar()
  19