gh-81313: Add the imath module

Author: serhiy-storchaka

Doc/library/imath.rst

@@ -0,0 +1,99 @@
+:mod:`imath` --- Mathematical functions for integer numbers
+===========================================================
+
+.. module:: imath
+   :synopsis: Mathematical functions for integer numbers.
+
+.. versionadded:: next
+
+--------------
+
+This module provides access to the mathematical functions for integer arguments.
+These functions accept integers and objects that implement the
+:meth:`__index__` method which is used to convert the object to an integer
+number.  They cannot be used with floating-point numbers or complex
+numbers.
+
+The following functions are provided by this module.  All return values are
+integers.
+
+
+.. function:: comb(n, k)
+
+   Return the number of ways to choose *k* items from *n* items without repetition
+   and without order.
+
+   Evaluates to ``n! / (k! * (n - k)!)`` when ``k <= n`` and evaluates
+   to zero when ``k > n``.
+
+   Also called the binomial coefficient because it is equivalent
+   to the coefficient of k-th term in polynomial expansion of
+   ``(1 + x)ⁿ``.
+
+   Raises :exc:`TypeError` if either of the arguments are not integers.
+   Raises :exc:`ValueError` if either of the arguments are negative.
+
+
+.. function:: factorial(n)
+
+   Return *n* factorial as an integer.  Raises :exc:`ValueError` if *n* is not integral or
+   is negative.
+
+
+.. function:: gcd(a, b)
+
+   Return the greatest common divisor of the specified integer arguments.
+   If any of the arguments is nonzero, then the returned value is the largest
+   positive integer that is a divisor of all arguments.  If all arguments
+   are zero, then the returned value is ``0``.  ``gcd()`` without arguments
+   returns ``0``.
+
+
+.. function:: ilog2(n)
+
+   Return the integer base 2 logarithm of the positive integer *n*. This is the
+   floor of the exact base 2 logarithm root of *n*, or equivalently the
+   greatest integer *k* such that
+   2\ :sup:`k` |nbsp| ≤ |nbsp| *n* |nbsp| < |nbsp| 2\ :sup:`k+1`.
+
+   It is equivalent to ``n.bit_length() - 1`` for positive *n*.
+
+
+.. function:: isqrt(n)
+
+   Return the integer square root of the nonnegative integer *n*. This is the
+   floor of the exact square root of *n*, or equivalently the greatest integer
+   *a* such that *a*\ ² |nbsp| ≤ |nbsp| *n*.
+
+   For some applications, it may be more convenient to have the least integer
+   *a* such that *n* |nbsp| ≤ |nbsp| *a*\ ², or in other words the ceiling of
+   the exact square root of *n*. For positive *n*, this can be computed using
+   ``a = 1 + isqrt(n - 1)``.
+
+
+.. function:: lcm(*integers)
+
+   Return the least common multiple of the specified integer arguments.
+   If all arguments are nonzero, then the returned value is the smallest
+   positive integer that is a multiple of all arguments.  If any of the arguments
+   is zero, then the returned value is ``0``.  ``lcm()`` without arguments
+   returns ``1``.
+
+
+.. function:: perm(n, k=None)
+
+   Return the number of ways to choose *k* items from *n* items
+   without repetition and with order.
+
+   Evaluates to ``n! / (n - k)!`` when ``k <= n`` and evaluates
+   to zero when ``k > n``.
+
+   If *k* is not specified or is ``None``, then *k* defaults to *n*
+   and the function returns ``n!``.
+
+   Raises :exc:`TypeError` if either of the arguments are not integers.
+   Raises :exc:`ValueError` if either of the arguments are negative.
+
+
+.. |nbsp| unicode:: 0xA0
+   :trim:

Doc/library/math.rst

@@ -124,40 +124,27 @@ noted otherwise, all return values are floats.
 Number-theoretic functions
 --------------------------
 
-.. function:: comb(n, k)
-
-   Return the number of ways to choose *k* items from *n* items without repetition
-   and without order.
-
-   Evaluates to ``n! / (k! * (n - k)!)`` when ``k <= n`` and evaluates
-   to zero when ``k > n``.
+These functions are aliases of corresponding functions in the
+:mod:`imath` module.
 
-   Also called the binomial coefficient because it is equivalent
-   to the coefficient of k-th term in polynomial expansion of
-   ``(1 + x)ⁿ``.
+.. function:: comb(n, k)
 
-   Raises :exc:`TypeError` if either of the arguments are not integers.
-   Raises :exc:`ValueError` if either of the arguments are negative.
+   An alias of :func:`imath.comb`.
 
    .. versionadded:: 3.8
 
 
 .. function:: factorial(n)
 
-   Return *n* factorial as an integer.  Raises :exc:`ValueError` if *n* is not integral or
-   is negative.
+   An alias of :func:`imath.factorial`.
 
    .. versionchanged:: 3.10
       Floats with integral values (like ``5.0``) are no longer accepted.
 
 
 .. function:: gcd(*integers)
 
-   Return the greatest common divisor of the specified integer arguments.
-   If any of the arguments is nonzero, then the returned value is the largest
-   positive integer that is a divisor of all arguments.  If all arguments
-   are zero, then the returned value is ``0``.  ``gcd()`` without arguments
-   returns ``0``.
+   An alias of :func:`imath.gcd`.
 
    .. versionadded:: 3.5
 
@@ -168,42 +155,21 @@ Number-theoretic functions
 
 .. function:: isqrt(n)
 
-   Return the integer square root of the nonnegative integer *n*. This is the
-   floor of the exact square root of *n*, or equivalently the greatest integer
-   *a* such that *a*\ ² |nbsp| ≤ |nbsp| *n*.
-
-   For some applications, it may be more convenient to have the least integer
-   *a* such that *n* |nbsp| ≤ |nbsp| *a*\ ², or in other words the ceiling of
-   the exact square root of *n*. For positive *n*, this can be computed using
-   ``a = 1 + isqrt(n - 1)``.
+   An alias of :func:`imath.isqrt`.
 
    .. versionadded:: 3.8
 
 
 .. function:: lcm(*integers)
 
-   Return the least common multiple of the specified integer arguments.
-   If all arguments are nonzero, then the returned value is the smallest
-   positive integer that is a multiple of all arguments.  If any of the arguments
-   is zero, then the returned value is ``0``.  ``lcm()`` without arguments
-   returns ``1``.
+   An alias of :func:`imath.lcm`.
 
    .. versionadded:: 3.9
 
 
 .. function:: perm(n, k=None)
 
-   Return the number of ways to choose *k* items from *n* items
-   without repetition and with order.
-
-   Evaluates to ``n! / (n - k)!`` when ``k <= n`` and evaluates
-   to zero when ``k > n``.
-
-   If *k* is not specified or is ``None``, then *k* defaults to *n*
-   and the function returns ``n!``.
-
-   Raises :exc:`TypeError` if either of the arguments are not integers.
-   Raises :exc:`ValueError` if either of the arguments are negative.
+   An alias of :func:`imath.perm`.
 
    .. versionadded:: 3.8
 
@@ -838,6 +804,3 @@ Constants
 
    Module :mod:`cmath`
       Complex number versions of many of these functions.
-
-.. |nbsp| unicode:: 0xA0
-   :trim:

Doc/whatsnew/3.15.rst

@@ -83,7 +83,11 @@ Other language changes
 New modules
 ===========
 
-* None yet.
+imath
+-----
+
+This module provides access to the mathematical functions for integer arguments.
+(Contributed by Serhiy Storchaka in :gh:`81313`.)
 
 
 Improved modules