0
# Byte Array Utilities
1

2
Comprehensive byte manipulation utilities optimized for big data processing, including conversions between primitive types and byte arrays, array operations, comparisons, and hash computations. The Bytes class provides essential functionality for data serialization, network protocols, and storage systems in distributed computing environments.
3

4
## Capabilities
5

6
### Type Conversions
7

8
Convert between primitive Java types and their byte array representations using big-endian encoding.
9

10
```java { .api }
11
// String conversions
12
/**
13
 * Convert string to UTF-8 byte array
14
 * @param s String to convert
15
 * @return UTF-8 encoded byte array
16
 */
17
public static byte[] toBytes(String s);
18

19
/**
20
 * Convert UTF-8 byte array to string
21
 * @param b UTF-8 encoded byte array
22
 * @return String or null if conversion fails
23
 */
24
public static String toString(byte[] b);
25

26
/**
27
 * Convert UTF-8 byte array segment to string
28
 * @param b Byte array
29
 * @param off Offset in array
30
 * @param len Length to convert
31
 * @return String or null if conversion fails
32
 */
33
public static String toString(byte[] b, int off, int len);
34

35
// Numeric type conversions
36
/**
37
 * Convert boolean to byte array (true=-1, false=0)
38
 * @param b Boolean value
39
 * @return Byte array representation
40
 */
41
public static byte[] toBytes(boolean b);
42

43
/**
44
 * Convert long to 8-byte array (big-endian)
45
 * @param val Long value
46
 * @return 8-byte array
47
 */
48
public static byte[] toBytes(long val);
49

50
/**
51
 * Convert int to 4-byte array (big-endian)  
52
 * @param val Int value
53
 * @return 4-byte array
54
 */
55
public static byte[] toBytes(int val);
56

57
/**
58
 * Convert short to 2-byte array (big-endian)
59
 * @param val Short value
60
 * @return 2-byte array
61
 */
62
public static byte[] toBytes(short val);
63

64
/**
65
 * Convert float to 4-byte array (IEEE 754)
66
 * @param f Float value
67
 * @return 4-byte array
68
 */
69
public static byte[] toBytes(float f);
70

71
/**
72
 * Convert double to 8-byte array (IEEE 754)
73
 * @param d Double value
74
 * @return 8-byte array
75
 */
76
public static byte[] toBytes(double d);
77

78
// Reverse conversions
79
public static boolean toBoolean(byte[] b);
80
public static long toLong(byte[] bytes);
81
public static int toInt(byte[] bytes);
82
public static short toShort(byte[] bytes);
83
public static float toFloat(byte[] bytes);
84
public static double toDouble(byte[] bytes);
85
```
86

87
**Usage Examples:**
88

89
```java
90
// String conversions
91
String text = "Hello, World!";
92
byte[] textBytes = Bytes.toBytes(text);
93
String recovered = Bytes.toString(textBytes); // "Hello, World!"
94

95
// Numeric conversions
96
long timestamp = System.currentTimeMillis();
97
byte[] timestampBytes = Bytes.toBytes(timestamp);
98
long recoveredTimestamp = Bytes.toLong(timestampBytes);
99

100
int count = 42;
101
byte[] countBytes = Bytes.toBytes(count);
102
int recoveredCount = Bytes.toInt(countBytes);
103

104
// Boolean conversion
105
boolean flag = true;
106
byte[] flagBytes = Bytes.toBytes(flag); // [-1]
107
boolean recoveredFlag = Bytes.toBoolean(flagBytes); // true
108
```
109

110
### Complex Type Conversions
111

112
Convert complex types including BigDecimal, UUID, and ByteBuffer to byte arrays.
113

114
```java { .api }
115
/**
116
 * Convert BigDecimal to byte array
117
 * @param val BigDecimal value
118
 * @return Byte array with scale and unscaled value
119
 */
120
public static byte[] toBytes(BigDecimal val);
121

122
/**
123
 * Convert byte array to BigDecimal
124
 * @param bytes Byte array
125
 * @return BigDecimal value
126
 */
127
public static BigDecimal toBigDecimal(byte[] bytes);
128

129
/**
130
 * Convert UUID to 16-byte array
131
 * @param uuid UUID value
132
 * @return 16-byte array
133
 */
134
public static byte[] toBytes(UUID uuid);
135

136
/**
137
 * Convert 16-byte array to UUID
138
 * @param bytes 16-byte array
139
 * @return UUID value
140
 */
141
public static UUID toUUID(byte[] bytes);
142

143
/**
144
 * Convert ByteBuffer to byte array
145
 * @param bb ByteBuffer
146
 * @return Byte array copy of buffer contents
147
 */
148
public static byte[] toBytes(ByteBuffer bb);
149
```
150

