0
# Utilities and Buffer Management
1

2
Core utility functions for data manipulation, encoding/decoding, and buffer operations essential for cryptographic work. Node-forge provides comprehensive utility functions for handling binary data, encoding operations, and cross-platform compatibility.
3

4
## Capabilities
5

6
### Buffer Creation and Management
7

8
Creates and manages binary buffers for cryptographic operations.
9

10
```javascript { .api }
11
/**
12
 * Creates a buffer for binary data operations
13
 * @param input - Initial data (string, ArrayBuffer, or bytes)
14
 * @param encoding - Encoding format (default: 'raw', also supports 'utf8')
15
 * @returns ByteStringBuffer instance for data manipulation
16
 */
17
forge.util.createBuffer(input?: string | ArrayBuffer, encoding?: string): ByteStringBuffer;
18

19
interface ByteStringBuffer {
20
  /** Add a single byte to the buffer */
21
  putByte(byte: number): ByteStringBuffer;
22
  /** Add bytes to the buffer */
23
  putBytes(bytes: string): ByteStringBuffer;
24
  /** Add a string to the buffer */
25
  putString(str: string): ByteStringBuffer;
26
  /** Add a 16-bit integer in big-endian order */
27
  putInt16(value: number): ByteStringBuffer;
28
  /** Add a 24-bit integer in big-endian order */
29
  putInt24(value: number): ByteStringBuffer;
30
  /** Add a 32-bit integer in big-endian order */
31
  putInt32(value: number): ByteStringBuffer;
32
  /** Add an n-bit integer in big-endian order */
33
  putInt(value: number, n: number): ByteStringBuffer;
34
  /** Fill buffer with repeated byte value */
35
  fillWithByte(byte: number, count: number): ByteStringBuffer;
36
  
37
  /** Get a single byte and advance read pointer */
38
  getByte(): number;
39
  /** Get bytes and advance read pointer */
40
  getBytes(count?: number): string;
41
  /** Get a 16-bit integer in big-endian order and advance read pointer */
42
  getInt16(): number;
43
  /** Get a 24-bit integer in big-endian order and advance read pointer */
44
  getInt24(): number;
45
  /** Get a 32-bit integer in big-endian order and advance read pointer */
46
  getInt32(): number;
47
  /** Get an n-bit integer in big-endian order and advance read pointer */
48
  getInt(n: number): number;
49
  /** Get signed n-bit integer using two's complement */
50
  getSignedInt(n: number): number;
51
  
52
  /** Get current buffer length */
53
  length(): number;
54
  /** Check if buffer is empty */
55
  isEmpty(): boolean;
56
  /** Convert buffer to hexadecimal string */
57
  toHex(): string;
58
  /** Convert buffer to string representation */
59
  toString(): string;
60
  /** Create a copy of the buffer */
61
  copy(): ByteStringBuffer;
62
  /** Clear the buffer */
63
  clear(): ByteStringBuffer;
64
  /** Truncate buffer to specified length */
65
  truncate(count?: number): ByteStringBuffer;
66
}
67
```
68

69
**Usage Examples:**
70

71
```javascript
72
const forge = require('node-forge');
73

74
// Create buffer from string
75
const buffer = forge.util.createBuffer('Hello World');
76

77
// Create buffer from hex data
78
const hexBuffer = forge.util.createBuffer();
79
hexBuffer.putBytes(forge.util.hexToBytes('48656c6c6f'));
80

81
// Working with integers
82
const intBuffer = forge.util.createBuffer();
83
intBuffer.putInt32(0x12345678);
84
intBuffer.putInt16(0xABCD);
85

86
// Reading data
87
const data = intBuffer.getInt32(); // 0x12345678
88
const shortData = intBuffer.getInt16(); // 0xABCD
89
```
90

91
### Encoding and Decoding
92

93
Base64 and hexadecimal encoding/decoding utilities.
94

95
```javascript { .api }
96
/**
97
 * Encode binary data to base64 string
98
 * @param input - Binary data to encode
99
 * @param maxline - Optional line length for formatting
100
 * @returns Base64 encoded string
101
 */
102
forge.util.encode64(input: string, maxline?: number): string;
103

104
/**
105
 * Decode base64 string to binary data
106
 * @param input - Base64 encoded string
107
 * @returns Binary decoded string
108
 */
109
forge.util.decode64(input: string): string;
110

111
/**
112
 * Convert hexadecimal string to binary bytes
113
 * @param hex - Hexadecimal string (e.g., "48656c6c6f")
114
 * @returns Binary string representation
115
 */
116
forge.util.hexToBytes(hex: string): string;
117

118
/**
119
 * Convert binary bytes to hexadecimal string
120
 * @param bytes - Binary data string
121
 * @returns Hexadecimal string representation
122
 */
123
forge.util.bytesToHex(bytes: string): string;
124
```
125

