0
# Number Formatting
1

2
Comprehensive number formatting utilities for converting numeric values into human-readable formats including comma separation, word conversion, ordinals, fractions, scientific notation, and metric prefixes.
3

4
## Capabilities
5

6
### Comma Formatting
7

8
Adds comma thousands separators to numbers for improved readability, supporting both integers and floats with optional decimal precision control.
9

10
```python { .api }
11
def intcomma(value: float | str, ndigits: int | None = None) -> str:
12
    """
13
    Converts an integer to a string containing commas every three digits.
14
    
15
    Args:
16
        value: Integer, float, or string to convert
17
        ndigits: Optional digits of precision for rounding after decimal point
18
    
19
    Returns:
20
        String with commas every three digits
21
    
22
    Examples:
23
        >>> intcomma(1000)
24
        '1,000'
25
        >>> intcomma(1_234_567.25)
26
        '1,234,567.25'
27
        >>> intcomma(1234.5454545, 2)
28
        '1,234.55'
29
    """
30
```
31

32
### Word Conversion
33

34
Converts large numbers into friendly text representations using words like "million", "billion", etc. Supports numbers up to decillion and googol.
35

36
```python { .api }
37
def intword(value: float | str, format: str = "%.1f") -> str:
38
    """
39
    Converts a large integer to a friendly text representation.
40
    
41
    Args:
42
        value: Integer, float, or string to convert
43
        format: Format string for the number portion (default "%.1f")
44
    
45
    Returns:
46
        Friendly text representation, or original string if conversion fails
47
    
48
    Examples:
49
        >>> intword(1000000)
50
        '1.0 million'
51
        >>> intword(1_200_000_000)
52
        '1.2 billion'
53
        >>> intword("1234000", "%0.3f")
54
        '1.234 million'
55
    """
56
```
57

58
### Ordinal Numbers
59

60
Converts integers to ordinal form (1st, 2nd, 3rd, etc.) with support for gendered translations in supported languages.
61

62
```python { .api }
63
def ordinal(value: float | str, gender: str = "male") -> str:
64
    """
65
    Converts an integer to its ordinal as a string.
66
    
67
    Args:
68
        value: Integer, float, or string to convert
69
        gender: Gender for translations ("male" or "female")
70
    
71
    Returns:
72
        Ordinal string representation
73
    
74
    Examples:
75
        >>> ordinal(1)
76
        '1st'
77
        >>> ordinal(22)
78
        '22nd'
79
        >>> ordinal(103)
80
        '103rd'
81
    """
82
```
83

84
### Associated Press Style
85

86
Converts numbers 0-9 to Associated Press style word format, returning digits for larger numbers.
87

88
```python { .api }
89
def apnumber(value: float | str) -> str:
90
    """
91
    Converts an integer to Associated Press style.
92
    
93
    Args:
94
        value: Integer, float, or string to convert
95
    
96
    Returns:
97
        For 0-9: number spelled out; otherwise: the number as string
98
    
99
    Examples:
100
        >>> apnumber(0)
101
        'zero'
102
        >>> apnumber(5)
103
        'five'
104
        >>> apnumber(10)
105
        '10'
106
    """
107
```
108

109
### Fractional Representation
110

111
Converts decimal numbers to human-readable fractional form including proper fractions, improper fractions, and mixed numbers.
112

113
```python { .api }
114
def fractional(value: float | str) -> str:
115
    """
116
    Convert to fractional number representation.
117
    
118
    Args:
119
        value: Integer, float, or string to convert
120
    
121
    Returns:
122
        Fractional representation as string
123
    
124
    Examples:
125
        >>> fractional(0.3)
126
        '3/10'
127
        >>> fractional(1.3)
128
        '1 3/10'
129
        >>> fractional(float(1/3))
130
        '1/3'
131
    """
132
```
133

134
### Scientific Notation
135

136
Formats numbers in scientific notation with customizable precision and Unicode superscript exponents.
137

138
```python { .api }
139
def scientific(value: float | str, precision: int = 2) -> str:
140
    """
141
    Return number in scientific notation z.wq x 10ⁿ.
142
    
143
    Args:
144
        value: Input number to format
145
        precision: Number of decimal places for mantissa
146
    
147
    Returns:
148
        Number in scientific notation with Unicode superscripts
149
    
150
    Examples:
151
        >>> scientific(500)
152
        '5.00 x 10²'
153
        >>> scientific(-1000)
154
        '-1.00 x 10³'
155
        >>> scientific(1000, 1)
156
        '1.0 x 10³'
157
    """
158
```
159

160
### Clamped Formatting
161

162
Returns formatted numbers clamped between floor and ceiling values, with tokens indicating when limits are exceeded.
163

164
```python { .api }
165
def clamp(
166
    value: float,
167
    format: str = "{:}",
168
    floor: float | None = None,
169
    ceil: float | None = None,
170
    floor_token: str = "<",
171
    ceil_token: str = ">"
172
) -> str:
173
    """
174
    Returns number clamped between floor and ceil with tokens.
175
    
176
    Args:
177
        value: Input number to clamp and format
178
        format: Format string or callable function
179
        floor: Minimum value before clamping
180
        ceil: Maximum value before clamping  
181
        floor_token: Token prepended when value < floor
182
        ceil_token: Token prepended when value > ceil
183
    
184
    Returns:
185
        Formatted number with clamp tokens if needed
186
    
187
    Examples:
188
        >>> clamp(0.0001, floor=0.01)
189
        '<0.01'
190
        >>> clamp(0.999, format="{:.0%}", ceil=0.99)
191
        '>99%'
192
        >>> clamp(1, format=intword, floor=1e6, floor_token="under ")
193
        'under 1.0 million'
194
    """
195
```
196

197
### Metric Prefixes
198

199
Formats numbers with SI metric unit prefixes, automatically choosing the most appropriate scale to avoid leading or trailing zeros.
200

201
```python { .api }
202
def metric(value: float, unit: str = "", precision: int = 3) -> str:
203
    """
204
    Return a value with a metric SI unit-prefix appended.
205
    
206
    Args:
207
        value: Input number to format
208
        unit: Optional base unit (e.g., "V", "W", "F")
209
        precision: Number of significant digits
210
    
211
    Returns:
212
        Number with appropriate metric prefix
213
    
214
    Examples:
215
        >>> metric(1500, "V")
216
        '1.50 kV'
217
        >>> metric(220e-6, "F")
218
        '220 μF'
219
        >>> metric(2e8, "W")
220
        '200 MW'
221
    """
222
```
223

224
## Constants
225

226
```python { .api }
227
# Powers of 10 used for large number conversion
228
powers: list[int]
229

230
# Human-readable names for large numbers
231
human_powers: tuple[tuple[str, str], ...]
232
```
233

234
## Error Handling
235

236
All number formatting functions handle invalid inputs gracefully:
237

238
- Non-numeric strings return the original string unchanged
239
- `None` values return the string `"None"`
240
- Infinite values return `"+Inf"`, `"-Inf"`, or `"NaN"` as appropriate
241
- Mathematical edge cases are handled consistently across all functions