0
# Distribution Functions
1

2
Pure Rand provides uniform distribution functions that ensure equal probability across value ranges. These functions convert the raw output from generators into useful ranges for integers, bigints, and arbitrary precision numbers.
3

4
## Capabilities
5

6
### Integer Distributions
7

8
Generate uniform random integers within specified ranges using standard JavaScript numbers.
9

10
#### uniformIntDistribution
11

12
Pure function that returns a distribution function or immediately generates a value with a new generator.
13

14
```typescript { .api }
15
/**
16
 * Generate uniform random integers between from and to (inclusive)
17
 * @param from - Minimum value (inclusive)
18
 * @param to - Maximum value (inclusive)
19
 * @returns Distribution function for deferred execution
20
 */
21
function uniformIntDistribution(from: number, to: number): Distribution<number>;
22

23
/**
24
 * Generate uniform random integers between from and to (inclusive) immediately
25
 * @param from - Minimum value (inclusive)
26
 * @param to - Maximum value (inclusive)
27
 * @param rng - RandomGenerator instance
28
 * @returns Tuple of [generated value, new generator]
29
 */
30
function uniformIntDistribution(from: number, to: number, rng: RandomGenerator): [number, RandomGenerator];
31
```
32

33
**Usage Examples:**
34

35
```typescript
36
import { uniformIntDistribution, xoroshiro128plus } from 'pure-rand';
37

38
const rng = xoroshiro128plus(42);
39

40
// Deferred execution pattern
41
const diceRoll = uniformIntDistribution(1, 6);
42
const [value1, rng2] = diceRoll(rng);
43
const [value2, rng3] = diceRoll(rng2);
44

45
// Immediate execution pattern
46
const [directValue, nextRng] = uniformIntDistribution(1, 100, rng);
47

48
// Range examples
49
const [coinFlip, rng4] = uniformIntDistribution(0, 1, rng3); // 0 or 1
50
const [percentage, rng5] = uniformIntDistribution(0, 100, rng4); // 0 to 100
51
const [negativeRange, rng6] = uniformIntDistribution(-10, 10, rng5); // -10 to 10
52
```
53

54
#### unsafeUniformIntDistribution
55

56
Unsafe function that mutates the generator for maximum performance.
57

58
```typescript { .api }
59
/**
60
 * Generate uniform random integers, mutating the generator for performance
61
 * @param from - Minimum value (inclusive)
62
 * @param to - Maximum value (inclusive)
63
 * @param rng - RandomGenerator instance (will be mutated)
64
 * @returns Generated random integer
65
 */
66
function unsafeUniformIntDistribution(from: number, to: number, rng: RandomGenerator): number;
67
```
68

69
**Usage Examples:**
70

71
```typescript
72
import { unsafeUniformIntDistribution, xoroshiro128plus } from 'pure-rand';
73

74
const rng = xoroshiro128plus(42);
75

76
// Multiple values with same generator (mutates rng)
77
const dice1 = unsafeUniformIntDistribution(1, 6, rng);
78
const dice2 = unsafeUniformIntDistribution(1, 6, rng);
79
const dice3 = unsafeUniformIntDistribution(1, 6, rng);
80

81
// High-performance usage
82
const results: number[] = [];
83
for (let i = 0; i < 1000; i++) {
84
  results.push(unsafeUniformIntDistribution(1, 1000, rng));
85
}
86
```
87

88
### BigInt Distributions
89

90
Generate uniform random BigInt values for arbitrary precision integers beyond JavaScript's safe integer range.
91

92
#### uniformBigIntDistribution
93

94
Pure function for BigInt value generation.
95

