Java API to Convert Number to Words

In many real-world applications, there is a need to convert numerical values into their corresponding word representations. For example, in financial applications, checks are written with both the numerical amount and the amount in words to avoid confusion and fraud. Java, being a widely used programming language, provides several ways to achieve this conversion. This blog post will explore the core concepts, typical usage scenarios, common pitfalls, and best practices related to converting numbers to words using Java APIs.

Table of Contents#

  1. Core Concepts
  2. Typical Usage Scenarios
  3. Common Pitfalls
  4. Best Practices
  5. Code Examples
  6. Conclusion
  7. FAQ
  8. References

Core Concepts#

The process of converting a number to words involves breaking down the number into its components (such as units, tens, hundreds, thousands, etc.) and then mapping these components to their corresponding word equivalents. For example, the number 123 can be broken down into 1 hundred, 2 tens, and 3 units, and then translated to "one hundred twenty-three".

In Java, we can implement this conversion either by writing custom algorithms or by using existing libraries. One approach is to use the java.text.NumberFormat class in combination with java.util.Locale to format numbers according to different languages and numbering systems. However, for more complex and accurate conversion of numbers to words, third-party libraries like "NumberToWords" can be very useful.

Typical Usage Scenarios#

  • Financial Applications: As mentioned earlier, financial documents such as checks, invoices, and receipts often require the amount to be written in words for clarity and security.
  • Speech Synthesis: When creating voice-enabled applications, numbers need to be converted to words so that they can be spoken naturally.
  • Document Generation: In reports and official documents, numerical data might need to be presented in word form for better readability.

Common Pitfalls#

  • Localization Issues: Different languages have different rules for number naming. For example, in English, we say "one hundred and twenty-three", while in some other languages, the "and" is not used. If you are not careful with localization, the word representation might be incorrect.
  • Handling Large Numbers: Java's primitive data types have limitations. For very large numbers, you need to use BigInteger or BigDecimal to avoid overflow issues. And converting these large numbers to words can be more complex.
  • Edge Cases: Numbers like zero, negative numbers, and numbers with decimal parts need special handling. For example, converting a negative number to words requires adding the word "negative" at the beginning.

Best Practices#

  • Use Libraries: Instead of writing a custom algorithm from scratch, use well-tested third-party libraries. They often handle localization and edge cases better.
  • Localization Awareness: Always consider the target language and use appropriate locale settings. This ensures that the number-to-word conversion is correct according to the language's rules.
  • Error Handling: When dealing with user-input numbers, validate the input to avoid unexpected behavior. For example, check if the input is a valid number before attempting to convert it.

Code Examples#

Using a Custom Algorithm for Small Integer Numbers#

import java.util.HashMap;
import java.util.Map;
 
public class NumberToWords {
    private static final Map<Integer, String> numberMap = new HashMap<>();
    static {
        numberMap.put(0, "zero");
        numberMap.put(1, "one");
        numberMap.put(2, "two");
        numberMap.put(3, "three");
        numberMap.put(4, "four");
        numberMap.put(5, "five");
        numberMap.put(6, "six");
        numberMap.put(7, "seven");
        numberMap.put(8, "eight");
        numberMap.put(9, "nine");
        numberMap.put(10, "ten");
        numberMap.put(11, "eleven");
        numberMap.put(12, "twelve");
        numberMap.put(13, "thirteen");
        numberMap.put(14, "fourteen");
        numberMap.put(15, "fifteen");
        numberMap.put(16, "sixteen");
        numberMap.put(17, "seventeen");
        numberMap.put(18, "eighteen");
        numberMap.put(19, "nineteen");
        numberMap.put(20, "twenty");
        numberMap.put(30, "thirty");
        numberMap.put(40, "forty");
        numberMap.put(50, "fifty");
        numberMap.put(60, "sixty");
        numberMap.put(70, "seventy");
        numberMap.put(80, "eighty");
        numberMap.put(90, "ninety");
    }
 
    public static String convert(int number) {
        if (number < 20) {
            return numberMap.get(number);
        }
        if (number < 100) {
            return numberMap.get((number / 10) * 10) + (number % 10 == 0 ? "" : " " + numberMap.get(number % 10));
        }
        if (number < 1000) {
            return numberMap.get(number / 100) + " hundred" + (number % 100 == 0 ? "" : " and " + convert(number % 100));
        }
        return ""; // This can be extended for larger numbers
    }
 
    public static void main(String[] args) {
        int num = 123;
        System.out.println(convert(num));
    }
}

Using a Third-Party Library (NumberToWords)#

First, add the library to your project. If you are using Maven, add the following dependency:

<dependency>
    <groupId>com.github.vincentrussell</groupId>
    <artifactId>number-to-words</artifactId>
    <version>1.0.3</version>
</dependency>
import com.github.vincentrussell.numbertotext.NumberToTextConverter;
 
public class ThirdPartyExample {
    public static void main(String[] args) {
        int number = 123;
        NumberToTextConverter converter = new NumberToTextConverter();
        String words = converter.toWords(number);
        System.out.println(words);
    }
}

Conclusion#

Converting numbers to words in Java can be achieved through custom algorithms or by using third-party libraries. While custom algorithms give you more control, they require more effort to handle all edge cases and localization. Third-party libraries are often more convenient and reliable, especially when dealing with complex scenarios. By being aware of the core concepts, typical usage scenarios, common pitfalls, and best practices, you can effectively implement number-to-word conversion in your Java applications.

FAQ#

Q: Can I convert decimal numbers to words? A: Yes, but it requires additional handling. You need to separate the integer part and the decimal part and convert them separately. Some libraries also support direct conversion of decimal numbers.

Q: Are there any built-in Java APIs for number-to-word conversion? A: Java does not have a direct built-in API for converting numbers to words. However, the java.text.NumberFormat class can be used for basic number formatting, which can be a part of the overall process.

Q: How can I handle negative numbers? A: You can add the word "negative" at the beginning of the word representation of the absolute value of the number.

References#

2025-10