conversions.convert_number_to_words
===================================

.. py:module:: conversions.convert_number_to_words


Classes
-------

.. autoapisummary::

   conversions.convert_number_to_words.NumberWords
   conversions.convert_number_to_words.NumberingSystem


Functions
---------

.. autoapisummary::

   conversions.convert_number_to_words.convert_number
   conversions.convert_number_to_words.convert_small_number


Module Contents
---------------

.. py:class:: NumberWords(*args, **kwds)

   Bases: :py:obj:`enum.Enum`


   Create a collection of name/value pairs.

   Example enumeration:

   >>> class Color(Enum):
   ...     RED = 1
   ...     BLUE = 2
   ...     GREEN = 3

   Access them by:

   - attribute access:

     >>> Color.RED
     <Color.RED: 1>

   - value lookup:

     >>> Color(1)
     <Color.RED: 1>

   - name lookup:

     >>> Color['RED']
     <Color.RED: 1>

   Enumerations can be iterated over, and know how many members they have:

   >>> len(Color)
   3

   >>> list(Color)
   [<Color.RED: 1>, <Color.BLUE: 2>, <Color.GREEN: 3>]

   Methods can be added to enumerations, and members can have their own
   attributes -- see the documentation for details.


   .. py:attribute:: ONES


   .. py:attribute:: TEENS


   .. py:attribute:: TENS


.. py:class:: NumberingSystem(*args, **kwds)

   Bases: :py:obj:`enum.Enum`


   Create a collection of name/value pairs.

   Example enumeration:

   >>> class Color(Enum):
   ...     RED = 1
   ...     BLUE = 2
   ...     GREEN = 3

   Access them by:

   - attribute access:

     >>> Color.RED
     <Color.RED: 1>

   - value lookup:

     >>> Color(1)
     <Color.RED: 1>

   - name lookup:

     >>> Color['RED']
     <Color.RED: 1>

   Enumerations can be iterated over, and know how many members they have:

   >>> len(Color)
   3

   >>> list(Color)
   [<Color.RED: 1>, <Color.BLUE: 2>, <Color.GREEN: 3>]

   Methods can be added to enumerations, and members can have their own
   attributes -- see the documentation for details.


   .. py:method:: max_value(system: str) -> int
      :classmethod:


      Gets the max value supported by the given number system.

      >>> NumberingSystem.max_value("short") == 10**18 - 1
      True
      >>> NumberingSystem.max_value("long") == 10**21 - 1
      True
      >>> NumberingSystem.max_value("indian") == 10**19 - 1
      True



   .. py:attribute:: INDIAN
      :value: ((14, 'crore crore'), (12, 'lakh crore'), (7, 'crore'), (5, 'lakh'), (3, 'thousand'), (2, 'hundred'))



   .. py:attribute:: LONG
      :value: ((15, 'billiard'), (9, 'milliard'), (6, 'million'), (3, 'thousand'), (2, 'hundred'))



   .. py:attribute:: SHORT
      :value: ((15, 'quadrillion'), (12, 'trillion'), (9, 'billion'), (6, 'million'), (3, 'thousand'), (2, 'hundred'))



.. py:function:: convert_number(num: int, system: Literal['short', 'long', 'indian'] = 'short') -> str

   Converts an integer to English words.

   :param num: The integer to be converted
   :param system: The numbering system (short, long, or Indian)

   >>> convert_number(0)
   'zero'
   >>> convert_number(1)
   'one'
   >>> convert_number(100)
   'one hundred'
   >>> convert_number(-100)
   'negative one hundred'
   >>> convert_number(123_456_789_012_345) # doctest: +NORMALIZE_WHITESPACE
   'one hundred twenty-three trillion four hundred fifty-six billion
   seven hundred eighty-nine million twelve thousand three hundred forty-five'
   >>> convert_number(123_456_789_012_345, "long") # doctest: +NORMALIZE_WHITESPACE
   'one hundred twenty-three thousand four hundred fifty-six milliard
   seven hundred eighty-nine million twelve thousand three hundred forty-five'
   >>> convert_number(12_34_56_78_90_12_345, "indian") # doctest: +NORMALIZE_WHITESPACE
   'one crore crore twenty-three lakh crore
   forty-five thousand six hundred seventy-eight crore
   ninety lakh twelve thousand three hundred forty-five'
   >>> convert_number(10**18)
   Traceback (most recent call last):
   ...
   ValueError: Input number is too large
   >>> convert_number(10**21, "long")
   Traceback (most recent call last):
   ...
   ValueError: Input number is too large
   >>> convert_number(10**19, "indian")
   Traceback (most recent call last):
   ...
   ValueError: Input number is too large


.. py:function:: convert_small_number(num: int) -> str

   Converts small, non-negative integers with irregular constructions in English (i.e.,
   numbers under 100) into words.

   >>> convert_small_number(0)
   'zero'
   >>> convert_small_number(5)
   'five'
   >>> convert_small_number(10)
   'ten'
   >>> convert_small_number(15)
   'fifteen'
   >>> convert_small_number(20)
   'twenty'
   >>> convert_small_number(25)
   'twenty-five'
   >>> convert_small_number(-1)
   Traceback (most recent call last):
   ...
   ValueError: This function only accepts non-negative integers
   >>> convert_small_number(123)
   Traceback (most recent call last):
   ...
   ValueError: This function only converts numbers less than 100