Module _gmp.gmp_error
=====================

.. module:: _gmp.gmp_error

We gently trap errors generated by the GNU MP library. When the latter
sends the :C:`SIGFPE` (*Floating Point Error*) signal following a
fatal error (division by zero, for example), the :Py:`gmp` module
captures this signal and raises an appropriate exception **without
aborting** the Python interpreter. Let's look at some examples:

.. code-block:: Python

   >>> z = mpz(-1); u = mpz()
   >>> z.sqrt()
   Traceback (most recent call last):
     File "<python-input-3>", line 1, in <module>
       z.sqrt()
       ~~~~~~^^
   _gmp.gmp_error: square root of negative (gmp_errno=4)
   >>> z // u
   Traceback (most recent call last):
     File "<python-input-4>", line 1, in <module>
       z // u
       ~~^^~~
   _gmp.gmp_error: division by zero (gmp_errno=2)
   >>> # Python interpreter still alive - no abort()

Same example using a block :py:keyword:`try` / :py:keyword:`except`:

.. code-block:: Python

   >>> z = mpz(-1); u = mpz()
   >>> try:
   ...     z.sqrt()
   ... except GMPErrSqrtOfNegative:
   ...     # Do something.
   >>> try:
   ...     z // u
   ... except GMPErrDivisionByZero:
   ...     # Do something.
   >>> # Python interpreter still alive - no abort()

.. warning:: The trick is, after capturing the :C:`SIGFPE` signal, to
             perform a non-local goto using system calls
             :C:`sigsetjmp()` and :C:`siglongjmp()`, which of course
             assumes that these are present on the operating system
             (which should be the case for any system conforming to
             the standard *POSIX.1-2008*).
	     
Exceptions generated by the GNU MP library
------------------------------------------

.. py:exception:: GMPErrUnsupportedArgument

.. py:exception:: GMPErrDivisionByZero

.. py:exception:: GMPErrSqrtOfNegative

.. py:exception:: GMPErrInvalidArgument

.. py:exception:: GMPErrMPZOverflow

.. table:: Mapping table between **_gmp.gmp_error** errors and **GMP MP** errors
   :width: 75%
   :widths: auto
   :align: left

   =================================== ======================================
   _gmp.gmp_error Error                GNU MP Error (defined in :C:`<gmp.h>`)
   =================================== ======================================
   :py:exc:`GMPErrUnsupportedArgument` :C:`GMP_ERROR_UNSUPPORTED_ARGUMENT`
   ----------------------------------- --------------------------------------
   :py:exc:`GMPErrDivisionByZero`      :C:`GMP_ERROR_DIVISION_BY_ZERO`
   ----------------------------------- --------------------------------------
   :py:exc:`GMPErrSqrtOfNegative`      :C:`GMP_ERROR_SQRT_OF_NEGATIVE`
   ----------------------------------- --------------------------------------
   :py:exc:`GMPErrInvalidArgument`     :C:`GMP_ERROR_INVALID_ARGUMENT`
   ----------------------------------- --------------------------------------
   :py:exc:`GMPErrMPZOverflow`         :C:`GMP_ERROR_MPZ_OVERFLOW`.
   =================================== ======================================