0
# Array Operations
1

2
Core array manipulation functions for Uint8Arrays including concatenation, comparison, and equality testing. These operations are optimized for performance with Node.js Buffer support when available.
3

4
## Capabilities
5

6
### Array Concatenation
7

8
Efficiently concatenates multiple Uint8Arrays into a single array. Optimizes performance when total length is known.
9

10
```typescript { .api }
11
/**
12
 * Returns a new Uint8Array created by concatenating the passed Uint8Arrays
13
 * @param arrays - Array of Uint8Arrays to concatenate
14
 * @param length - Optional total length hint for optimization
15
 * @returns New Uint8Array containing concatenated data
16
 */
17
function concat(arrays: Uint8Array[], length?: number): Uint8Array;
18
```
19

20
**Usage Examples:**
21

22
```typescript
23
import { concat } from "uint8arrays/concat";
24
import { fromString } from "uint8arrays/from-string";
25
import { toString } from "uint8arrays/to-string";
26

27
// Basic concatenation
28
const part1 = fromString("Hello");
29
const part2 = fromString(" ");
30
const part3 = fromString("World");
31

32
const combined = concat([part1, part2, part3]);
33
console.log(toString(combined)); // "Hello World"
34

35
// With length hint for better performance
36
const arrays = [
37
  new Uint8Array([1, 2, 3]),
38
  new Uint8Array([4, 5]),
39
  new Uint8Array([6, 7, 8, 9])
40
];
41
const result = concat(arrays, 9); // Length hint improves performance
42
console.log(result); // Uint8Array(9) [1, 2, 3, 4, 5, 6, 7, 8, 9]
43

44
// Concatenating many small arrays
45
const chunks = [];
46
for (let i = 0; i < 100; i++) {
47
  chunks.push(new Uint8Array([i]));
48
}
49
const all = concat(chunks, 100);
50
```
51

52
### Array Comparison
53

54
Lexicographic comparison of two Uint8Arrays, compatible with Array.sort for ordering arrays.
55

56
```typescript { .api }
57
/**
58
 * Can be used with Array.sort to sort an array with Uint8Array entries
59
 * @param a - First array to compare
60
 * @param b - Second array to compare
61
 * @returns -1 if a < b, 1 if a > b, 0 if equal
62
 */
63
function compare(a: Uint8Array, b: Uint8Array): number;
64
```
65

66
**Usage Examples:**
67

68
```typescript
69
import { compare } from "uint8arrays/compare";
70

71
// Direct comparison
72
const array1 = new Uint8Array([1, 2, 3]);
73
const array2 = new Uint8Array([1, 2, 4]);
74
console.log(compare(array1, array2)); // -1 (array1 < array2)
75

76
const array3 = new Uint8Array([1, 2, 3]);
77
console.log(compare(array1, array3)); // 0 (equal)
78

79
// Sorting arrays
80
const arrays = [
81
  new Uint8Array([3, 4, 5]),
82
  new Uint8Array([1, 2, 3]),
83
  new Uint8Array([2, 3, 4])
84
];
85

86
const sorted = arrays.sort(compare);
87
console.log(sorted);
88
// [
89
//   Uint8Array(3) [1, 2, 3],
90
//   Uint8Array(3) [2, 3, 4], 
91
//   Uint8Array(3) [3, 4, 5]
92
// ]
93

94
// Length affects comparison
95
const short = new Uint8Array([1, 2]);
96
const long = new Uint8Array([1, 2, 0]);
97
console.log(compare(short, long)); // -1 (shorter array is "less")
98
```
99

100
### Array Equality
101

102
Fast equality testing for Uint8Arrays with identical content. Optimized for performance with early returns.
103

104
```typescript { .api }
105
/**
106
 * Returns true if the two passed Uint8Arrays have the same content
107
 * @param a - First array to compare
108
 * @param b - Second array to compare
109
 * @returns true if arrays are identical, false otherwise
110
 */
111
function equals(a: Uint8Array, b: Uint8Array): boolean;
112
```
113

114
**Usage Examples:**
115

116
```typescript
117
import { equals } from "uint8arrays/equals";
118
import { fromString } from "uint8arrays/from-string";
119

120
// Basic equality
121
const array1 = new Uint8Array([1, 2, 3]);
122
const array2 = new Uint8Array([1, 2, 3]);
123
const array3 = new Uint8Array([1, 2, 4]);
124

125
console.log(equals(array1, array2)); // true
126
console.log(equals(array1, array3)); // false
127

128
// Same reference check (optimized)
129
console.log(equals(array1, array1)); // true (fast path)
130

131
// String comparison
132
const str1 = fromString("hello");
133
const str2 = fromString("hello");
134
const str3 = fromString("world");
135

136
console.log(equals(str1, str2)); // true
137
console.log(equals(str1, str3)); // false
138

139
// Different lengths
140
const short = new Uint8Array([1, 2]);
141
const long = new Uint8Array([1, 2, 3]);
142
console.log(equals(short, long)); // false (early return)
143
```
144

145
## Performance Characteristics
146

147
### concat()
148
- **Time Complexity**: O(n) where n is total length of all arrays
149
- **Space Complexity**: O(n) for result array
150
- **Optimization**: Providing length parameter avoids array traversal
151
- **Node.js**: Uses Buffer.concat() when available
152

153
### compare()
154
- **Time Complexity**: O(min(a.length, b.length)) average case
155
- **Early Termination**: Stops at first differing byte
156
- **Lexicographic**: Shorter arrays are considered "less than" longer arrays with same prefix
157
- **Node.js**: Uses Buffer.compare() when available
158

159
### equals()
160
- **Time Complexity**: O(n) worst case, O(1) best case
161
- **Reference Check**: Same reference returns true immediately
162
- **Length Check**: Different lengths return false immediately
163
- **Byte-by-byte**: Only compares content when necessary
164

165
## Error Handling
166

167
All functions handle edge cases gracefully:
168

169
- Empty arrays are supported in all operations
170
- Different lengths are handled appropriately for each operation
171
- No parameter validation errors - follows JavaScript conventions