151
**Usage Examples:**
152

153
```java
154
import java.math.BigDecimal;
155
import java.util.UUID;
156
import java.nio.ByteBuffer;
157

158
// BigDecimal conversion
159
BigDecimal price = new BigDecimal("123.45");
160
byte[] priceBytes = Bytes.toBytes(price);
161
BigDecimal recoveredPrice = Bytes.toBigDecimal(priceBytes); // 123.45
162

163
// UUID conversion
164
UUID id = UUID.randomUUID();
165
byte[] idBytes = Bytes.toBytes(id);
166
UUID recoveredId = Bytes.toUUID(idBytes);
167

168
// ByteBuffer conversion
169
ByteBuffer buffer = ByteBuffer.allocate(10);
170
buffer.put("test".getBytes());
171
buffer.flip();
172
byte[] bufferBytes = Bytes.toBytes(buffer);
173
```
174

175
### Array Operations
176

177
Manipulate byte arrays with concatenation, slicing, and padding operations.
178

179
```java { .api }
180
/**
181
 * Concatenate two byte arrays
182
 * @param a First array
183
 * @param b Second array
184
 * @return Combined array
185
 */
186
public static byte[] add(byte[] a, byte[] b);
187

188
/**
189
 * Concatenate three byte arrays
190
 * @param a First array
191
 * @param b Second array
192
 * @param c Third array
193
 * @return Combined array
194
 */
195
public static byte[] add(byte[] a, byte[] b, byte[] c);
196

197
/**
198
 * Concatenate multiple byte arrays
199
 * @param arrays Variable number of arrays
200
 * @return Combined array
201
 */
202
public static byte[] concat(byte[]... arrays);
203

204
/**
205
 * Get first N bytes from array
206
 * @param a Source array
207
 * @param length Number of bytes
208
 * @return First N bytes or null if array too short
209
 */
210
public static byte[] head(byte[] a, int length);
211

212
/**
213
 * Get last N bytes from array
214
 * @param a Source array  
215
 * @param length Number of bytes
216
 * @return Last N bytes or null if array too short
217
 */
218
public static byte[] tail(byte[] a, int length);
219

220
/**
221
 * Prepend zero bytes to array
222
 * @param a Source array
223
 * @param length Number of zeros to prepend
224
 * @return Padded array
225
 */
226
public static byte[] padHead(byte[] a, int length);
227

228
/**
229
 * Append zero bytes to array
230
 * @param a Source array
231
 * @param length Number of zeros to append
232
 * @return Padded array
233
 */
234
public static byte[] padTail(byte[] a, int length);
235
```
236

237
**Usage Examples:**
238

239
```java
240
byte[] part1 = Bytes.toBytes("Hello");
241
byte[] part2 = Bytes.toBytes(" ");
242
byte[] part3 = Bytes.toBytes("World");
243

244
// Concatenation
245
byte[] greeting = Bytes.add(part1, part2, part3);
246
String result = Bytes.toString(greeting); // "Hello World"
247

248
// Multiple array concatenation
249
byte[] combined = Bytes.concat(part1, part2, part3);
250

251
// Array slicing
252
byte[] data = Bytes.toBytes("abcdefghij");
253
byte[] firstFive = Bytes.head(data, 5);  // "abcde"
254
byte[] lastFive = Bytes.tail(data, 5);   // "fghij"
255

256
// Padding
257
byte[] original = Bytes.toBytes("test");
258
byte[] headPadded = Bytes.padHead(original, 3);  // [0,0,0,t,e,s,t]
259
byte[] tailPadded = Bytes.padTail(original, 3);  // [t,e,s,t,0,0,0]
260
```
261