126
**Usage Examples:**
127

128
```javascript
129
// Base64 operations
130
const data = 'Hello World';
131
const encoded = forge.util.encode64(data);        // 'SGVsbG8gV29ybGQ='
132
const decoded = forge.util.decode64(encoded);     // 'Hello World'
133

134
// Hex operations
135
const hexString = '48656c6c6f20576f726c64';       // "Hello World" in hex
136
const bytes = forge.util.hexToBytes(hexString);   // Binary string
137
const backToHex = forge.util.bytesToHex(bytes);   // '48656c6c6f20576f726c64'
138
```
139

140
### UTF-8 Encoding
141

142
UTF-8 string encoding and decoding utilities.
143

144
```javascript { .api }
145
/**
146
 * Encode a string to UTF-8 bytes
147
 * @param str - String to encode
148
 * @returns UTF-8 encoded binary string
149
 */
150
forge.util.encodeUtf8(str: string): string;
151

152
/**
153
 * Decode UTF-8 bytes to string
154
 * @param bytes - UTF-8 encoded binary data
155
 * @returns Decoded string
156
 */
157
forge.util.decodeUtf8(bytes: string): string;
158
```
159

160
### String Utilities
161

162
String manipulation utilities for cryptographic operations.
163

164
```javascript { .api }
165
/**
166
 * Create a string filled with repeated character
167
 * @param char - Character to repeat
168
 * @param length - Number of repetitions
169
 * @returns String filled with character
170
 */
171
forge.util.fillString(char: string, length: number): string;
172

173
/**
174
 * XOR two byte strings
175
 * @param bytes1 - First byte string
176
 * @param bytes2 - Second byte string
177
 * @param count - Number of bytes to XOR
178
 * @param offset - Starting offset
179
 * @returns XOR result as string
180
 */
181
forge.util.xorBytes(bytes1: string, bytes2: string, count: number, offset: number): string;
182
```
183

184
### Type Checking
185

186
Runtime type checking utilities.
187

188
```javascript { .api }
189
/**
190
 * Check if value is an array
191
 * @param obj - Value to check
192
 * @returns True if value is array
193
 */
194
forge.util.isArray(obj: any): boolean;
195

196
/**
197
 * Check if value is an ArrayBuffer
198
 * @param obj - Value to check
199
 * @returns True if value is ArrayBuffer
200
 */
201
forge.util.isArrayBuffer(obj: any): boolean;
202

203
/**
204
 * Check if value is an ArrayBuffer view
205
 * @param obj - Value to check
206
 * @returns True if value is ArrayBuffer view
207
 */
208
forge.util.isArrayBufferView(obj: any): boolean;
209
```
210

211
### Asynchronous Utilities
212

213
Cross-platform asynchronous scheduling utilities.
214

215
```javascript { .api }
216
/**
217
 * Schedule callback for next tick (cross-platform)
218
 * @param callback - Function to execute
219
 */
220
forge.util.nextTick(callback: () => void): void;
221

222
/**
223
 * Schedule callback for immediate execution (cross-platform)
224
 * @param callback - Function to execute
225
 */
226
forge.util.setImmediate(callback: () => void): void;
227
```
228

229
### IP Address Utilities
230

231
IP address conversion utilities.
232

233
```javascript { .api }
234
/**
235
 * Convert IP address string to binary bytes
236
 * @param ip - IP address string (IPv4 or IPv6)
237
 * @returns Binary representation or null if invalid
238
 */
239
forge.util.bytesFromIP(ip: string): string | null;
240

241
/**
242
 * Convert binary bytes to IP address string
243
 * @param bytes - Binary IP address data
244
 * @returns IP address string
245
 */
246
forge.util.bytesToIP(bytes: string): string;
247

248
/**
249
 * Convert IPv4 address to binary bytes
250
 * @param ip - IPv4 address string (e.g., "192.168.1.1")
251
 * @returns 4-byte binary string or null if invalid
252
 */
253
forge.util.bytesFromIPv4(ip: string): string | null;
254

255
/**
256
 * Convert binary bytes to IPv4 address string
257
 * @param bytes - 4-byte binary data
258
 * @returns IPv4 address string
259
 */
260
forge.util.bytesToIPv4(bytes: string): string;
261

262
/**
263
 * Convert IPv6 address to binary bytes
264
 * @param ip - IPv6 address string
265
 * @returns 16-byte binary string or null if invalid
266
 */
267
forge.util.bytesFromIPv6(ip: string): string | null;
268

269
/**
270
 * Convert binary bytes to IPv6 address string
271
 * @param bytes - 16-byte binary data
272
 * @returns IPv6 address string
273
 */
274
forge.util.bytesToIPv6(bytes: string): string;
275
```
276

