maths.special_numbers.kaprekar_constant
=======================================

.. py:module:: maths.special_numbers.kaprekar_constant

.. autoapi-nested-parse::

   Kaprekar's Constant (6174) - also known as Kaprekar's Routine

   Kaprekar's constant is a special number discovered by Indian mathematician
   D. R. Kaprekar in 1949. It is notable for the following property:

   1. Take any four-digit number with at least two different digits (leading zeros allowed)
   2. Arrange the digits in descending order to form the largest possible number
   3. Arrange the digits in ascending order to form the smallest possible number
   4. Subtract the smaller number from the larger number
   5. Repeat the process with the result

   This process will always reach 6174 in at most 7 iterations, and once 6174 is
   reached, the process will continue to yield 6174.

   Example:
       3524 -> 5432 - 2345 = 3087
       3087 -> 8730 - 0378 = 8352
       8352 -> 8532 - 2358 = 6174
       6174 -> 7641 - 1467 = 6174 (repeats)

   Reference: https://en.wikipedia.org/wiki/6174_(number)
   OEIS: https://oeis.org/A099009



Functions
---------

.. autoapisummary::

   maths.special_numbers.kaprekar_constant.is_kaprekar_valid
   maths.special_numbers.kaprekar_constant.kaprekar_constant
   maths.special_numbers.kaprekar_constant.kaprekar_routine
   maths.special_numbers.kaprekar_constant.main


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

.. py:function:: is_kaprekar_valid(number: int) -> bool

   Check if a number is valid for Kaprekar's routine.
   A number is valid if it has at least two different digits.

   Args:
       number: A 4-digit number (0-9999)

   Returns:
       True if the number is valid for Kaprekar's routine, False otherwise

   >>> is_kaprekar_valid(3524)
   True
   >>> is_kaprekar_valid(1111)
   False
   >>> is_kaprekar_valid(1000)
   True
   >>> is_kaprekar_valid(1)
   True
   >>> is_kaprekar_valid(6174)
   True


.. py:function:: kaprekar_constant(number: int, max_iterations: int = 7) -> tuple[int, list[int]]

   Apply Kaprekar's routine until reaching the constant 6174 or max iterations.

   Args:
       number: A 4-digit number (0-9999)
       max_iterations: Maximum number of iterations to perform (default: 7)

   Returns:
       A tuple containing:
       - The number of iterations taken to reach 6174 (or -1 if not reached)
       - A list of all intermediate results

   >>> kaprekar_constant(3524)
   (3, [3524, 3087, 8352, 6174])
   >>> kaprekar_constant(6174)
   (0, [6174])
   >>> kaprekar_constant(1234)
   (3, [1234, 3087, 8352, 6174])
   >>> kaprekar_constant(1111)
   (-1, [1111, 0])
   >>> kaprekar_constant(495)
   (4, [495, 9081, 9621, 8352, 6174])
   >>> kaprekar_constant(9998)
   (5, [9998, 999, 8991, 8082, 8532, 6174])


.. py:function:: kaprekar_routine(number: int) -> int

   Perform one iteration of Kaprekar's routine.

   Args:
       number: A 4-digit number (0-9999)

   Returns:
       The result of one Kaprekar iteration

   >>> kaprekar_routine(3524)
   3087
   >>> kaprekar_routine(3087)
   8352
   >>> kaprekar_routine(8352)
   6174
   >>> kaprekar_routine(6174)
   6174
   >>> kaprekar_routine(1)
   999
   >>> kaprekar_routine(1111)
   0


.. py:function:: main() -> None

   Demonstrate Kaprekar's constant with user input and examples.