0
# Vectors & Arrays
1

2
Memory-efficient resizable arrays with typed backing storage and bit-packed boolean arrays for space optimization.
3

4
## Capabilities
5

6
### Vector
7

8
Dynamic resizable array with typed backing storage and configurable growth policies.
9

10
```typescript { .api }
11
/**
12
 * Dynamic vector with typed array backing storage
13
 * @param ArrayClass Constructor for the backing array type
14
 * @param initialCapacityOrOptions Initial capacity or configuration options
15
 */
16
function Vector(
17
  ArrayClass: ArrayConstructor,
18
  initialCapacityOrOptions?: number | VectorOptions
19
): Vector;
20

21
interface VectorOptions {
22
  /** Initial number of elements (default: 0) */
23
  initialLength?: number;
24
  /** Initial allocated capacity (default: computed from initialLength) */
25
  initialCapacity?: number;
26
  /** Custom growth policy function (default: 1.5x growth) */
27
  policy?: (capacity: number) => number;
28
  /** Whether to create a factory function (default: false) */
29
  factory?: boolean;
30
}
31

32
interface Vector {
33
  /** Current number of elements */
34
  readonly length: number;
35
  /** Current allocated capacity */
36
  readonly capacity: number;
37
  /** Alias for length */
38
  readonly size: number;
39
  
40
  /** Set value at index, returns this for chaining */
41
  set(index: number, value: number): this;
42
  
43
  /** Get value at index, returns undefined if out of bounds */
44
  get(index: number): number | undefined;
45
  
46
  /** Add value to end, returns new length */
47
  push(value: number): number;
48
  
49
  /** Remove and return last value */
50
  pop(): number | undefined;
51
  
52
  /** Change allocated capacity to exact size */
53
  reallocate(capacity: number): this;
54
  
55
  /** Grow capacity to at least the specified size */
56
  grow(capacity?: number): this;
57
  
58
  /** Change length, growing or shrinking as needed */
59
  resize(length: number): this;
60
  
61
  /** Apply growth policy, returns new capacity */
62
  applyPolicy(override?: number): number;
63
  
64
  /** Iterate over values */
65
  values(): IterableIterator<number>;
66
  
67
  /** Iterate over [index, value] pairs */
68
  entries(): IterableIterator<[number, number]>;
69
  
70
  /** Default iterator (same as values) */
71
  [Symbol.iterator](): IterableIterator<number>;
72
  
73
  /** Execute callback for each element */
74
  forEach(callback: (value: number, index: number, vector: this) => void, scope?: any): void;
75
  
76
  /** Debug representation */
77
  inspect(): any;
78
}
79
```
80

81
**Usage Examples:**
82

83
```typescript
84
import {Vector} from "mnemonist";
85

86
// Create vector with Float32Array backing
87
const vector = new Vector(Float32Array, 10);
88
vector.push(1.5, 2.7, 3.14);
89
console.log(vector.get(0)); // 1.5
90
console.log(vector.length); // 3
91

92
// With custom growth policy
93
const customVector = new Vector(Int32Array, {
94
  initialCapacity: 8,
95
  policy: (capacity) => capacity * 2 // Double on growth
96
});
97

98
// Iteration
99
for (const value of vector) {
100
  console.log(value);
101
}
102

103
vector.forEach((value, index) => {
104
  console.log(`${index}: ${value}`);
105
});
106
```
107

108
### Vector Static Methods
109

110
Factory methods for creating vectors from existing data.
111

112
```typescript { .api }
113
/**
114
 * Create vector from iterable data
115
 */
116
function from<T>(
117
  iterable: Iterable<T>,
118
  ArrayClass: ArrayConstructor,
119
  capacity?: number
120
): Vector;
121
```
122

123
**Usage Examples:**
124

125
```typescript
126
import {Vector} from "mnemonist";
127

128
// From array
129
const vector = Vector.from([1, 2, 3], Float32Array);
130

131
// From other iterables
132
const fromSet = Vector.from(new Set([4, 5, 6]), Int32Array);
133
const fromMap = Vector.from(new Map().values(), Uint16Array);
134
```
135