277
### Storage Utilities
278

279
Cross-platform storage utilities with automatic JSON serialization.
280

281
```javascript { .api }
282
/**
283
 * Store data in storage with automatic JSON encoding
284
 * @param storage - Storage API object
285
 * @param key - Storage key
286
 * @param data - Data to store (automatically JSON encoded)
287
 * @returns Storage operation result
288
 */
289
forge.util.setItem(storage: any, key: string, data: any): any;
290

291
/**
292
 * Retrieve data from storage with automatic JSON decoding
293
 * @param storage - Storage API object
294
 * @param key - Storage key
295
 * @returns Retrieved and decoded data
296
 */
297
forge.util.getItem(storage: any, key: string): any;
298

299
/**
300
 * Remove item from storage
301
 * @param storage - Storage API object
302
 * @param key - Storage key
303
 * @returns Storage operation result
304
 */
305
forge.util.removeItem(storage: any, key: string): any;
306

307
/**
308
 * Clear items from storage matching key pattern
309
 * @param storage - Storage API object
310
 * @param key - Key pattern for matching items to clear
311
 * @returns Storage operation result
312
 */
313
forge.util.clearItems(storage: any, key: string): any;
314
```
315

316
### Data Formatting
317

318
Utilities for formatting numbers, sizes, and other data.
319

320
```javascript { .api }
321
/**
322
 * Format a string with substitution parameters (similar to printf)
323
 * @param format - Format string with %s, %d, etc. placeholders
324
 * @param ...args - Arguments for substitution
325
 * @returns Formatted string
326
 */
327
forge.util.format(format: string, ...args: any[]): string;
328

329
/**
330
 * Format a number with decimal places and separators
331
 * @param number - Number to format
332
 * @param decimals - Number of decimal places
333
 * @param decimalPoint - Decimal separator character
334
 * @param thousandsSeparator - Thousands separator character
335
 * @returns Formatted number string
336
 */
337
forge.util.formatNumber(number: number, decimals?: number, decimalPoint?: string, thousandsSeparator?: string): string;
338

339
/**
340
 * Format a byte size to human-readable string
341
 * @param size - Size in bytes
342
 * @returns Formatted size string (e.g., "1.5 KB", "2.3 MB")
343
 */
344
forge.util.formatSize(size: number): string;
345

346
/**
347
 * Convert 32-bit integer to 4-byte binary string
348
 * @param integer - 32-bit integer value
349
 * @returns 4-byte binary string
350
 */
351
forge.util.int32ToBytes(integer: number): string;
352
```
353

354
### Object Utilities
355

356
Utilities for object manipulation and property checking.
357

358
```javascript { .api }
359
/**
360
 * Check if an object is empty (has no enumerable properties)
361
 * @param obj - Object to check
362
 * @returns True if object is empty
363
 */
364
forge.util.isEmpty(obj: object): boolean;
365
```
366

367
### Compression Utilities
368

369
Data compression and decompression utilities.
370

371
```javascript { .api }
372
/**
373
 * Deflate (compress) data using specified algorithm
374
 * @param api - Compression API to use
375
 * @param data - Data to compress
376
 * @param raw - Whether to output raw deflate data
377
 * @returns Compressed data
378
 */
379
forge.util.deflate(api: object, data: string, raw?: boolean): string;
380

381
/**
382
 * Inflate (decompress) data using specified algorithm
383
 * @param api - Compression API to use
384
 * @param data - Data to decompress
385
 * @param raw - Whether input is raw deflate data
386
 * @returns Decompressed data
387
 */
388
forge.util.inflate(api: object, data: string, raw?: boolean): string;
389
```
390

391
### System Information
392

393
System and environment detection utilities.
394

395
```javascript { .api }
396
/**
397
 * Estimate number of CPU cores available (with callback for async operation)
398
 * @param options - Configuration options for estimation
399
 * @param callback - Callback function receiving estimated core count
400
 */
401
forge.util.estimateCores(options?: object, callback?: (cores: number) => void): void;
402

403
/**
404
 * Estimate number of CPU cores available (synchronous)
405
 * @returns Estimated core count
406
 */
407
forge.util.estimateCores(): number;
408

409
/**
410
 * Indicates whether running in Node.js environment
411
 */
412
forge.util.isNodejs: boolean;
413

414
/**
415
 * Reference to global scope object (cross-platform)
416
 */
417
forge.util.globalScope: any;
418
```