0
# Utility Functions
1
2
Pure Rand provides utility functions for common operations like generating multiple values at once and skipping ahead in the generator sequence. These functions follow the same pure/unsafe pattern as the rest of the library.
3
4
## Capabilities
5
6
### Multiple Value Generation
7
8
Generate arrays of random values efficiently, useful for initialization or batch processing.
9
10
#### generateN
11
12
Pure function that generates multiple values without modifying the original generator.
13
14
```typescript { .api }
15
/**
16
* Generate array of random numbers from a generator
17
* @param rng - RandomGenerator instance
18
* @param num - Number of values to generate
19
* @returns Tuple of [array of generated values, new generator]
20
*/
21
function generateN(rng: RandomGenerator, num: number): [number[], RandomGenerator];
22
```
23
24
**Usage Examples:**
25
26
```typescript
27
import { generateN, xoroshiro128plus } from 'pure-rand';
28
29
const rng = xoroshiro128plus(42);
30
31
// Generate 5 random values
32
const [values, nextRng] = generateN(rng, 5);
33
console.log(values); // [-1478741536, 1458377984, -254826496, 1967597568, -985538560]
34
35
// Original generator unchanged, can be reused
36
const [moreValues, anotherRng] = generateN(rng, 3);
37
console.log(moreValues); // Same first 3 values as above
38
39
// Continue with the new generator
40
const [finalValues, finalRng] = generateN(nextRng, 2);
41
```
42
43
#### unsafeGenerateN
44
45
Unsafe function that generates multiple values by mutating the generator for maximum performance.
46
47
```typescript { .api }
48
/**
49
* Generate array of random numbers, mutating the generator for performance
50
* @param rng - RandomGenerator instance (will be mutated)
51
* @param num - Number of values to generate
52
* @returns Array of generated values
53
*/
54
function unsafeGenerateN(rng: RandomGenerator, num: number): number[];
55
```
56
57
**Usage Examples:**
58
59
```typescript
60
import { unsafeGenerateN, xoroshiro128plus } from 'pure-rand';
61
62
const rng = xoroshiro128plus(42);
63
64
// Generate values (mutates rng)
65
const values1 = unsafeGenerateN(rng, 5);
66
const values2 = unsafeGenerateN(rng, 3); // Continues from where values1 left off
67
68
// High-performance batch generation
69
const largeArray = unsafeGenerateN(rng, 10000);
70
```
71
72
### Sequence Skipping
73
74
Skip ahead in the generator sequence without generating intermediate values, useful for parallel processing or jumping to specific positions.
75
76
#### skipN
77
78
Pure function that skips N generations and returns a new generator.
79
80
```typescript { .api }
81
/**
82
* Skip N generations in the sequence without generating values
83
* @param rng - RandomGenerator instance
84
* @param num - Number of generations to skip
85
* @returns New generator at the target position
86
*/
87
function skipN(rng: RandomGenerator, num: number): RandomGenerator;
88
```
89
90
**Usage Examples:**
91
92
```typescript
93
import { skipN, uniformIntDistribution, xoroshiro128plus } from 'pure-rand';
94
95
const rng = xoroshiro128plus(42);
96
97
// Get value at current position
98
const [value1, rng2] = uniformIntDistribution(1, 100, rng);
99
100
// Skip ahead 1000 generations
101
const skippedRng = skipN(rng, 1000);
102
const [value1000, rng1001] = uniformIntDistribution(1, 100, skippedRng);
103
104
// This is equivalent to calling next() 1000 times but much faster
105
```
106
107
#### unsafeSkipN
108
109
Unsafe function that skips N generations by mutating the generator.
110
111
```typescript { .api }
112
/**
113
* Skip N generations in place, mutating the generator for performance
114
* @param rng - RandomGenerator instance (will be mutated)
115
* @param num - Number of generations to skip
116
*/
117
function unsafeSkipN(rng: RandomGenerator, num: number): void;
118
```
119
120
**Usage Examples:**
121
122
```typescript
123
import { unsafeSkipN, unsafeUniformIntDistribution, xoroshiro128plus } from 'pure-rand';
124
125
const rng = xoroshiro128plus(42);
126
127
// Get first value
128
const value1 = unsafeUniformIntDistribution(1, 100, rng);
129
130
// Skip ahead 500 generations (mutates rng)
131
unsafeSkipN(rng, 500);
132
133
// Now rng is at position 501
134
const value501 = unsafeUniformIntDistribution(1, 100, rng);
135
```
136
137
## Common Usage Patterns
138
139
### Batch Initialization
140
141
Generate arrays of values for initialization:
142
143
```typescript
144
import { generateN, uniformIntDistribution, xoroshiro128plus } from 'pure-rand';
145
146
const rng = xoroshiro128plus(Date.now());
147
148
// Initialize array with random values
149
const [rawValues, nextRng] = generateN(rng, 100);
150
151
// Or generate distributed values
152
const diceRolls: number[] = [];
153
let currentRng = nextRng;
154
for (let i = 0; i < 50; i++) {
155
const [roll, newRng] = uniformIntDistribution(1, 6, currentRng);
156
diceRolls.push(roll);
157
currentRng = newRng;
158
}
159
160
// More efficient unsafe version
161
const unsafeRng = xoroshiro128plus(Date.now());
162
const fastDiceRolls: number[] = [];
163
for (let i = 0; i < 50; i++) {
164
fastDiceRolls.push(unsafeUniformIntDistribution(1, 6, unsafeRng));
165
}
166
```
167
168
### Parallel Processing Setup
169
170
Use skipN to create generators for different workers:
171
172
```typescript
173
import { skipN, xoroshiro128plus } from 'pure-rand';
174
175
const baseSeed = 42;
176
const itemsPerWorker = 1000;
177
178
// Create generators for 4 workers
179
const workers = [];
180
let baseRng = xoroshiro128plus(baseSeed);
181
182
for (let i = 0; i < 4; i++) {
183
workers.push({
184
id: i,
185
rng: baseRng,
186
startIndex: i * itemsPerWorker,
187
endIndex: (i + 1) * itemsPerWorker
188
});
189
190
// Skip ahead for next worker
191
baseRng = skipN(baseRng, itemsPerWorker);
192
}
193
194
// Each worker now has independent, non-overlapping sequences
195
```
196
197
### Reproducible Sampling
198
199
Skip to specific positions for reproducible sampling:
200
201
```typescript
202
import { skipN, uniformIntDistribution, xoroshiro128plus } from 'pure-rand';
203
204
const masterRng = xoroshiro128plus(12345);
205
206
// Sample at specific positions
207
const positions = [0, 100, 500, 750, 1200];
208
const samples: number[] = [];
209
210
for (const position of positions) {
211
const positionRng = skipN(masterRng, position);
212
const [sample] = uniformIntDistribution(1, 1000, positionRng);
213
samples.push(sample);
214
}
215
216
console.log(samples); // Always the same values for seed 12345
217
```
218
219
### Performance Comparison
220
221
```typescript
222
import { generateN, unsafeGenerateN, skipN, unsafeSkipN, xoroshiro128plus } from 'pure-rand';
223
224
const count = 10000;
225
226
// Pure operations (safe, creates new instances)
227
console.time('Pure generateN');
228
const rng1 = xoroshiro128plus(42);
229
const [values, newRng] = generateN(rng1, count);
230
console.timeEnd('Pure generateN');
231
232
console.time('Pure skipN');
233
const rng2 = xoroshiro128plus(42);
234
const skippedRng = skipN(rng2, count);
235
console.timeEnd('Pure skipN');
236
237
// Unsafe operations (faster, mutates in place)
238
console.time('Unsafe generateN');
239
const rng3 = xoroshiro128plus(42);
240
const unsafeValues = unsafeGenerateN(rng3, count);
241
console.timeEnd('Unsafe generateN');
242
243
console.time('Unsafe skipN');
244
const rng4 = xoroshiro128plus(42);
245
unsafeSkipN(rng4, count);
246
console.timeEnd('Unsafe skipN');
247
```
248
249
## Function Selection Guide
250
251
- **generateN**: Use when you need multiple raw values and want to preserve the original generator
252
- **unsafeGenerateN**: Use for maximum performance when you don't need the original generator
253
- **skipN**: Use to jump ahead in sequences for parallel processing or specific sampling
254
- **unsafeSkipN**: Use for high-performance sequence advancement when mutating the generator is acceptable
255
256
All utility functions work with any generator type and complement the distribution functions for comprehensive random number generation workflows.