136
### Typed Vector Variants
137

138
Pre-configured vector classes for each typed array type.
139

140
```typescript { .api }
141
/**
142
 * Pre-configured typed vector variants
143
 */
144
function Int8Vector(initialCapacityOrOptions?: number | VectorOptions): Int8Vector;
145
function Uint8Vector(initialCapacityOrOptions?: number | VectorOptions): Uint8Vector;
146
function Uint8ClampedVector(initialCapacityOrOptions?: number | VectorOptions): Uint8ClampedVector;
147
function Int16Vector(initialCapacityOrOptions?: number | VectorOptions): Int16Vector;
148
function Uint16Vector(initialCapacityOrOptions?: number | VectorOptions): Uint16Vector;
149
function Int32Vector(initialCapacityOrOptions?: number | VectorOptions): Int32Vector;
150
function Uint32Vector(initialCapacityOrOptions?: number | VectorOptions): Uint32Vector;
151
function Float32Vector(initialCapacityOrOptions?: number | VectorOptions): Float32Vector;
152
function Float64Vector(initialCapacityOrOptions?: number | VectorOptions): Float64Vector;
153
function PointerVector(initialCapacityOrOptions?: number | VectorOptions): PointerVector;
154
```
155

156
**Usage Examples:**
157

158
```typescript
159
import {
160
  Int8Vector, Uint32Vector, Float32Vector, PointerVector
161
} from "mnemonist";
162

163
// Signed 8-bit integers (-128 to 127)
164
const bytes = new Int8Vector();
165
bytes.push(-50, 0, 127);
166

167
// Unsigned 32-bit integers (0 to 4,294,967,295)
168
const indices = new Uint32Vector();
169
indices.push(1000000, 2000000);
170

171
// 32-bit floats
172
const coordinates = new Float32Vector();
173
coordinates.push(1.5, -2.7, 3.14159);
174

175
// Automatically sized pointers (Uint16Array, Uint32Array, or Float64Array)
176
const pointers = new PointerVector();
177
```
178

179
**Typed Vector Static Methods:**
180

181
```typescript { .api }
182
// Each typed vector has its own from method
183
Int8Vector.from(iterable: Iterable<number>, capacity?: number): Int8Vector;
184
Uint32Vector.from(iterable: Iterable<number>, capacity?: number): Uint32Vector;
185
Float32Vector.from(iterable: Iterable<number>, capacity?: number): Float32Vector;
186
// ... same pattern for all typed variants
187
```
188

189
### BitVector
190

191
Dynamic bit array storing boolean values efficiently with 32 bits per 32-bit word.
192