262
### Byte Array Writing and Reading
263

264
Write values at specific positions in byte arrays and read from ByteBuffers.
265

266
```java { .api }
267
/**
268
 * Write bytes at specified position
269
 * @param tgtBytes Target array
270
 * @param tgtOffset Position in target
271
 * @param srcBytes Source array
272
 * @param srcOffset Source position
273
 * @param srcLength Length to copy
274
 * @return New offset after write
275
 */
276
public static int putBytes(byte[] tgtBytes, int tgtOffset, byte[] srcBytes, int srcOffset, int srcLength);
277

278
/**
279
 * Write long at specified position
280
 * @param bytes Target array
281
 * @param offset Position to write
282
 * @param val Long value
283
 * @return New offset after write
284
 * @throws IllegalArgumentException if insufficient space
285
 */
286
public static int putLong(byte[] bytes, int offset, long val);
287

288
/**
289
 * Write int at specified position
290
 * @param bytes Target array
291
 * @param offset Position to write
292
 * @param val Int value
293
 * @return New offset after write
294
 */
295
public static int putInt(byte[] bytes, int offset, int val);
296

297
// Similar methods for putShort, putFloat, putDouble, putByte
298

299
/**
300
 * Extract bytes from ByteBuffer without changing position
301
 * @param buf ByteBuffer
302
 * @return Byte array copy
303
 */
304
public static byte[] getBytes(ByteBuffer buf);
305
```
306

307
**Usage Examples:**
308

309
```java
310
// Create buffer for structured data
311
byte[] buffer = new byte[16];
312
int offset = 0;
313

314
// Write multiple values sequentially
315
offset = Bytes.putInt(buffer, offset, 12345);     // Write int at position 0
316
offset = Bytes.putLong(buffer, offset, 67890L);   // Write long at position 4
317
offset = Bytes.putFloat(buffer, offset, 3.14f);   // Write float at position 12
318

319
// Read values back
320
int intValue = Bytes.toInt(buffer, 0);      // 12345
321
long longValue = Bytes.toLong(buffer, 4);   // 67890L
322
float floatValue = Bytes.toFloat(buffer, 12); // 3.14f
323

324
// ByteBuffer extraction
325
ByteBuffer bb = ByteBuffer.wrap("example data".getBytes());
326
byte[] extracted = Bytes.getBytes(bb); // Preserves buffer position
327
```
328

329
### Comparison Operations
330

331
Compare byte arrays lexicographically with optimized implementations.
332

333
```java { .api }
334
/**
335
 * Lexicographically compare byte arrays
336
 * @param left Left operand
337
 * @param right Right operand
338
 * @return 0 if equal, <0 if left < right, >0 if left > right
339
 */
340
public static int compareTo(byte[] left, byte[] right);
341

342
/**
343
 * Compare byte array segments
344
 * @param buffer1 First array
345
 * @param offset1 First array start position
346
 * @param length1 First array length
347
 * @param buffer2 Second array
348
 * @param offset2 Second array start position
349
 * @param length2 Second array length
350
 * @return Comparison result
351
 */
352
public static int compareTo(byte[] buffer1, int offset1, int length1,
353
                           byte[] buffer2, int offset2, int length2);
354

355
/**
356
 * Check byte array equality
357
 * @param left Left array
358
 * @param right Right array
359
 * @return true if arrays are equal
360
 */
361
public static boolean equals(byte[] left, byte[] right);
362

363
/**
364
 * Check if array starts with prefix
365
 * @param bytes Array to check
366
 * @param prefix Prefix to match
367
 * @return true if bytes starts with prefix
368
 */
369
public static boolean startsWith(byte[] bytes, byte[] prefix);
370

371
/**
372
 * Byte array comparator for use with TreeMap, TreeSet, etc.
373
 */
374
public static final Comparator<byte[]> BYTES_COMPARATOR;
375
```
376

377
**Usage Examples:**
378

