0
# Memory Allocation
1

2
Memory allocation functions for creating Uint8Arrays with optimized performance. These functions automatically use Node.js Buffer when available for better performance while maintaining compatibility across all JavaScript environments.
3

4
## Capabilities
5

6
### Safe Allocation
7

8
Creates a new Uint8Array with memory initialized to zero values. Safe and predictable for all use cases.
9

10
```typescript { .api }
11
/**
12
 * Returns a Uint8Array of the requested size. Referenced memory will be initialized to 0.
13
 * @param size - Size of the array to allocate (default: 0)
14
 * @returns New Uint8Array with zero-initialized memory
15
 */
16
function alloc(size?: number): Uint8Array;
17
```
18

19
**Usage Examples:**
20

21
```typescript
22
import { alloc } from "uint8arrays/alloc";
23

24
// Create a 10-byte zero-initialized array
25
const buffer = alloc(10);
26
console.log(buffer); // Uint8Array(10) [0, 0, 0, 0, 0, 0, 0, 0, 0, 0]
27

28
// Create empty array (0 bytes)
29
const empty = alloc();
30
console.log(empty.length); // 0
31

32
// Useful for preparing buffers for writing
33
const writeBuffer = alloc(1024);
34
// All bytes are guaranteed to be 0
35
```
36

37
### Unsafe Allocation
38

39
Creates a new Uint8Array with potentially uninitialized memory for maximum performance. Only use when you will immediately overwrite all values.
40

41
```typescript { .api }
42
/**
43
 * Where possible returns a Uint8Array of the requested size that references
44
 * uninitialized memory. Only use if you are certain you will immediately
45
 * overwrite every value in the returned Uint8Array.
46
 * @param size - Size of the array to allocate (default: 0)
47
 * @returns New Uint8Array with potentially uninitialized memory
48
 */
49
function allocUnsafe(size?: number): Uint8Array;
50
```
51

52
**Usage Examples:**
53

54
```typescript
55
import { allocUnsafe } from "uint8arrays/alloc";
56

57
// Allocate buffer for immediate writing
58
const buffer = allocUnsafe(8);
59
// IMPORTANT: Don't read from buffer before writing to it
60

61
// Fill with specific pattern
62
for (let i = 0; i < buffer.length; i++) {
63
  buffer[i] = i * 2;
64
}
65
console.log(buffer); // Uint8Array(8) [0, 2, 4, 6, 8, 10, 12, 14]
66

67
// Use with APIs that write to buffers
68
const readBuffer = allocUnsafe(1024);
69
// Pass to file reading, network operations, etc.
70
```
71

72
## Platform Optimizations
73

74
Both allocation functions provide platform-specific optimizations:
75

76
- **Node.js**: Uses `Buffer.alloc()` and `Buffer.allocUnsafe()` for better performance
77
- **Browser/Other**: Uses standard `new Uint8Array()` constructor
78
- **Return Type**: Always returns a Uint8Array regardless of internal implementation
79

80
## Performance Considerations
81

82
- **alloc**: Slightly slower due to zero-initialization, but always safe
83
- **allocUnsafe**: Faster allocation, but requires immediate initialization
84
- **Node.js**: Significant performance improvement when Buffer is available
85
- **Memory**: Both functions create actual memory allocations, not views
86

87
## Error Handling
88

89
Both functions handle edge cases gracefully:
90

91
- Negative size values are treated as 0
92
- Very large size values may throw RangeError (platform dependent)
93
- Non-integer size values are truncated