Comparers
=========

------------------
Rational Comparers
------------------

``calcpy`` provides extension of rational comparers to support multiple arguments and a parameter ``key`` to customize the comparision.

.. autofunction:: calcpy.eq
.. autofunction:: calcpy.ne
.. autofunction:: calcpy.lt
.. autofunction:: calcpy.le
.. autofunction:: calcpy.ge
.. autofunction:: calcpy.gt

-----------------------
Convert among Comparers
-----------------------

Python has three types of comparers:

- **Rational Comparers**: ``eq()``, ``ne()``, ``lt()``, ``le()``, ``ge()``, ``gt()``. They are provided in the built-in module ``operator`` and are extended in ``calcpy``.

- **Callable function**: Many built-in functions (such as ``sorted()``, ``min()``, ``max()``), as well as many calcpy functions, has a parameter ``key`` to specify a callable function, and the return values of this function can be used to compare.

- **Three-way ``cmp`` functions**: ``cmp()``. It returns 1 when the first argument is greater than the second argument, -1 when the first argument is less than the second argument, and 0 when the two arguments are equal. It is the old style of comparison in early version of Python 2.

``calcpy`` provides APIs to convert among these three types of comparers.

.. autofunction:: calcpy.eq_to_key
.. autofunction:: calcpy.ne_to_key
.. autofunction:: calcpy.lt_to_key
.. autofunction:: calcpy.le_to_key
.. autofunction:: calcpy.gt_to_key
.. autofunction:: calcpy.ge_to_key

.. autofunction:: calcpy.cmp_to_key

.. autofunction:: calcpy.key_to_cmp

.. autofunction:: calcpy.key_to_eq
.. autofunction:: calcpy.key_to_ne
.. autofunction:: calcpy.key_to_lt
.. autofunction:: calcpy.key_to_le
.. autofunction:: calcpy.key_to_gt
.. autofunction:: calcpy.key_to_ge
    
.. autofunction:: calcpy.eq_to_cmp
.. autofunction:: calcpy.ne_to_cmp
.. autofunction:: calcpy.lt_to_cmp
.. autofunction:: calcpy.le_to_cmp
.. autofunction:: calcpy.ge_to_cmp
.. autofunction:: calcpy.gt_to_cmp

.. autofunction:: calcpy.cmp_to_eq
.. autofunction:: calcpy.cmp_to_ne
.. autofunction:: calcpy.cmp_to_lt
.. autofunction:: calcpy.cmp_to_le
.. autofunction:: calcpy.cmp_to_gt
.. autofunction:: calcpy.cmp_to_ge

.. _matcher:

----------------------
Matcher (Experimental)
----------------------

We also provide a class ``calcpy.matcher.PandasFrameMatcher`` for comparing ``pd.DataFrame``'s. It can be passed to the parameter ``key`` for set-operation APIs in ``calcpy``.

.. autoclass:: calcpy.matcher.PandasFrameMatcher

Different ways to instantiate the ``PandasFrameMatcher`` class:

- ``calcpy.matcher.PandasFrameMatcher()``: Compare whether pandas objects as a whole. It has the same effect as ``calcpy.overall_equal()``.

- ``calcpy.matcher.PandasFrameMatcher("index")``: Compare index values of pandas objects.

- ``calcpy.matcher.PandasFrameMatcher("values")``: Compare values of pandas objects, ignoring the index values.

- ``calcpy.matcher.PandasFrameMatcher("series")``: Compare ``pd.DataFrame`` in a ``pd.Series`` way. By default, it is ``left_series.equals(right_series)``.

For ``pd.DataFrame``, it also provides a keyword parameter ``axis``. It compares each row when it is set to 0 (the default value) or ``index``, and compares each column if ``axis`` is set to 1 or ``column``.