379
```java
380
byte[] array1 = Bytes.toBytes("apple");
381
byte[] array2 = Bytes.toBytes("banana");
382
byte[] array3 = Bytes.toBytes("apple");
383

384
// Comparison
385
int result1 = Bytes.compareTo(array1, array2); // < 0 (apple < banana)
386
int result2 = Bytes.compareTo(array1, array3); // 0 (equal)
387

388
// Equality
389
boolean equal = Bytes.equals(array1, array3); // true
390

391
// Prefix checking
392
byte[] data = Bytes.toBytes("Hello World");
393
byte[] prefix = Bytes.toBytes("Hello");
394
boolean hasPrefix = Bytes.startsWith(data, prefix); // true
395

396
// Use with sorted collections
397
TreeMap<byte[], String> sortedMap = new TreeMap<>(Bytes.BYTES_COMPARATOR);
398
sortedMap.put(Bytes.toBytes("key1"), "value1");
399
sortedMap.put(Bytes.toBytes("key2"), "value2");
400
```
401

402
### Hash Computation
403

404
Generate hash codes for byte arrays optimized for use as map keys.
405

406
```java { .api }
407
/**
408
 * Compute hash code for byte array
409
 * @param b Byte array
410
 * @return Hash code
411
 */
412
public static int hashCode(byte[] b);
413

414
/**
415
 * Compute hash code for byte array segment
416
 * @param bytes Byte array
417
 * @param offset Start position
418
 * @param length Length to hash
419
 * @return Hash code
420
 */
421
public static int hashCode(byte[] bytes, int offset, int length);
422

423
/**
424
 * Generate Integer hash suitable for HashMap keys
425
 * @param b Byte array
426
 * @return Integer hash code
427
 */
428
public static Integer mapKey(byte[] b);
429

430
/**
431
 * Generate Integer hash for array segment
432
 * @param b Byte array
433
 * @param length Length to hash
434
 * @return Integer hash code
435
 */
436
public static Integer mapKey(byte[] b, int length);
437
```
438

439
**Usage Examples:**
440

441
```java
442
byte[] key1 = Bytes.toBytes("user123");
443
byte[] key2 = Bytes.toBytes("user456");
444

445
// Generate hash codes
446
int hash1 = Bytes.hashCode(key1);
447
int hash2 = Bytes.hashCode(key2);
448

449
// Use as HashMap keys
450
Map<Integer, String> dataMap = new HashMap<>();
451
dataMap.put(Bytes.mapKey(key1), "User data for 123");
452
dataMap.put(Bytes.mapKey(key2), "User data for 456");
453

454
// Hash array segments
455
byte[] largeArray = Bytes.toBytes("This is a long string with data");
456
int segmentHash = Bytes.hashCode(largeArray, 5, 10); // Hash bytes 5-14
457
```
458

459
### String Representation
460

461
Convert byte arrays to readable string formats including hex and binary representations.
462

463
```java { .api }
464
/**
465
 * Convert byte array to hex string
466
 * @param bytes Byte array
467
 * @return Lowercase hex string
468
 */
469
public static String toHexString(byte[] bytes);
470

471
/**
472
 * Convert hex string to byte array
473
 * @param str Hex string (must have even length)
474
 * @return Byte array
475
 * @throws IllegalArgumentException if odd length
476
 */
477
public static byte[] fromHexString(String str);
478

479
/**
480
 * Convert byte array to printable binary representation
481
 * @param b Byte array
482
 * @return String with printable chars and \xHH escapes
483
 */
484
public static String toStringBinary(byte[] b);
485

486
/**
487
 * Parse binary-escaped string to byte array
488
 * @param in String with \xHH escape sequences
489
 * @return Parsed byte array
490
 */
491
public static byte[] toBytesBinary(String in);
492
```
493

494
**Usage Examples:**
495

496
```java
497
byte[] data = {0x48, 0x65, 0x6c, 0x6c, 0x6f}; // "Hello"
498

499
// Hex representation
500
String hex = Bytes.toHexString(data); // "48656c6c6f"
501
byte[] fromHex = Bytes.fromHexString(hex); // Recovers original data
502

503
// Binary representation (printable + escapes)
504
byte[] mixedData = {0x48, 0x65, 0x6c, 0x6c, 0x6f, 0x00, 0x01, 0x02};
505
String binary = Bytes.toStringBinary(mixedData); // "Hello\x00\x01\x02"
506
byte[] fromBinary = Bytes.toBytesBinary(binary); // Recovers original
507

508
// Regular string representation
509
String readable = Bytes.toString(data); // "Hello"
510
```
511