96
```typescript { .api }
97
/**
98
 * Generate uniform random bigints between from and to (inclusive)
99
 * @param from - Minimum bigint value (inclusive)
100
 * @param to - Maximum bigint value (inclusive)
101
 * @returns Distribution function for deferred execution
102
 */
103
function uniformBigIntDistribution(from: bigint, to: bigint): Distribution<bigint>;
104

105
/**
106
 * Generate uniform random bigints between from and to (inclusive) immediately
107
 * @param from - Minimum bigint value (inclusive)
108
 * @param to - Maximum bigint value (inclusive)
109
 * @param rng - RandomGenerator instance
110
 * @returns Tuple of [generated bigint, new generator]
111
 */
112
function uniformBigIntDistribution(from: bigint, to: bigint, rng: RandomGenerator): [bigint, RandomGenerator];
113
```
114

115
**Usage Examples:**
116

117
```typescript
118
import { uniformBigIntDistribution, xoroshiro128plus } from 'pure-rand';
119

120
const rng = xoroshiro128plus(42);
121

122
// Large number ranges
123
const [largeInt, rng2] = uniformBigIntDistribution(
124
  BigInt("123456789012345678901234567890"),
125
  BigInt("999999999999999999999999999999"),
126
  rng
127
);
128

129
// Deferred pattern with BigInt
130
const bigIntGen = uniformBigIntDistribution(0n, 1000000n);
131
const [value, nextRng] = bigIntGen(rng2);
132
```
133

134
#### unsafeUniformBigIntDistribution
135

136
Unsafe function for high-performance BigInt generation.
137

138
```typescript { .api }
139
/**
140
 * Generate uniform random bigints, mutating the generator for performance
141
 * @param from - Minimum bigint value (inclusive)
142
 * @param to - Maximum bigint value (inclusive)
143
 * @param rng - RandomGenerator instance (will be mutated)
144
 * @returns Generated random bigint
145
 */
146
function unsafeUniformBigIntDistribution(from: bigint, to: bigint, rng: RandomGenerator): bigint;
147
```
148

149
### Array Integer Distributions
150

151
Generate uniform random values using arbitrary precision integers represented as arrays. Useful for cryptographic applications or when working with extremely large numbers.
152

153
#### ArrayInt Type
154

155
```typescript { .api }
156
type ArrayInt = {
157
  /** Sign of the represented number */
158
  sign: -1 | 1;
159
  /** Value of the number, must only contain numbers in the range [0, 0xffffffff] */
160
  data: number[];
161
};
162
```
163

164
The ArrayInt type represents integers larger than what can be represented in standard JavaScript numbers. Examples:
165
- `{ sign: 1, data: [42] }` represents 42
166
- `{ sign: -1, data: [42] }` represents -42  
167
- `{ sign: -1, data: [5, 42] }` represents -1 * (5 * 2^32 + 42)
168

169
**ArrayInt Construction Examples:**
170

171
```typescript
172
import { uniformArrayIntDistribution, xoroshiro128plus } from 'pure-rand';
173

174
// ArrayInt type is used for arbitrary precision integers
175
type ArrayInt = {
176
  sign: -1 | 1;
177
  data: number[];
178
};
179

180
const rng = xoroshiro128plus(42);
181

182
// Simple positive number
183
const smallPositive: ArrayInt = { sign: 1, data: [123] };
184

185
// Simple negative number  
186
const smallNegative: ArrayInt = { sign: -1, data: [456] };
187

188
// Large positive number (larger than 2^32)
189
const largePositive: ArrayInt = { sign: 1, data: [1, 2147483647] }; // 1 * 2^32 + 2147483647
190

191
// Very large number using multiple components
192
const veryLarge: ArrayInt = { 
193
  sign: 1, 
194
  data: [0x12345678, 0x9abcdef0, 0x11111111] 
195
}; // Multi-precision representation
196

197
// Generate random ArrayInt values
198
const [randomArrayInt, nextRng] = uniformArrayIntDistribution(
199
  smallPositive,
200
  largePositive,
201
  rng
202
);
203
```
204

205
#### uniformArrayIntDistribution
206

207
Pure function for arbitrary precision integer generation.
208

