0
# Number Conversion
1

2
Core functionality for converting numbers to word representations in multiple languages and formats. The main `num2words()` function provides a unified interface for all conversion types across all supported languages.
3

4
## Capabilities
5

6
### Cardinal Numbers
7

8
Convert integers and floats to their word representation (e.g., 42 → "forty-two").
9

10
```python { .api }
11
def num2words(number, lang='en', to='cardinal', **kwargs):
12
    """
13
    Convert number to cardinal word form.
14
    
15
    Parameters:
16
    - number: int/float/str - Number to convert
17
    - lang: str - Language code (default: 'en')
18
    - to: str - Must be 'cardinal' for this conversion type
19
    - **kwargs: Language-specific formatting options
20
    
21
    Returns:
22
    str - Cardinal number as words
23
    
24
    Raises:
25
    NotImplementedError - For unsupported languages
26
    TypeError - For invalid number types
27
    OverflowError - For numbers exceeding language limits
28
    """
29
```
30

31
**Usage Examples:**
32

33
```python
34
from num2words import num2words
35

36
# Basic integers
37
num2words(42)                    # "forty-two"
38
num2words(1000)                  # "one thousand"
39
num2words(1234567)               # "one million, two hundred and thirty-four thousand, five hundred and sixty-seven"
40

41
# Negative numbers
42
num2words(-15)                   # "minus fifteen"
43

44
# Decimal numbers
45
num2words(42.5)                  # "forty-two point five"
46
num2words(3.14159)               # "three point one four one five nine"
47

48
# Different languages
49
num2words(42, lang='fr')         # "quarante-deux"
50
num2words(42, lang='es')         # "cuarenta y dos"
51
num2words(42, lang='de')         # "zweiundvierzig"
52
num2words(42, lang='ja')         # "四十二"
53
```
54

55
### Ordinal Numbers
56

57
Convert numbers to ordinal word form (e.g., 42 → "forty-second").
58

59
```python { .api }
60
def num2words(number, lang='en', to='ordinal', **kwargs):
61
    """
62
    Convert number to ordinal word form.
63
    
64
    Parameters:
65
    - number: int - Integer to convert (floats not supported)
66
    - lang: str - Language code (default: 'en')
67
    - to: str - Must be 'ordinal' for this conversion type
68
    - **kwargs: Language-specific formatting options
69
    
70
    Returns:
71
    str - Ordinal number as words
72
    
73
    Raises:
74
    NotImplementedError - For unsupported languages
75
    TypeError - For float inputs or negative numbers
76
    """
77
```
78

79
**Usage Examples:**
80

81
```python
82
# Basic ordinals
83
num2words(1, to='ordinal')       # "first"
84
num2words(2, to='ordinal')       # "second"
85
num2words(3, to='ordinal')       # "third"
86
num2words(21, to='ordinal')      # "twenty-first"
87
num2words(42, to='ordinal')      # "forty-second"
88

89
# Different languages
90
num2words(1, to='ordinal', lang='fr')   # "premier"
91
num2words(2, to='ordinal', lang='es')   # "segundo"
92

93
# Backward compatibility (deprecated)
94
num2words(42, ordinal=True)      # "forty-second" (equivalent to to='ordinal')
95
```
96

97
### Ordinal Numbers (Numeric)
98

99
Convert numbers to ordinal numeric form (e.g., 42 → "42nd").
100

101
```python { .api }
102
def num2words(number, lang='en', to='ordinal_num', **kwargs):
103
    """
104
    Convert number to ordinal numeric form.
105
    
106
    Parameters:
107
    - number: int - Integer to convert
108
    - lang: str - Language code (default: 'en')
109
    - to: str - Must be 'ordinal_num' for this conversion type
110
    - **kwargs: Language-specific formatting options
111
    
112
    Returns:
113
    str - Ordinal number in numeric format with suffix
114
    """
115
```
116

117
**Usage Examples:**
118

