Converter Module

Module: piethorn.math.converter

Overview

This module translates between numbers and English wording and includes a few helper conversions for large magnitudes and text-to-digit obfuscation.

find_number_name

find_number_name(exponent)

Return the scale word for a decimal exponent.

find_number_name_from_value

find_number_name_from_value(number)

Return a scale-name pair for a decimal magnitude.

convert_to_words

convert_to_words(number)

Convert a number to an English phrase.

from piethorn.math.converter import convert_to_words

convert_to_words(0)      # "Zero"
convert_to_words(12.5)   # "Twelve and Five Tenth"

convert_partial_word

convert_partial_word(number, places_before_word=0, round_to=2147483647)

Produce a compact numeric-plus-scale representation.

convert_partial_word(1234567, 2, 4)  # "1234.567 Thousand"

convert_to_number

convert_to_number(number_words)

Parse a numeric string or English phrase into decimal.Decimal.

convert_to_big

convert_to_big(number)

Coerce several input types into decimal.Decimal.

letter_to_number

letter_to_number(sentence, percent_to_convert=-1.0)

Replace supported characters with lookalike digits based on a percentage.

Autodoc

piethorn.math.converter

One-to-one Python port of the Java cache utility.

This module intentionally preserves Java behavior, including:

  • Naming quirks

  • Edge cases

  • Large-number Latin prefix rules

  • Fraction handling semantics

This module intentionally preserves the Java behavior so outputs and parsing round-trip the same way.

Notable behaviors preserved from Java:

  • Fractions are expressed using “and” plus an ordinal place name (for example, 0.25 -> "Zero and Twenty Five Hundredth").

  • Large-number names are generated using the same Latin-prefix construction.

  • convert_partial_word() returns a numeric string followed by a scale word, matching Java’s formatting logic.

Public API (mirrors Java, with snake_case aliases):

  • find_number_name(exponent: int) -> str

  • find_number_name_from_value(number: Decimal) -> Pair[str, Decimal]

  • convert_to_words(number: Any) -> str

  • convert_partial_word(number: Any, places_before_word: int = 0, round_to: int = 2**31 - 1) -> str

  • convert_to_number(number_words: str) -> Decimal

  • convert_to_big(number: Any) -> Decimal

piethorn.math.converter.convert_partial_word(number: Any, places_before_word: int = 0, round_to: int = 2147483647) → str

Convert a number into words but optionally truncate/round its magnitude.

Java method: convertPartialWord(BigDecimal n, int placesBeforeWord, int roundTo).

This is used to express a number using a shorter word scale (e.g., “12.3 Million”) by shifting the decimal point before converting. The output formatting and rounding behavior matches Java (including ‘plain string’ rendering).

piethorn.math.converter.convert_to_big(number: Any) → Decimal

Coerce an arbitrary input into a Decimal (“BigDecimal”) equivalent.

Java method: convertToBig(Object n).

Supports: - numbers / numeric strings - iterables / arrays (average of elements) - mappings (average of values) - non-numeric fallback: hash-based deterministic conversion (Java parity)

piethorn.math.converter.convert_to_number(number_words: str) → Decimal

Parse English words back into a Decimal (Java convertToNumber(String)).

This attempts direct numeric parsing first (Decimal(number_words)). If that fails, it tokenizes the English words and accumulates the numeric value using the same scale tables/caches that convert_to_words uses.

piethorn.math.converter.convert_to_words(number: Any) → str

Public entry point: convert a number into English words.

Java method: convertToWords(Object n).

Accepts multiple input types (Decimal, int/float, strings, collections, etc.) and applies the same coercion rules as Java, then delegates to the internal Decimal implementation.

piethorn.math.converter.find_number_name(exponent: int) → str

Return the scale name for a base-10 exponent.

Java method: findNumberName(int exponent).

This is a thin wrapper that normalizes the exponent to a thousand-group boundary and then delegates to _get_numbers_name.

piethorn.math.converter.find_number_name_from_value(number: Decimal) → Pair

Return the scale name for a numeric value.

Java method: findNumberName(BigDecimal value).

The value is converted to an exponent (base 10), rounded down to a multiple of 3, and mapped to a name (e.g., 1E6 -> “Million”).

piethorn.math.converter.letter_to_number(sentence: str, percent_to_convert: float = -1.0)

Randomly replace mapped letters in a sentence with lookalike digits.

If percent_to_convert is less than zero or greater than 100, then will generate a randomly skewed percent using percent_to_convert as a hint with an upper modifier of 91 and lower modifier of 5.

Parameters:

  • sentence – Sentence to convert.

  • percent_to_convert – The amount of sentence to convert.