---

C# Number to Words: The Complete Guide to Converting Longs into English Text

Learn to convert any number up to 999,999,999,999 into its full English word equivalent in C#. This guide breaks down the core logic, provides a detailed code walkthrough, and covers everything from basic principles to handling trillion-scale integers for financial and accessibility applications.

---

The Daily Grind: Why Converting Numbers to Words Matters

Imagine your friend Yaʻqūb, who works behind the counter at the city's most popular deli. The line of hungry customers is endless, a river of people eager for their orders. To maintain order, each customer grabs a numbered ticket. When a fresh order is ready, Yaʻqūb doesn't just shout a digit; he calls out the full number in clear English words: "Now serving, number one hundred twenty-three!"

This ensures everyone, from the front of the line to the back, hears the number correctly, avoiding confusion and keeping the queue moving smoothly. What Yaʻqūb does instinctively—translating digits into words—is a surprisingly common and fascinating challenge for software developers. From printing the legal amount on a bank check to building accessibility features for screen readers, this task is more than just an academic puzzle.

You've likely encountered this problem and felt the initial complexity. How do you teach a machine the nuanced rules of the English language for numbers? This guide will walk you through the entire process, transforming that complexity into a clear, manageable algorithm using the power and elegance of C#.

---

What is the Number-to-Words Conversion Problem?

The number-to-words problem is a classic programming challenge that involves creating a function or algorithm that takes a numerical input and returns its English language representation as a string. For this specific task, derived from the exclusive kodikra.com C# curriculum, the scope is well-defined: handle any non-negative integer from 0 up to 999,999,999,999 (one less than a trillion).

The core of the challenge lies in breaking down a large number into manageable parts and applying a consistent set of rules. Humans do this subconsciously. When we see 1,234,567, we don't process it as seven individual digits. Instead, we see chunks:

• 1 million
• 234 thousand
• 567

Our goal is to programmatically replicate this chunking logic. We need to create a system that can handle the unique names for numbers 0-19, the pattern for tens (twenty, thirty, forty), and the scale words (thousand, million, billion). The final output must be a grammatically correct, space-separated string, just as you would say it out loud.

Key Technical Constraints and Entities

• Input Type: The input is a long (Int64) in C#. This is crucial because a standard int (Int32) can only hold values up to about 2.1 billion, which is insufficient for our maximum range of 999 billion.
• Output Type: The function must return a string.
• Range: The valid input range is 0 to 999,999,999,999 inclusive. Any number outside this range should trigger an error.
• Error Handling: Invalid inputs (negative numbers or numbers too large) must be handled gracefully, typically by throwing an ArgumentOutOfRangeException.

---

Why This Algorithm is a Cornerstone of Software Development

While it might seem like a niche problem, the logic behind number-to-word conversion appears in many critical software applications. Understanding how to solve it equips you with skills in algorithmic thinking, problem decomposition, and handling edge cases—skills that are universally valuable.

Here’s why this is more than just a coding exercise:

• Financial Technology (FinTech): This is the most common application. When printing checks, invoices, or legal financial documents, the numerical amount is often written out in words to prevent fraud and ambiguity. For example, "$1,500.25" is written as "One thousand five hundred and 00/100 dollars."
• Accessibility (a11y): Screen reader software, which assists visually impaired users, must convert numerical data on a screen into spoken words. A well-designed number-to-word converter ensures that data from charts, tables, and text is read out naturally.
• Voice User Interfaces (VUI): Systems like Alexa, Siri, and Google Assistant need to vocalize numerical information. Whether it's telling you the current stock price or the population of a city, this conversion logic is running behind the scenes.
• Educational Tool: It's a fantastic problem for teaching fundamental programming concepts like recursion, iteration, modularity (using helper functions), and data structures (like dictionaries or arrays to store word mappings).

By mastering this challenge from the Kodikra C# Learning Path, you are building a foundational block that strengthens your ability to tackle more complex logical problems in any domain.

---

How to Convert Numbers to Words: The Algorithmic Strategy

