0
# Array Operations
1

2
Array manipulation utilities for random slicing and efficient element removal operations, optimized for performance in data processing and collection management.
3

4
## Capabilities
5

6
### Random Array Slicing
7

8
Extract random elements from an array with specified count, using circular iteration for consistent behavior.
9

10
```typescript { .api }
11
/**
12
 * Array random slice with items count
13
 * @param arr - Source array to slice from
14
 * @param num - Number of items to extract (optional, defaults to entire array)
15
 * @returns New array with randomly selected items
16
 */
17
function randomSlice<T = any>(arr: T[], num?: number): T[];
18
```
19

20
**Usage Examples:**
21

22
```typescript
23
import { randomSlice } from "utility";
24

25
// Random subset of array
26
const colors = ['red', 'blue', 'green', 'yellow', 'purple', 'orange'];
27
const randomColors = randomSlice(colors, 3);
28
// Result: 3 random colors, e.g., ['green', 'red', 'purple']
29

30
// All elements (copy array)
31
const allColors = randomSlice(colors);
32
// Result: copy of entire array
33

34
// More items than array length (returns copy)
35
const moreItems = randomSlice(['a', 'b'], 5);
36
// Result: ['a', 'b'] (returns copy when num >= length)
37

38
// Random sampling from large dataset
39
const dataset = Array.from({ length: 1000 }, (_, i) => i);
40
const sample = randomSlice(dataset, 10);
41
// Result: 10 random numbers from 0-999
42

43
// Empty array handling
44
const empty = randomSlice([], 5);
45
// Result: [] (empty array)
46

47
// Random user selection
48
const users = [
49
  { id: 1, name: 'Alice' },
50
  { id: 2, name: 'Bob' },
51
  { id: 3, name: 'Charlie' },
52
  { id: 4, name: 'Diana' }
53
];
54
const randomUsers = randomSlice(users, 2);
55
// Result: 2 random user objects
56
```
57

58
### Efficient Element Removal
59

60
Remove single element from array by index with optimized performance (faster than splice).
61

62
```typescript { .api }
63
/**
64
 * Remove one element from an array efficiently
65
 * @param arr - Input array to modify
66
 * @param index - Element index to remove (supports negative indices)
67
 * @returns Modified array (same reference)
68
 */
69
function spliceOne<T = any>(arr: T[], index: number): T[];
70
```
71

72
**Usage Examples:**
73

74
```typescript
75
import { spliceOne } from "utility";
76

77
// Basic element removal
78
const numbers = [1, 2, 3, 4, 5];
79
spliceOne(numbers, 2); // Remove element at index 2
80
console.log(numbers); // [1, 2, 4, 5]
81

82
// Negative index (from end)
83
const letters = ['a', 'b', 'c', 'd'];
84
spliceOne(letters, -1); // Remove last element
85
console.log(letters); // ['a', 'b', 'c']
86

87
// Out of bounds index (no change)
88
const items = ['x', 'y', 'z'];
89
spliceOne(items, 10); // Index too large
90
console.log(items); // ['x', 'y', 'z'] (unchanged)
91

92
spliceOne(items, -10); // Index too negative
93
console.log(items); // ['x', 'y', 'z'] (unchanged)
94

95
// Performance-critical removal
96
function removeUser(users: User[], userId: number) {
97
  const index = users.findIndex(user => user.id === userId);
98
  if (index !== -1) {
99
    spliceOne(users, index); // Faster than users.splice(index, 1)
100
  }
101
  return users;
102
}
103

104
// Batch removals (remove from end to maintain indices)
105
function removeBatch(arr: any[], indices: number[]) {
106
  // Sort indices in descending order to maintain correct positions
107
  const sortedIndices = indices.sort((a, b) => b - a);
108
  
109
  for (const index of sortedIndices) {
110
    spliceOne(arr, index);
111
  }
112
  
113
  return arr;
114
}
115

116
// Event handler cleanup
117
const handlers = [handler1, handler2, handler3, handler4];
118
const indexToRemove = handlers.indexOf(handler2);
119
if (indexToRemove !== -1) {
120
  spliceOne(handlers, indexToRemove);
121
}
122
```