numconv / docs / index.rst

numconv

=======

`numconv <https://tabo.pe/projects/numconv/>`_ is a library that converts

strings to numbers and numbers to strings using default or user supplied

encoding alphabets, written by `Gustavo Picón <https://tabo.pe>`_ and

licensed under the Apache License 2.0.

Installation

------------

``numconv`` has been tested in Python 2.4, 2.5, 2.6, 2.7, 3.0 and 3.1. Other

versions may work but are not supported.

You have several ways to install ``numconv``. If you're not sure,

`just use pip <http://guide.python-distribute.org/pip.html>`_

pip (or easy_install)

~~~~~~~~~~~~~~~~~~~~~

You can install the release versions from

`numconv's PyPI page`_ using ``pip``::

  pip install numconv

or if for some reason you can't use ``pip``, you can try ``easy_install``::

  easy_install --always-unzip numconv

setup.py

~~~~~~~~

Download a release from the `numconv download page`_ and unpack it, then

run::

   python setup.py install

API

---

.. module:: numconv

.. autoclass:: NumConv

   .. automethod:: int2str

      **Examples** (taken from :file:`tests.py`):

        3735928559 to hexadecimal::

            >> NumConv(16).int2str(3735928559)

            'DEADBEEF'

        19284 to binary::

            >> NumConv(2).int2str(19284)

            '100101101010100'

        37 to base 4 using a custom dictionary::

            >> NumConv(4, 'rofl').int2str(37)

            'foo'

        Very large number to :data:`~numconv.BASE85`::

            >> NumConv(85).int2str(2693233728041137)

            '~123AFz@'

   .. automethod:: str2int

      **Examples** (taken from :file:`tests.py`):

        Hexadecimal 'DEADBEEF' to integer::

           >> NumConv(16).str2int('DEADBEEF')

           3735928559

        Binary '100101101010100' to integer::

            >> NumConv(2).str2int('100101101010100')

            19284

        Base 4 with custom encoding 'foo' to integer::

            >> NumConv(4, 'rofl').str2int('foo')

            37

        :data:`~numconv.BASE85` '~123AFz@' to integer::

            >> NumConv(85).str2int('~123AFz@')

            2693233728041137

.. data:: BASE85

   Alphabet defined in section 4 of :rfc:`1924`. Supposed to be a joke

   (it is an April's fools RFC after all), but is quite useful because

   it can be used as a base for the most common numeric conversions.

.. data:: BASE16

          BASE32

          BASE32HEX

          BASE64

          BASE64URL

   Alphabets defined in :rfc:`4648`. Not really for common numeric

   conversion use.

.. data:: BASE62

   Useful for URL shorteners.

.. autofunction:: int2str

.. autofunction:: str2int

Indices and tables

==================

* :ref:`genindex`

* :ref:`modindex`

* :ref:`search`

.. _`numconv's PyPI page`:

   http://pypi.python.org/pypi/numconv

.. _`numconv download page`:

   http://code.tabo.pe/numconv/downloads/