193
```typescript { .api }
194
/**
195
 * Dynamic bit vector with efficient boolean storage
196
 * @param initialLengthOrOptions Initial length or configuration options
197
 */
198
function BitVector(initialLengthOrOptions?: number | BitVectorOptions): BitVector;
199

200
interface BitVectorOptions {
201
  /** Initial number of bits (default: 0) */
202
  initialLength?: number;
203
  /** Initial allocated capacity in bits (default: computed from initialLength) */
204
  initialCapacity?: number;
205
  /** Custom growth policy function (default: 1.5x growth) */
206
  policy?: (capacity: number) => number;
207
}
208

209
interface BitVector {
210
  /** Current number of bits */
211
  readonly length: number;
212
  /** Current allocated capacity in bits (always multiple of 32) */
213
  readonly capacity: number;
214
  /** Number of bits set to 1 */
215
  readonly size: number;
216
  
217
  /** Set bit at index to value (1 or 0), returns this for chaining */
218
  set(index: number, value?: boolean | number): this;
219
  
220
  /** Set bit at index to 0, returns this for chaining */
221
  reset(index: number): this;
222
  
223
  /** Toggle bit at index, returns this for chaining */
224
  flip(index: number): this;
225
  
226
  /** Get bit value at index as number (0 or 1) */
227
  get(index: number): number;
228
  
229
  /** Get bit value at index as boolean */
230
  test(index: number): boolean;
231
  
232
  /** Add bit to end, returns new length */
233
  push(value: boolean | number): number;
234
  
235
  /** Remove and return last bit */
236
  pop(): number | undefined;
237
  
238
  /** Count of 1s from start to position i (exclusive) */
239
  rank(i: number): number;
240
  
241
  /** Position of rth 1-bit, or -1 if not found */
242
  select(r: number): number;
243
  
244
  /** Change allocated capacity */
245
  reallocate(capacity: number): this;
246
  
247
  /** Grow capacity to at least the specified size */
248
  grow(capacity?: number): this;
249
  
250
  /** Change length, growing or shrinking as needed */
251
  resize(length: number): this;
252
  
253
  /** Apply growth policy */
254
  applyPolicy(override?: number): number;
255
  
256
  /** Iterate over bit values (0 or 1) */
257
  values(): IterableIterator<number>;
258
  
259
  /** Iterate over [index, bit] pairs */
260
  entries(): IterableIterator<[number, number]>;
261
  
262
  /** Default iterator (same as values) */
263
  [Symbol.iterator](): IterableIterator<number>;
264
  
265
  /** Execute callback for each bit */
266
  forEach(callback: (bit: number, index: number) => void, scope?: any): void;
267
  
268
  /** Debug representation */
269
  inspect(): any;
270
  
271
  /** Return underlying Uint32Array as regular array */
272
  toJSON(): Array<number>;
273
}
274
```
275

276
**Usage Examples:**
277

278
```typescript
279
import {BitVector} from "mnemonist";
280

281
// Create dynamic bit vector
282
const bits = new BitVector();
283
bits.push(true, false, true, true); // Add bits
284
console.log(bits.length); // 4
285
console.log(bits.size);   // 3 (three 1-bits)
286

287
// Set individual bits
288
bits.set(10, 1); // Set bit 10 to 1
289
bits.reset(2);   // Set bit 2 to 0
290
bits.flip(1);    // Toggle bit 1
291

292
// Query bits
293
console.log(bits.test(10)); // true
294
console.log(bits.get(2));   // 0
295

296
// Rank and select operations
297
console.log(bits.rank(5));  // Count of 1s before position 5
298
console.log(bits.select(2)); // Position of 2nd 1-bit
299

300
// Iteration
301
for (const bit of bits) {
302
  console.log(bit); // 0 or 1
303
}
304
```
305

306
### BitSet
307

308
Fixed-size bit array optimized for known-size boolean collections.
309

310
```typescript { .api }
311
/**
312
 * Fixed-size bit set with efficient boolean storage
313
 * @param length Fixed number of bits in the set
314
 */
315
function BitSet(length: number): BitSet;
316

317
interface BitSet {
318
  /** Fixed number of bits in the set */
319
  readonly length: number;
320
  /** Number of bits currently set to 1 */
321
  readonly size: number;
322
  
323
  /** Set bit at index to value (1 or 0), returns this for chaining */
324
  set(index: number, value?: boolean | number): void;
325
  
326
  /** Set bit at index to specified value */
327
  reset(index: number, value: boolean | number): void;
328
  
329
  /** Toggle bit at index */
330
  flip(index: number, value: boolean | number): void;
331
  
332
  /** Get bit value at index as number (0 or 1) */
333
  get(index: number): number;
334
  
335
  /** Get bit value at index as boolean */
336
  test(index: number): boolean;
337
  
338
  /** Reset all bits to 0 and size to 0 */
339
  clear(): void;
340
  
341
  /** Count of 1s from start to position i (exclusive) */
342
  rank(i: number): number;
343
  
344
  /** Position of rth 1-bit, or -1 if not found */
345
  select(r: number): number;
346
  
347
  /** Iterate over bit values (0 or 1) */
348
  values(): IterableIterator<number>;
349
  
350
  /** Iterate over [index, bit] pairs */
351
  entries(): IterableIterator<[number, number]>;
352
  
353
  /** Default iterator (same as values) */
354
  [Symbol.iterator](): IterableIterator<number>;
355
  
356
  /** Execute callback for each bit */
357
  forEach(callback: (bit: number, index: number) => void, scope?: any): void;
358
  
359
  /** Debug representation */
360
  inspect(): any;
361
  
362
  /** Return underlying Uint32Array as regular array */
363
  toJSON(): Array<number>;
364
}
365
```
366

