https://github.com/lapets/isqrt
Efficient pure-Python implementation of the integer square root function.
https://github.com/lapets/isqrt
arithmetic integers python python-library square-root square-root-estimate
Last synced: 6 months ago
JSON representation
Efficient pure-Python implementation of the integer square root function.
- Host: GitHub
- URL: https://github.com/lapets/isqrt
- Owner: lapets
- License: mit
- Created: 2018-01-14T03:41:05.000Z (almost 8 years ago)
- Default Branch: main
- Last Pushed: 2023-05-25T21:59:48.000Z (over 2 years ago)
- Last Synced: 2024-09-14T16:23:25.603Z (over 1 year ago)
- Topics: arithmetic, integers, python, python-library, square-root, square-root-estimate
- Language: Python
- Homepage: http://pypi.org/project/isqrt
- Size: 60.5 KB
- Stars: 2
- Watchers: 2
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.rst
- License: LICENSE
Awesome Lists containing this project
README
=====
isqrt
=====
Efficient pure-Python implementation of the integer square root function.
|pypi| |actions| |coveralls|
.. |pypi| image:: https://badge.fury.io/py/isqrt.svg
:target: https://badge.fury.io/py/isqrt
:alt: PyPI version and link.
.. |actions| image:: https://github.com/lapets/isqrt/workflows/lint-test-cover/badge.svg
:target: https://github.com/lapets/isqrt/actions/workflows/lint-test-cover.yml
:alt: GitHub Actions status.
.. |coveralls| image:: https://coveralls.io/repos/github/lapets/isqrt/badge.svg?branch=main
:target: https://coveralls.io/github/lapets/isqrt?branch=main
:alt: Coveralls test coverage summary.
Purpose
-------
Given an arbitrarily large non-negative integer ``n``, the `integer square root `__ function finds the largest integer ``r`` such that ``r**2 <= n`` and ``(r + 1)**2 > n``.
.. |math_isqrt| replace:: ``math.isqrt``
.. _math_isqrt: https://docs.python.org/3/library/math.html#math.isqrt
.. |math_sqrt| replace:: ``math.sqrt``
.. _math_sqrt: https://docs.python.org/3/library/math.html#math.sqrt
**The built-in** |math_isqrt|_ **function was introduced in Python 3.8 and should normally be used instead of the function defined in this library.** To provide the best performance possible while retaining backwards-compatible behavior for this library, the implementation in this library invokes |math_isqrt|_ when it is available. If |math_isqrt|_ is not available, this library attempts to use |math_sqrt|_ and then (if |math_sqrt|_ does not produce the correct result or the input is outside the range supported by |math_sqrt|_) defaults to a pure-Python implementation in which the number of executed Python arithmetic operations is linear in the bit length of the input integer.
Installation and Usage
----------------------
This library is available as a `package on PyPI `__:
.. code-block:: bash
python -m pip install isqrt
The library can be imported in the usual way:
.. code-block:: python
from isqrt import isqrt
Examples
^^^^^^^^
The exported function ``isqrt`` provides a pure-Python implementation of the `integer square root `__ algorithm:
.. code-block:: python
>>> isqrt(4)
2
>>> isqrt(16)
4
>>> list(map(isqrt, range(16, 26)))
[4, 4, 4, 4, 4, 4, 4, 4, 4, 5]
>>> isqrt(2**30000) == 2**15000
True
Development
-----------
All installation and development dependencies are fully specified in ``pyproject.toml``. The ``project.optional-dependencies`` object is used to `specify optional requirements `__ for various development tasks. This makes it possible to specify additional options (such as ``test``, ``lint``, and so on) when performing installation using `pip `__:
.. code-block:: bash
python -m pip install .[test,lint]
Testing and Conventions
^^^^^^^^^^^^^^^^^^^^^^^
All unit tests are executed and their coverage is measured when using `pytest `__ (see the ``pyproject.toml`` file for configuration details):
.. code-block:: bash
python -m pip install .[test]
python -m pytest
Alternatively, all unit tests are included in the module itself and can be executed using `doctest `__:
.. code-block:: bash
python src/isqrt/isqrt.py -v
Style conventions are enforced using `Pylint `__:
.. code-block:: bash
python -m pip install .[lint]
python -m pylint src/isqrt
Acknowledgments
^^^^^^^^^^^^^^^
The initial version of this function was `posted `__ on Stack Overflow. A `more efficient version `__ was implemented by Alexander Gosselin. The implementation in this package is adapted directly from these previous implementations.
Contributions
^^^^^^^^^^^^^
In order to contribute to the source code, open an issue or submit a pull request on the `GitHub page `__ for this library.
Versioning
^^^^^^^^^^
Beginning with version 0.10.0, the version number format for this library and the changes to the library associated with version number increments conform with `Semantic Versioning 2.0.0 `__.
Publishing
^^^^^^^^^^
This library can be published as a `package on PyPI `__ by a package maintainer. First, install the dependencies required for packaging and publishing:
.. code-block:: bash
python -m pip install .[publish]
Ensure that the correct version number appears in the ``pyproject.toml`` file. Create and push a tag for this version (replacing ``?.?.?`` with the version number):
.. code-block:: bash
git tag ?.?.?
git push origin ?.?.?
Remove any old build/distribution files. Then, package the source into a distribution archive:
.. code-block:: bash
rm -rf build dist src/*.egg-info
python -m build --sdist --wheel .
Finally, upload the package distribution archive to `PyPI `__:
.. code-block:: bash
python -m twine upload dist/*