The key to solving this problem is to not solve it all at once. We must decompose the large problem into smaller, repeatable sub-problems. The most effective strategy is "chunking," which mirrors how our brains process large numbers.

The Three-Step Master Plan

Our algorithm can be broken down into three primary steps:

1. Validate and Handle Edge Cases: First, get the simple cases out of the way. If the number is 0, return "zero". If it's outside our allowed range (negative or >= 1 trillion), throw an exception.
2. Chunk the Number: Divide the input number into groups of three digits, starting from the right. Each chunk will correspond to a scale: thousands, millions, billions. For example, 12,345,678,910 becomes four chunks: 12, 345, 678, 910.
3. Convert and Combine: Process each chunk using a helper function that can convert any number from 0-999 into words. Then, append the correct scale word ("billion", "million", "thousand") to each non-zero chunk and join them all together.

ASCII Diagram: High-Level Chunking Logic

This diagram illustrates how a large number is deconstructed into scaled chunks before being processed.

    ● Start with a large number (e.g., 1234567890)
    │
    ▼
  ┌───────────────────┐
  │ Is number == 0?   │
  └─────────┬─────────┘
            │
      No    ▼
  ┌───────────────────┐
  │ Loop: number > 0  │
  └─────────┬─────────┘
            │
            ▼
┌───────────────────────────┐
│ Chunk = number % 1000     │  // Get the last 3 digits
│ Scale = Get current scale │  // (e.g., "", "thousand", "million")
└────────────┬──────────────┘
             │
             ▼
┌───────────────────────────┐
│ ProcessChunk(Chunk, Scale)│
└────────────┬──────────────┘
             │
             ▼
┌───────────────────────────┐
│ number = number / 1000    │  // Move to the next chunk
└────────────┬──────────────┘
             │
             ▼
  ◆ More chunks to process?
   ╱           ╲
  Yes ─────────┘ (Loop back)
   │
   No
   │
   ▼
┌───────────────────────────┐
│ Join all processed parts  │
│ (e.g., "one billion" +    │
│ "two hundred...")         │
└────────────┬──────────────┘
             │
             ▼
    ● End (Return final string)

The Core Engine: The Three-Digit Converter

The most critical piece of our solution is a helper function that can take any number between 0 and 999 and return its word form. This function itself has a clear internal logic:

1. Handle Hundreds: If the number is 100 or greater, find the digit for the hundreds place (e.g., for 789, it's 7). Convert it to a word ("seven"), append " hundred", and then process the remainder (89).
2. Handle Tens and Units: For the remaining number (0-99):
   • If it's less than 20, use a direct lookup (e.g., 1 = "one", 12 = "twelve").
   • If it's 20 or greater, handle the tens place (20 = "twenty", 30 = "thirty", etc.) and the units place (1 = "one", 2 = "two", etc.) separately, often joining them with a hyphen (though our problem requires a space).

ASCII Diagram: Three-Digit Converter Logic (e.g., for number 245)

    ● Start with number N (0-999)
    │
    ▼
  ┌────────────────┐
  │ N = 245        │
  └───────┬────────┘
          │
          ▼
    ◆ N >= 100?
   ╱           ╲
  Yes           No
  │              │
  ▼              ▼
┌────────────────┐  (Skip to tens)
│ Digit = N / 100│  // 2
│ Word = "two"   │
│ Append " hundred"│
│ N = N % 100    │  // N is now 45
└───────┬────────┘
        │
        ▼
    ◆ N > 0?
   ╱           ╲
  Yes           No
  │              │
  ▼              ▼
┌────────────────┐  (End of Hundreds)
│ Append " "     │
└───────┬────────┘
        │
        ▼
    ◆ N < 20?
   ╱           ╲
  No            Yes
  │              │
  ▼              ▼
┌────────────────┐ ┌────────────────┐
│ Tens = N / 10  │ │ Lookup N in    │
│ Word = "forty" │ │ 0-19 map       │
│ N = N % 10     │ │ (e.g., 17 ->   │
└───────┬────────┘ │ "seventeen")   │
        │          └───────┬────────┘
        ▼                  │
    ◆ N > 0?               │
   ╱           ╲           │
  Yes           No         │
  │              │         │
  ▼              ▼         │
┌────────────────┐ (End of Tens) │
│ Append " "     │         │
│ Units = N      │         │
│ Word = "five"  │         │
└───────┬────────┘         │
        │                  │
        └────────┬─────────┘
                 │
                 ▼
    ● End (Result: "two hundred forty-five")

---

Where the Logic is Implemented: A C# Code Walkthrough

Now, let's analyze a complete and elegant C# solution that implements this strategy. This code is structured to be both efficient and readable, leveraging modern C# features.

using System;
using System.Collections.Generic;
using System.Linq;

public static class Say
{
    private static readonly Dictionary<long, string> NumberWords = new Dictionary<long, string>
    {
        {0, "zero"}, {1, "one"}, {2, "two"}, {3, "three"}, {4, "four"}, {5, "five"},
        {6, "six"}, {7, "seven"}, {8, "eight"}, {9, "nine"}, {10, "ten"},
        {11, "eleven"}, {12, "twelve"}, {13, "thirteen"}, {14, "fourteen"}, {15, "fifteen"},
        {16, "sixteen"}, {17, "seventeen"}, {18, "eighteen"}, {19, "nineteen"}, {20, "twenty"},
        {30, "thirty"}, {40, "forty"}, {50, "fifty"}, {60, "sixty"}, {70, "seventy"},
        {80, "eighty"}, {90, "ninety"}
    };

    private static readonly (long value, string name)[] Scales =
    {
        (1_000_000_000, "billion"),
        (1_000_000, "million"),
        (1_000, "thousand"),
        (100, "hundred")
    };

    public static string InEnglish(long number)
    {
        if (number < 0 || number >= 1_000_000_000_000)
        {
            throw new ArgumentOutOfRangeException(nameof(number), "Input must be between 0 and 999,999,999,999.");
        }

        if (number == 0)
        {
            return NumberWords[0];
        }

        return GenerateWords(number);
    }

    private static string GenerateWords(long number)
    {
        if (NumberWords.ContainsKey(number))
        {
            return NumberWords[number];
        }

        var parts = new List<string>();
        
        // Handle scales (billions, millions, thousands, hundreds)
        foreach (var (value, name) in Scales)
        {
            if (number >= value)
            {
                parts.Add($"{GenerateWords(number / value)} {name}");
                number %= value;
            }
        }

        // Handle tens and units (1-99)
        if (number > 0)
        {
            if (NumberWords.ContainsKey(number))
            {
                parts.Add(NumberWords[number]);
            }
            else
            {
                long tens = (number / 10) * 10;
                long units = number % 10;
                parts.Add($"{NumberWords[tens]}-{NumberWords[units]}");
            }
        }

        return string.Join(" ", parts);
    }
}

Detailed Breakdown of the Code

1. Data Storage: NumberWords and Scales

The code starts by defining two static readonly data structures. This is a highly efficient approach because these collections are created only once when the class is loaded, and their values never change.

• Dictionary<long, string> NumberWords: This dictionary is a fast lookup table for all the unique number words (0-19, 20, 30...90). Using a dictionary provides O(1) average time complexity for lookups, which is ideal.
• (long value, string name)[] Scales: This is an array of tuples. It elegantly stores the scale values and their corresponding names. Storing them in descending order is crucial for the algorithm's logic, as we want to process the largest chunks (billions) first.

2. The Public Entry Point: InEnglish(long number)

This is the public API method that users will call. Its role is simple but critical: validation and delegation.

public static string InEnglish(long number)
{
    if (number < 0 || number >= 1_000_000_000_000)
    {
        throw new ArgumentOutOfRangeException(nameof(number), "Input must be between 0 and 999,999,999,999.");
    }

    if (number == 0)
    {
        return NumberWords[0];
    }

    return GenerateWords(number);
}

• Guard Clauses: The first if statement is a "guard clause." It checks for invalid input at the very beginning and fails fast by throwing an ArgumentOutOfRangeException. This is a best practice that prevents invalid data from propagating through your system.
• Edge Case Handling: The second if handles the simplest case: 0. By handling it here, we simplify the logic in the main recursive function.
• Delegation: For all other valid numbers, it calls the private helper method GenerateWords, which contains the core conversion logic.

3. The Core Recursive Logic: GenerateWords(long number)

This method is the heart of the solution. It uses recursion to break the number down piece by piece.

private static string GenerateWords(long number)
{
    // Base case 1: Direct lookup
    if (NumberWords.ContainsKey(number))
    {
        return NumberWords[number];
    }

    var parts = new List<string>();

    // Recursive step for scales
    foreach (var (value, name) in Scales)
    {
        if (number >= value)
        {
            parts.Add($"{GenerateWords(number / value)} {name}");
            number %= value;
        }
    }
    
    // ... logic for 21-99 ...
}

• Base Case: The first if statement is the recursive base case. If the number can be found directly in our NumberWords dictionary (like 15 or 50), it returns the word immediately, stopping the recursion for that branch.
• Recursive Step: The foreach loop iterates through the Scales array (from billions down to hundreds).
  • If the current number is large enough to contain a scale (e.g., number >= 1_000_000), it performs two actions.
  • 1. Recursive Call: It calls GenerateWords again, but this time with the quotient (number / value). For 1,234,000, the first call would be GenerateWords(1) for the "million" scale. This call will hit the base case and return "one". The code then constructs the string "one million".
  • 2. Remainder Calculation: It uses the modulo operator (number %= value) to chop off the part that was just processed. In our example, 1,234,000 % 1,000,000 leaves 234,000 for the next iteration of the loop.

4. Handling the Remainder (1-99)

After the scales loop, the remaining number will always be less than 100.

if (number > 0)
{
    if (NumberWords.ContainsKey(number))
    {
        parts.Add(NumberWords[number]);
    }
    else
    {
        long tens = (number / 10) * 10; // e.g., 45 -> 40
        long units = number % 10;       // e.g., 45 -> 5
        parts.Add($"{NumberWords[tens]}-{NumberWords[units]}");
    }
}

• This section handles numbers like 45. It's not in the dictionary directly.
• The code calculates the tens part (40) and the units part (5).
• It then looks up both in the NumberWords dictionary and combines them with a hyphen, resulting in "forty-five". Note: The original problem asks for a space, so this could be changed to $"{...} {...}". The hyphen is a common convention.

5. Final Assembly

Finally, string.Join(" ", parts) takes all the generated string pieces (like "one million", "two hundred thirty-four thousand", "five hundred sixty-seven") and stitches them together with spaces in between, producing the final result.

Running the Code from the Terminal

To test this code, you can place it in a C# console application and run it from your terminal.

1. Create a file Program.cs:

// Paste the entire Say class here...

public class Program
{
    public static void Main(string[] args)
    {
        long numberToTest = 123456789012;
        try
        {
            string words = Say.InEnglish(numberToTest);
            Console.WriteLine($"{numberToTest} --> {words}");
        }
        catch (ArgumentOutOfRangeException ex)
        {
            Console.WriteLine($"Error: {ex.Message}");
        }
    }
}

2. Run from the command line:

# Create a new console project
dotnet new console -n NumberConverter

# Navigate into the directory
cd NumberConverter

# Replace the content of Program.cs with the code above

# Run the project
dotnet run

The expected output will be:

123456789012 --> one hundred twenty-three billion four hundred fifty-six million seven hundred eighty-nine thousand twelve

---

Pros and Cons of the Recursive Approach

Every algorithmic choice comes with trade-offs. The recursive solution presented is elegant and highly readable for those familiar with recursion, but it's worth comparing it to a more traditional iterative approach.

Aspect	Recursive Solution (As Implemented)	Iterative (Loop-based) Solution
Readability	Can be very clean and declarative. The logic GenerateWords(number / value) clearly expresses "convert the prefix."	Often more verbose but can be easier for beginners to follow step-by-step without understanding the call stack.
Performance	For each recursive call, a new stack frame is created. For a number in the high billions, this results in a few nested calls, which is perfectly acceptable and has negligible overhead.	Avoids function call overhead, which can be marginally faster in performance-critical scenarios. However, for this problem, the difference is insignificant.
Stack Overflow Risk	The maximum recursion depth is very small (billions -> millions -> thousands -> hundreds), so there is virtually no risk of a StackOverflowException.	No risk of stack overflow, as it relies on a simple loop.
Code Complexity	The logic is concise. The complexity is in understanding the flow of recursive calls.	The logic might involve more manual state management (e.g., building a list of strings inside a single loop), which can sometimes make the code longer.

For this problem, the recursive solution is an excellent choice. It naturally models the "divide and conquer" nature of the problem and leads to clean, maintainable code.

---

Frequently Asked Questions (FAQ)

1. How do you handle the word "and" in numbers?

The presented solution follows American English convention, which typically omits "and". For example, 123 is "one hundred twenty-three". In British English, it would be "one hundred and twenty-three". To add this, you would modify the three-digit converter logic to insert " and " if there is a hundreds part and a non-zero remainder.

2. Can this code handle numbers larger than trillions?

Not as written. To support larger numbers (quadrillion, quintillion, etc.), you would simply need to add their values and names to the Scales array in the correct descending order. The recursive logic is already generic enough to handle it automatically.

private static readonly (long value, string name)[] Scales =
{
    (1_000_000_000_000_000, "quadrillion"), // Add this
    (1_000_000_000, "billion"),
    // ... rest of the scales
};
    

3. What is ArgumentOutOfRangeException and why is it used?

ArgumentOutOfRangeException is a specific type of exception in .NET used to indicate that the value of an argument passed to a method is outside the allowable range of values. It's better than a generic Exception because it clearly communicates the nature of the error to the calling code, making debugging easier.

4. Why use long instead of int for the number?

A standard int in C# is a 32-bit signed integer with a maximum value of 2,147,483,647 (about 2.1 billion). The problem requires handling numbers up to 999,999,999,999, which is far beyond the capacity of an int. A long is a 64-bit signed integer that can hold values up to approximately 9 quintillion, making it the appropriate choice.

5. Is there a way to solve this without recursion?

Yes, an iterative solution is absolutely possible. You could use a while loop that processes the number in chunks of 1000. Inside the loop, you would convert the 0-999 chunk, append the correct scale word (from an array of scales), and then divide the number by 1000 to prepare for the next iteration. The result would be built up in a list and joined at the end.

6. How can this code be adapted for other languages like Spanish or French?

The core chunking logic remains the same, but the implementation of the three-digit converter and the scale words would need to change significantly. Many languages have different grammatical rules for numbers (e.g., gender agreement, different words for 70, 80, 90 in French). You would need to replace the NumberWords and Scales data structures and likely rewrite the GenerateWords logic to accommodate these new rules.

7. What are the performance implications of using string concatenation in a loop?

The solution wisely avoids repeated string concatenation (e.g., s = s + " new part"), which can be inefficient because strings are immutable in C#. Instead, it builds a List<string> called parts and then uses string.Join(" ", parts) at the very end. This is a highly performant and recommended pattern for building strings from multiple pieces.

---

Conclusion and Future-Proofing

You have now explored the complete journey of solving the number-to-words problem in C#. We've seen how a seemingly daunting task can be conquered by breaking it down into logical, manageable chunks. The recursive strategy, combined with efficient data lookups, provides a solution that is not only correct but also elegant and easy to understand.

The core takeaway is the power of decomposition. By creating a robust helper function that handles numbers from 0-999, the larger problem of handling trillions becomes a simple matter of repetition and scaling. This pattern of identifying and solving a core sub-problem is a fundamental skill in software engineering.

As you continue your journey through the Kodikra C# 8 Learning Path, you will find this pattern reappearing in various forms. To deepen your expertise, explore our comprehensive C# language guide for more advanced topics and challenges.

Disclaimer: All code in this article is written and tested against modern .NET standards (e.g., .NET 8+) and C# 12 features. The fundamental logic is timeless, but syntax and available APIs may evolve in future versions.

---

Published by Kodikra — Your trusted Csharp learning resource.