367
**Usage Examples:**
368

369
```typescript
370
import {BitSet} from "mnemonist";
371

372
// Create fixed-size bit set
373
const flags = new BitSet(64); // 64 bits
374
flags.set(0, 1);
375
flags.set(63, 1);
376
console.log(flags.size); // 2
377

378
// Bulk operations
379
flags.clear(); // All bits to 0
380
console.log(flags.size); // 0
381

382
// Set multiple bits
383
[5, 10, 15, 20].forEach(i => flags.set(i, 1));
384

385
// Use as boolean array
386
const hasFeature = (feature: number) => flags.test(feature);
387
console.log(hasFeature(10)); // true
388
console.log(hasFeature(11)); // false
389

390
// Find positions of set bits
391
let position = -1;
392
let count = 0;
393
while ((position = flags.select(++count)) !== -1) {
394
  console.log(`Bit ${position} is set`);
395
}
396
```
397

398
## Types
399

400
```typescript { .api }
401
/**
402
 * Array constructor types supported by Vector
403
 */
404
type ArrayConstructor = 
405
  | Int8ArrayConstructor
406
  | Uint8ArrayConstructor
407
  | Uint8ClampedArrayConstructor
408
  | Int16ArrayConstructor
409
  | Uint16ArrayConstructor
410
  | Int32ArrayConstructor
411
  | Uint32ArrayConstructor
412
  | Float32ArrayConstructor
413
  | Float64ArrayConstructor;
414

415
/**
416
 * Growth policy function type
417
 * Takes current capacity, returns new capacity
418
 */
419
type GrowthPolicy = (capacity: number) => number;
420

421
/**
422
 * Vector configuration options
423
 */
424
interface VectorOptions {
425
  initialLength?: number;
426
  initialCapacity?: number;
427
  policy?: GrowthPolicy;
428
  factory?: boolean;
429
}
430

431
/**
432
 * BitVector configuration options
433
 */
434
interface BitVectorOptions {
435
  initialLength?: number;
436
  initialCapacity?: number; 
437
  policy?: GrowthPolicy;
438
}
439
```
440

441
## Performance Characteristics
442

443
| Operation | Vector | BitVector | BitSet |
444
|-----------|--------|-----------|---------|
445
| Get/Set | O(1) | O(1) | O(1) |
446
| Push | O(1) amortized | O(1) amortized | N/A |
447
| Pop | O(1) | O(1) | N/A |
448
| Rank | N/A | O(n) | O(n) |
449
| Select | N/A | O(n) | O(n) |
450
| Memory per item | 1-8 bytes | 1/32 bytes | 1/32 bytes |
451
| Growth | Dynamic | Dynamic | Fixed |
452
453
## Memory Efficiency
454

455
- **Vector**: Uses typed arrays directly, 1-8 bytes per element depending on type
456
- **BitVector**: Packs 32 bits per 32-bit word, ~0.03 bytes per boolean
457
- **BitSet**: Same as BitVector but fixed size, slightly less overhead
458
- **PointerVector**: Automatically selects optimal array size based on capacity needs
459

460
## Choosing the Right Array Type
461

462
- **Vector**: For numeric data with specific precision requirements
463
- **Typed Vectors**: When you know the exact numeric type needed
464
- **BitVector**: For dynamic boolean arrays or flags
465
- **BitSet**: For fixed-size boolean arrays when memory is critical
466
- **PointerVector**: For indices or pointers where size depends on data scale