209
```typescript { .api }
210
/**
211
 * Generate uniform random ArrayInt values for arbitrary precision integers
212
 * @param from - Minimum ArrayInt value (inclusive)
213
 * @param to - Maximum ArrayInt value (inclusive)
214
 * @returns Distribution function for deferred execution
215
 */
216
function uniformArrayIntDistribution(from: ArrayInt, to: ArrayInt): Distribution<ArrayInt>;
217

218
/**
219
 * Generate uniform random ArrayInt values immediately
220
 * @param from - Minimum ArrayInt value (inclusive)
221
 * @param to - Maximum ArrayInt value (inclusive)
222
 * @param rng - RandomGenerator instance
223
 * @returns Tuple of [generated ArrayInt, new generator]
224
 */
225
function uniformArrayIntDistribution(from: ArrayInt, to: ArrayInt, rng: RandomGenerator): [ArrayInt, RandomGenerator];
226
```
227

228
#### unsafeUniformArrayIntDistribution
229

230
Unsafe function for high-performance arbitrary precision generation.
231

232
```typescript { .api }
233
/**
234
 * Generate uniform random ArrayInt values, mutating the generator for performance
235
 * @param from - Minimum ArrayInt value (inclusive)
236
 * @param to - Maximum ArrayInt value (inclusive)
237
 * @param rng - RandomGenerator instance (will be mutated)
238
 * @returns Generated random ArrayInt
239
 */
240
function unsafeUniformArrayIntDistribution(from: ArrayInt, to: ArrayInt, rng: RandomGenerator): ArrayInt;
241
```
242

243
## Distribution Patterns
244

245
### Deferred Execution
246

247
Create a distribution function once and reuse it multiple times:
248

249
```typescript
250
import { uniformIntDistribution, xoroshiro128plus } from 'pure-rand';
251

252
const rng = xoroshiro128plus(42);
253
const diceRoll = uniformIntDistribution(1, 6);
254

255
// Reuse the same distribution
256
const [roll1, rng2] = diceRoll(rng);
257
const [roll2, rng3] = diceRoll(rng2);
258
const [roll3, rng4] = diceRoll(rng3);
259
```
260

261
### Immediate Execution
262

263
Generate values directly when you don't need to reuse the distribution:
264

265
```typescript
266
import { uniformIntDistribution, xoroshiro128plus } from 'pure-rand';
267

268
const rng = xoroshiro128plus(42);
269

270
const [roll1, rng2] = uniformIntDistribution(1, 6, rng);
271
const [roll2, rng3] = uniformIntDistribution(1, 6, rng2);
272
const [roll3, rng4] = uniformIntDistribution(1, 6, rng3);
273
```
274

275
### Performance Optimization with Unsafe Functions
276

277
When maximum performance is needed and you don't require immutability:
278

279
```typescript
280
import { unsafeUniformIntDistribution, xoroshiro128plus } from 'pure-rand';
281

282
const rng = xoroshiro128plus(42);
283

284
// High-performance generation (mutates rng)
285
const results: number[] = [];
286
for (let i = 0; i < 10000; i++) {
287
  results.push(unsafeUniformIntDistribution(0, 100, rng));
288
}
289
```
290

291
## Range Considerations
292

293
- **Inclusive bounds**: All distribution functions include both `from` and `to` values in the possible outcomes
294
- **Order independence**: `uniformIntDistribution(10, 1, rng)` works the same as `uniformIntDistribution(1, 10, rng)`
295
- **Single value**: When `from === to`, the function always returns that value
296
- **Type safety**: BigInt distributions require BigInt parameters, regular int distributions use numbers
297

298
## Performance Notes
299

300
- **Pure functions**: Create new generator instances, safe for concurrent use
301
- **Unsafe functions**: Modify generators in-place, highest performance but not thread-safe
302
- **Deferred patterns**: Slight overhead for function creation but enable reusable distributions
303
- **Immediate patterns**: Most direct approach when distribution is used only once