119
```python
120
num2words(1, to='ordinal_num')   # "1st"
121
num2words(2, to='ordinal_num')   # "2nd"
122
num2words(3, to='ordinal_num')   # "3rd"
123
num2words(4, to='ordinal_num')   # "4th"
124
num2words(21, to='ordinal_num')  # "21st"
125
num2words(42, to='ordinal_num')  # "42nd"
126
```
127

128
### Year Format
129

130
Convert numbers to year word form with language-specific formatting.
131

132
```python { .api }
133
def num2words(number, lang='en', to='year', **kwargs):
134
    """
135
    Convert number to year word form.
136
    
137
    Parameters:
138
    - number: int - Year to convert (typically 4-digit)
139
    - lang: str - Language code (default: 'en')
140
    - to: str - Must be 'year' for this conversion type
141
    - **kwargs: Language-specific year formatting options
142
    
143
    Returns:
144
    str - Year as words in language-specific format
145
    """
146
```
147

148
**Usage Examples:**
149

150
```python
151
num2words(1984, to='year')       # "nineteen eighty-four"
152
num2words(2000, to='year')       # "two thousand"
153
num2words(2023, to='year')       # "twenty twenty-three"
154
num2words(1066, to='year')       # "ten sixty-six"
155

156
# Different languages may have different year formatting
157
num2words(1984, to='year', lang='fr')   # Language-specific year format
158
```
159

160
### String Input Handling
161

162
The function accepts string inputs and converts them to numbers first.
163

164
```python { .api }
165
def num2words(number, **kwargs):
166
    """
167
    Handle string inputs by converting to number first.
168
    
169
    Parameters:
170
    - number: str - String representation of number
171
    - **kwargs: Same as numeric inputs
172
    
173
    Returns:
174
    str - Converted number as words
175
    
176
    Raises:
177
    ValueError - For invalid string formats
178
    """
179
```
180

181
**Usage Examples:**
182

183
```python
184
num2words("42")                  # "forty-two"
185
num2words("42.5")                # "forty-two point five"
186
num2words("1,234")               # Handles comma-separated format
187
num2words("-15")                 # "minus fifteen"
188
```
189

190
### Language Fallback
191

192
The library provides intelligent language fallback for regional variants.
193

194
**Usage Examples:**
195

196
```python
197
# Full language codes
198
num2words(42, lang='en_US')      # Falls back to 'en'
199
num2words(42, lang='fr_FR')      # Falls back to 'fr'
200
num2words(42, lang='es_MX')      # Falls back to 'es'
201

202
# Specific regional variants (where supported)
203
num2words(42, lang='en_IN')      # English (India) - specific formatting
204
num2words(42, lang='fr_BE')      # French (Belgium) - specific formatting
205
num2words(42, lang='es_CO')      # Spanish (Colombia) - specific formatting
206

207
# Error handling for unsupported languages
208
try:
209
    num2words(42, lang='unsupported')
210
except NotImplementedError:
211
    # Fallback to default language
212
    result = num2words(42, lang='en')
213
```
214

215
## Error Handling
216

217
The conversion function provides clear error messages for various edge cases:
218

219
```python
220
# Type errors
221
try:
222
    num2words(42.5, to='ordinal')  # Floats not supported for ordinals
223
except TypeError as e:
224
    print(e)  # "Cannot treat float 42.5 as ordinal."
225

226
# Negative ordinals
227
try:
228
    num2words(-5, to='ordinal')
229
except TypeError as e:
230
    print(e)  # "Cannot treat negative num -5 as ordinal."
231

232
# Numbers too large
233
try:
234
    num2words(10**100)  # Exceeds maximum supported value
235
except OverflowError as e:
236
    print(e)  # Language-specific maximum value message
237

238
# Unsupported languages
239
try:
240
    num2words(42, lang='xyz')
241
except NotImplementedError:
242
    print("Language not supported")
243
```