0
# Cardinal Pluralization
1

2
Cardinal-only pluralization functions optimized for when ordinal pluralization is not needed. These functions are more memory-efficient as they don't include ordinal logic.
3

4
## Capabilities
5

6
### Cardinal Functions
7

8
All 217 language functions support cardinal pluralization only, without the ordinal parameter.
9

10
```typescript { .api }
11
/**
12
 * Determines the cardinal plural category for a number
13
 * @param n - The number to pluralize (number or string)
14
 * @returns The appropriate cardinal plural category
15
 */
16
(n: number | string) => PluralCategory;
17

18
type PluralCategory = "zero" | "one" | "two" | "few" | "many" | "other";
19
```
20

21
### Import Pattern
22

23
```javascript { .api }
24
import { en, fr, ar, pl } from "make-plural/cardinals";
25
```
26

27
### Language Functions
28

29
All 217 languages are available with the same coverage as the main plurals module, but only for cardinal numbers:
30

31
**Examples by Complexity:**
32

33
**Simple Two-Category Languages:**
34
- `en` - English: Returns `"one" | "other"`
35
- `de` - German: Returns `"one" | "other"`
36
- `nl` - Dutch: Returns `"one" | "other"`
37
- `sv` - Swedish: Returns `"one" | "other"`
38

39
**Three-Category Languages:**
40
- `fr` - French: Returns `"one" | "many" | "other"`
41
- `pt` - Portuguese: Returns `"one" | "many" | "other"`
42
- `es` - Spanish: Returns `"one" | "many" | "other"`
43

44
**Four-Category Languages:**
45
- `pl` - Polish: Returns `"one" | "few" | "many" | "other"`
46
- `ru` - Russian: Returns `"one" | "few" | "many" | "other"`
47
- `uk` - Ukrainian: Returns `"one" | "few" | "many" | "other"`
48

49
**Complex Six-Category Languages:**
50
- `ar` - Arabic: Returns `"zero" | "one" | "two" | "few" | "many" | "other"`
51
- `cy` - Welsh: Returns `"zero" | "one" | "two" | "few" | "many" | "other"`
52

53
**Single-Category Languages:**
54
- `zh` - Chinese: Returns `"other"`
55
- `ja` - Japanese: Returns `"other"`
56
- `ko` - Korean: Returns `"other"`
57
- `vi` - Vietnamese: Returns `"other"`
58

59
### Usage Examples
60

61
**Basic Cardinal Usage:**
62
```javascript
63
import { en, fr, ar, pl } from "make-plural/cardinals";
64

65
// English - simple binary system
66
en(0);   // 'other'
67
en(1);   // 'one'
68
en(2);   // 'other'
69
en(100); // 'other'
70

71
// French - 0 and 1 are singular, 2+ is plural
72
fr(0);   // 'one'
73
fr(1);   // 'one'  
74
fr(2);   // 'many'
75
fr(100); // 'many'
76

77
// Arabic - complex 6-category system
78
ar(0);   // 'zero'
79
ar(1);   // 'one'
80
ar(2);   // 'two'
81
ar(3);   // 'few'    (3-10)
82
ar(11);  // 'many'   (11-99)
83
ar(100); // 'other'  (100, 200, 300...)
84
ar(101); // 'few'    (101-110)
85
```
86

87
**Decimal Number Support:**
88
```javascript
89
import { en, ar, fr } from "make-plural/cardinals";
90

91
// English treats all decimals as 'other'
92
en(1.0);   // 'one'
93
en(1.5);   // 'other'
94
en(2.0);   // 'other'
95

96
// French decimal handling
97
fr(0.5);   // 'one'    (0 ≤ n < 2)
98
fr(1.9);   // 'one'
99
fr(2.0);   // 'many'
100

101
// Arabic decimal handling
102
ar(0.5);   // 'other'
103
ar(1.0);   // 'one'
104
ar(1.5);   // 'other'
105
```
106

107
**String Input Support:**
108
```javascript
109
import { pl, ru } from "make-plural/cardinals";
110

111
// Polish with string numbers
112
pl("1");     // 'one'
113
pl("2");     // 'few'
114
pl("5");     // 'many'
115

116
// Russian with string numbers  
117
ru("1");     // 'one'    (1, 21, 31...)
118
ru("2");     // 'few'    (2-4, 22-24...)
119
ru("5");     // 'many'   (0, 5-20, 25-30...)
120
```
121

122
### Language-Specific Rules
123

124
**Arabic (`ar`) Rules:**
125
- `zero`: n = 0
126
- `one`: n = 1  
127
- `two`: n = 2
128
- `few`: n % 100 in 3-10
129
- `many`: n % 100 in 11-99
130
- `other`: everything else
131

132
**Polish (`pl`) Rules:**
133
- `one`: n = 1
134
- `few`: n % 10 in 2-4 && n % 100 not in 12-14
135
- `many`: n % 10 = 0 || n % 10 in 5-9 || n % 100 in 11-14
136
- `other`: everything else (decimals)
137

138
**French (`fr`) Rules:**
139
- `one`: 0 ≤ n < 2
140
- `many`: n ≥ 2
141
- `other`: not an integer
142

143
**Russian (`ru`) Rules:**
144
- `one`: n % 10 = 1 && n % 100 ≠ 11
145
- `few`: n % 10 in 2-4 && n % 100 not in 12-14  
146
- `many`: n % 10 = 0 || n % 10 in 5-9 || n % 100 in 11-14
147
- `other`: not an integer
148

149
### Memory Efficiency
150

151
Cardinal-only functions are more memory-efficient than the combined plurals functions:
152

153
```javascript
154
// More memory efficient for cardinal-only use
155
import { en, fr } from "make-plural/cardinals";
156

157
// Less efficient if you only need cardinals
158
import { en, fr } from "make-plural";
159
```
160

161
### When to Use Cardinals
162

163
Use cardinal-only functions when:
164

165
1. **Memory constraints**: Working in memory-constrained environments
166
2. **Bundle size**: Need to minimize JavaScript bundle size
167
3. **Cardinal-only**: Your application only deals with cardinal numbers (counts, quantities)
168
4. **Performance**: Need maximum performance for cardinal pluralization
169

170
Avoid when:
171

172
1. **Mixed usage**: You need both cardinal and ordinal pluralization
173
2. **Future flexibility**: You might need ordinals later
174
3. **Code simplicity**: Using one import pattern is preferred