512
### Advanced Operations
513

514
Specialized operations for range splitting, incrementation, and prefix operations.
515

516
```java { .api }
517
/**
518
 * Split byte range for MapReduce-style processing
519
 * @param a Start of range
520
 * @param b End of range  
521
 * @param num Number of splits
522
 * @return Array of split points
523
 */
524
public static byte[][] split(byte[] a, byte[] b, int num);
525

526
/**
527
 * Increment byte array by specified amount
528
 * @param value Byte array to increment (≤8 bytes)
529
 * @param amount Increment amount
530
 * @return Incremented byte array
531
 */
532
public static byte[] incrementBytes(byte[] value, long amount);
533

534
/**
535
 * Generate stop key for prefix scanning
536
 * @param prefix Prefix bytes
537
 * @return Stop key for range scanning, or null if prefix cannot be incremented
538
 */
539
public static byte[] stopKeyForPrefix(byte[] prefix);
540

541
/**
542
 * Write fixed-size string with zero padding
543
 * @param out DataOutput stream
544
 * @param s String to write
545
 * @param size Fixed field size
546
 * @throws IOException if string too long or write fails
547
 */
548
public static void writeStringFixedSize(DataOutput out, String s, int size) throws IOException;
549
```
550

551
**Usage Examples:**
552

553
```java
554
// Range splitting for distributed processing
555
byte[] startKey = Bytes.toBytes("user000");
556
byte[] endKey = Bytes.toBytes("user999");
557
byte[][] splits = Bytes.split(startKey, endKey, 4); // Create 4 ranges
558

559
// Byte array incrementation
560
byte[] counter = Bytes.toBytes(100L);
561
byte[] incremented = Bytes.incrementBytes(counter, 50); // Now contains 150L
562

563
// Prefix scanning
564
byte[] prefix = Bytes.toBytes("user");
565
byte[] stopKey = Bytes.stopKeyForPrefix(prefix); // For scanning user* keys
566

567
// Fixed-size string writing
568
ByteArrayOutputStream baos = new ByteArrayOutputStream();
569
DataOutputStream dos = new DataOutputStream(baos);
570
Bytes.writeStringFixedSize(dos, "test", 10); // Writes "test\0\0\0\0\0\0"
571
```
572

573
## Constants and Utilities
574

575
### Size Constants
576

577
```java { .api }
578
public static final int SIZEOF_BOOLEAN = 1;
579
public static final int SIZEOF_BYTE = 1;
580
public static final int SIZEOF_CHAR = 2;
581
public static final int SIZEOF_SHORT = 2;
582
public static final int SIZEOF_INT = 4;
583
public static final int SIZEOF_FLOAT = 4;
584
public static final int SIZEOF_LONG = 8;
585
public static final int SIZEOF_DOUBLE = 8;
586
```
587

588
### Encoding Constants
589

590
```java { .api }
591
public static final String UTF8_ENCODING = "UTF-8";
592
public static final byte[] EMPTY_BYTE_ARRAY = new byte[0];
593
```
594

595
### Comparator
596

597
```java { .api }
598
/**
599
 * Optimized byte array comparator for collections
600
 */
601
public static final Comparator<byte[]> BYTES_COMPARATOR;
602
```
603

604
## Performance Considerations
605

606
### Optimization Features
607

608
- Uses optimized comparison implementations (Unsafe when available, pure Java fallback)
609
- Efficient big-endian encoding/decoding for numeric types
610
- Minimal object allocation in conversion methods
611
- Reusable comparator instances for sorted collections
612
- Lazy string generation for hex/binary representations
613

614
### Memory Efficiency
615

616
- All conversion methods create new byte arrays (no shared state)
617
- String conversions handle UTF-8 encoding efficiently
618
- ByteBuffer operations preserve original buffer state
619
- Hash computations use consistent algorithms suitable for distributed systems
620

621
### Big Data Optimizations
622

623
- Lexicographical comparison optimized for adjacent sorted data
624
- Range splitting supports MapReduce-style distributed processing
625
- Incrementation operations handle both positive and negative values
626
- Prefix operations enable efficient range scanning in key-value stores