0
# Hash and Math
1

2
Hash functions, mathematical operations with overflow checking, and statistical utilities for precise numerical computations and data integrity verification.
3

4
## Hash Functions (com.google.common.hash)
5

6
### HashFunction and Hasher
7

8
Core interfaces for computing hash codes with various algorithms.
9

10
```java { .api }
11
import com.google.common.hash.HashFunction;
12
import com.google.common.hash.Hasher;
13
import com.google.common.hash.HashCode;
14
import com.google.common.hash.Hashing;
15
import java.nio.charset.StandardCharsets;
16

17
// Get hash functions
18
HashFunction murmur3 = Hashing.murmur3_32_fixed(); // Fixed seed Murmur3
19
HashFunction sha256 = Hashing.sha256();
20
HashFunction md5 = Hashing.md5();
21
HashFunction crc32 = Hashing.crc32();
22

23
// Simple hashing
24
HashCode hash1 = murmur3.hashString("Hello World", StandardCharsets.UTF_8);
25
HashCode hash2 = sha256.hashBytes("Hello World".getBytes(StandardCharsets.UTF_8));
26
HashCode hash3 = crc32.hashInt(42);
27
HashCode hash4 = murmur3.hashLong(123456789L);
28

29
// Using Hasher for complex objects
30
Hasher hasher = murmur3.newHasher();
31
hasher.putString("user", StandardCharsets.UTF_8);
32
hasher.putInt(25); // age
33
hasher.putLong(System.currentTimeMillis()); // timestamp
34
hasher.putBytes("additional data".getBytes());
35
HashCode complexHash = hasher.hash();
36

37
// Hash code representations
38
String hexString = hash1.toString(); // Hex representation
39
byte[] bytes = hash1.asBytes(); // Raw bytes
40
int intValue = hash1.asInt(); // As 32-bit int (if hash is 32-bit)
41
long longValue = hash1.asLong(); // As 64-bit long (if hash is 64-bit or larger)
42

43
// Hash function properties
44
int bits = murmur3.bits(); // Number of bits in hash (32 for murmur3_32)
45
boolean goodForSigning = sha256.bits() >= 256; // Cryptographically secure
46
```
47

48
### Available Hash Functions
49

50
Comprehensive set of hash functions for different use cases.
51

52
```java { .api }
53
// Non-cryptographic hash functions (fast, good distribution)
54
HashFunction murmur3_32 = Hashing.murmur3_32(); // 32-bit Murmur3
55
HashFunction murmur3_32_fixed = Hashing.murmur3_32_fixed(); // Fixed seed
56
HashFunction murmur3_128 = Hashing.murmur3_128(); // 128-bit Murmur3
57
HashFunction sipHash24 = Hashing.sipHash24(); // SipHash-2-4
58

59
// Cryptographic hash functions (secure but slower)
60
HashFunction md5 = Hashing.md5(); // MD5 (128-bit, deprecated for security)
61
HashFunction sha1 = Hashing.sha1(); // SHA-1 (160-bit, deprecated for security)
62
HashFunction sha256 = Hashing.sha256(); // SHA-256 (256-bit, secure)
63
HashFunction sha384 = Hashing.sha384(); // SHA-384 (384-bit, secure)
64
HashFunction sha512 = Hashing.sha512(); // SHA-512 (512-bit, secure)
65

66
// Checksums
67
HashFunction crc32 = Hashing.crc32(); // CRC32 checksum
68
HashFunction crc32c = Hashing.crc32c(); // CRC32C checksum
69

70
// Good general-purpose hash function
71
HashFunction good = Hashing.goodFastHash(32); // Good 32-bit hash
72
HashFunction good128 = Hashing.goodFastHash(128); // Good 128-bit hash
73

74
// Use cases:
75
// - Hash tables, bloom filters: murmur3_32, goodFastHash
76
// - Checksums, data integrity: crc32, crc32c
77
// - Cryptographic signatures: sha256, sha512
78
// - Consistent hashing: murmur3_128
79
```
80

81
### Funnels
82

83
Type-safe way to feed data into hash functions.
84

85
```java { .api }
86
import com.google.common.hash.Funnel;
87
import com.google.common.hash.Funnels;
88
import com.google.common.hash.PrimitiveSink;
89

90
// Built-in funnels for common types
91
Funnel<byte[]> byteArrayFunnel = Funnels.byteArrayFunnel();
92
Funnel<String> stringFunnel = Funnels.stringFunnel(StandardCharsets.UTF_8);
93
Funnel<Integer> integerFunnel = Funnels.integerFunnel();
94
Funnel<Long> longFunnel = Funnels.longFunnel();
95

96
// Using funnels with hash functions
97
HashFunction hasher = Hashing.murmur3_32();
98
HashCode stringHash = hasher.hashObject("Hello", stringFunnel);
99
HashCode intHash = hasher.hashObject(42, integerFunnel);
100

101
// Custom funnel for complex objects
102
public class Person {
103
    private final String name;
104
    private final int age;
105
    private final String email;
106
    
107
    // Constructor, getters...
108
    
109
    public static final Funnel<Person> FUNNEL = new Funnel<Person>() {
110
        @Override
111
        public void funnel(Person person, PrimitiveSink into) {
112
            into.putString(person.name, StandardCharsets.UTF_8)
113
                .putInt(person.age)
114
                .putString(person.email, StandardCharsets.UTF_8);
115
        }
116
    };
117
}
118

119
// Use custom funnel
120
Person person = new Person("John", 30, "john@example.com");
121
HashCode personHash = murmur3.hashObject(person, Person.FUNNEL);
122

123
// Sequential funnel for collections
124
Funnel<Iterable<String>> listFunnel = Funnels.sequentialFunnel(stringFunnel);
125
List<String> names = Arrays.asList("Alice", "Bob", "Charlie");
126
HashCode listHash = murmur3.hashObject(names, listFunnel);
127
```
128

129
### BloomFilter
130

131
Probabilistic data structure for testing set membership with configurable false positive rate.
132

133
```java { .api }
134
import com.google.common.hash.BloomFilter;
135

136
// Create bloom filter for strings
137
BloomFilter<String> bloomFilter = BloomFilter.create(
138
    Funnels.stringFunnel(StandardCharsets.UTF_8),
139
    1000,    // Expected number of insertions
140
    0.01     // Desired false positive probability (1%)
141
);
142

143
// Add elements
144
bloomFilter.put("apple");
145
bloomFilter.put("banana");
146
bloomFilter.put("cherry");
147

148
// Test membership
149
boolean mightContain1 = bloomFilter.mightContain("apple");  // true (definitely in set)
150
boolean mightContain2 = bloomFilter.mightContain("grape");  // false (definitely not in set)
151
boolean mightContain3 = bloomFilter.mightContain("date");   // might be false positive
152

153
// Bloom filter for custom objects
154
BloomFilter<Person> personFilter = BloomFilter.create(
155
    Person.FUNNEL,
156
    10000,   // Expected 10,000 people
157
    0.001    // 0.1% false positive rate
158
);
159

160
personFilter.put(new Person("Alice", 25, "alice@example.com"));
161
boolean found = personFilter.mightContain(new Person("Bob", 30, "bob@example.com"));
162

163
// Monitor bloom filter performance
164
double fpp = bloomFilter.expectedFpp(); // Current false positive probability
165
long approximateCount = bloomFilter.approximateElementCount(); // Estimated elements added
166

167
// Combining bloom filters (union operation)
168
BloomFilter<String> filter1 = BloomFilter.create(stringFunnel, 100, 0.01);
169
BloomFilter<String> filter2 = BloomFilter.create(stringFunnel, 100, 0.01);
170

171
filter1.put("a");
172
filter2.put("b");
173

174
filter1.putAll(filter2); // filter1 now contains elements from both filters
175
```
176

177
### Hash Utilities
178

179
Utility methods for combining and manipulating hash codes.
180

181
```java { .api }
182
// Combining hash codes
183
HashCode hash1 = Hashing.sha256().hashString("part1", StandardCharsets.UTF_8);
184
HashCode hash2 = Hashing.sha256().hashString("part2", StandardCharsets.UTF_8);
185

186
// Ordered combination (order matters)
187
HashCode combined = Hashing.combineOrdered(Arrays.asList(hash1, hash2));
188

189
// Unordered combination (order doesn't matter)  
190
HashCode combinedUnordered = Hashing.combineUnordered(Arrays.asList(hash1, hash2));
191

192
// Consistent hashing (for distributed systems)
193
int bucket = Hashing.consistentHash(hash1, 100); // Map to bucket 0-99
194
int bucket2 = Hashing.consistentHash(hash1.asLong(), 100); // Alternative
195

196
// Creating hash codes from existing values
197
HashCode fromInt = HashCode.fromInt(42);
198
HashCode fromLong = HashCode.fromLong(123456789L);
199
HashCode fromBytes = HashCode.fromBytes(new byte[]{1, 2, 3, 4});
200
HashCode fromString = HashCode.fromString("deadbeef"); // From hex string
201
```
202

203
## Mathematical Utilities (com.google.common.math)
204

205
### Integer Math
206

207
Safe mathematical operations on integers with overflow checking.
208

209
```java { .api }
210
import com.google.common.math.IntMath;
211
import java.math.RoundingMode;
212

213
// Checked arithmetic (throws ArithmeticException on overflow)
214
int sum = IntMath.checkedAdd(Integer.MAX_VALUE - 1, 1); // OK
215
// int overflow = IntMath.checkedAdd(Integer.MAX_VALUE, 1); // Throws ArithmeticException
216

217
int difference = IntMath.checkedSubtract(100, 50); // 50
218
int product = IntMath.checkedMultiply(1000, 1000); // 1,000,000
219
int power = IntMath.checkedPow(2, 10); // 1024
220

221
// Mathematical operations
222
int gcd = IntMath.gcd(48, 18); // 6 (greatest common divisor)
223
int mod = IntMath.mod(-5, 3); // 1 (always non-negative result)
224
int pow = IntMath.pow(3, 4); // 81
225

226
// Square root with rounding
227
int sqrt1 = IntMath.sqrt(15, RoundingMode.DOWN); // 3
228
int sqrt2 = IntMath.sqrt(15, RoundingMode.UP); // 4
229
int sqrt3 = IntMath.sqrt(16, RoundingMode.EXACT); // 4 (exact)
230

231
// Logarithms
232
int log2 = IntMath.log2(8, RoundingMode.EXACT); // 3
233
int log10 = IntMath.log10(1000, RoundingMode.EXACT); // 3
234
int log2Rounded = IntMath.log2(15, RoundingMode.UP); // 4
235

236
// Factorial
237
int factorial5 = IntMath.factorial(5); // 120
238
int factorial0 = IntMath.factorial(0); // 1
239

240
// Binomial coefficient (n choose k)
241
int binomial = IntMath.binomial(10, 3); // 120 (10 choose 3)
242

243
// Power of two operations
244
boolean isPowerOfTwo = IntMath.isPowerOfTwo(16); // true
245
int nextPowerOfTwo = IntMath.ceilingPowerOfTwo(15); // 16
246
int prevPowerOfTwo = IntMath.floorPowerOfTwo(15); // 8
247

248
// Mean calculation (avoids overflow)
249
int mean = IntMath.mean(1000000000, 2000000000); // Doesn't overflow
250
```
251

252
### Long Math
253

254
Similar mathematical operations for long values.
255

256
```java { .api }
257
import com.google.common.math.LongMath;
258

259
// Checked arithmetic for longs
260
long checkedSum = LongMath.checkedAdd(Long.MAX_VALUE - 1, 1);
261
long checkedProduct = LongMath.checkedMultiply(1000000L, 1000000L);
262
long checkedPower = LongMath.checkedPow(2L, 62);
263

264
// Mathematical operations
265
long gcd = LongMath.gcd(123456789L, 987654321L);
266
long mod = LongMath.mod(-15L, 7L); // 6
267
long pow = LongMath.pow(10L, 9); // 1,000,000,000
268

269
// Square root and logarithms
270
long sqrt = LongMath.sqrt(1000000L, RoundingMode.DOWN); // 1000
271
long log2 = LongMath.log2(1024L, RoundingMode.EXACT); // 10
272
long log10 = LongMath.log10(1000000L, RoundingMode.EXACT); // 6
273

274
// Large factorials (as long as they fit in long)
275
long factorial10 = LongMath.factorial(10); // 3,628,800
276
long factorial20 = LongMath.factorial(20); // 2,432,902,008,176,640,000
277

278
// Binomial coefficients
279
long binomial = LongMath.binomial(20, 10); // 184,756
280

281
// Power of two operations
282
boolean isPowerOfTwo = LongMath.isPowerOfTwo(1024L); // true
283
long mean = LongMath.mean(1000000000000L, 2000000000000L);
284
```
285

286
### Double Math
287

288
Mathematical operations on double values with proper rounding and precision handling.
289

290
```java { .api }
291
import com.google.common.math.DoubleMath;
292
import java.math.BigInteger;
293

294
// Rounding operations
295
int roundedToInt = DoubleMath.roundToInt(3.7, RoundingMode.HALF_UP); // 4
296
long roundedToLong = DoubleMath.roundToLong(3.14159, RoundingMode.DOWN); // 3
297
BigInteger roundedToBigInt = DoubleMath.roundToBigInteger(1.23e15, RoundingMode.UP);
298

299
// Logarithms
300
double log2 = DoubleMath.log2(8.0); // 3.0
301
double log2Approx = DoubleMath.log2(10.0); // ~3.3219
302

303
// Factorial as double (for larger values)
304
double factorial100 = DoubleMath.factorial(100); // Very large number
305

306
// Fuzzy comparison (with tolerance)
307
boolean equal = DoubleMath.fuzzyEquals(3.14159, 3.14160, 0.001); // true
308
int comparison = DoubleMath.fuzzyCompare(3.14, 3.15, 0.1); // 0 (equal within tolerance)
309

310
// Mathematical properties
311
boolean isInteger = DoubleMath.isMathematicalInteger(3.0); // true
312
boolean isInteger2 = DoubleMath.isMathematicalInteger(3.1); // false
313
boolean isPowerOfTwo = DoubleMath.isPowerOfTwo(8.0); // true
314

315
// Finite check
316
boolean isFinite = DoubleMath.isFinite(3.14); // true
317
boolean isFinite2 = DoubleMath.isFinite(Double.POSITIVE_INFINITY); // false
318
```
319

320
### BigInteger Math
321

322
Mathematical operations on BigInteger values for arbitrary precision.
323

324
```java { .api }
325
import com.google.common.math.BigIntegerMath;
326
import java.math.BigInteger;
327

328
// Square root
329
BigInteger big = new BigInteger("1000000000000000000000"); // 10^21
330
BigInteger sqrt = BigIntegerMath.sqrt(big, RoundingMode.DOWN);
331

332
// Logarithms  
333
BigInteger large = new BigInteger("1024");
334
int log2 = BigIntegerMath.log2(large, RoundingMode.EXACT); // 10
335
int log10 = BigIntegerMath.log10(new BigInteger("1000"), RoundingMode.EXACT); // 3
336

337
// Factorial (can handle very large values)
338
BigInteger factorial50 = BigIntegerMath.factorial(50);
339
BigInteger factorial100 = BigIntegerMath.factorial(100);
340

341
// Binomial coefficient
342
BigInteger binomial = BigIntegerMath.binomial(100, 50); // 100 choose 50
343

344
// Power of two test
345
boolean isPowerOfTwo = BigIntegerMath.isPowerOfTwo(new BigInteger("1024")); // true
346

347
// Divide and round
348
BigInteger dividend = new BigInteger("1000");
349
BigInteger divisor = new BigInteger("3");
350
BigInteger quotient = BigIntegerMath.divide(dividend, divisor, RoundingMode.UP); // 334
351
```
352

353
### Statistics
354

355
Statistical operations and data analysis utilities.
356

357
```java { .api }
358
import com.google.common.math.Stats;
359
import com.google.common.math.StatsAccumulator;
360
import com.google.common.math.PairedStats;
361
import com.google.common.math.PairedStatsAccumulator;
362

363
// Creating statistics from data
364
double[] values = {1.0, 2.0, 3.0, 4.0, 5.0};
365
Stats stats = Stats.of(values);
366

367
// Basic statistics
368
long count = stats.count(); // 5
369
double mean = stats.mean(); // 3.0
370
double sum = stats.sum(); // 15.0
371
double min = stats.min(); // 1.0
372
double max = stats.max(); // 5.0
373

374
// Variance and standard deviation
375
double popVariance = stats.populationVariance(); // Population variance
376
double popStdDev = stats.populationStandardDeviation(); // Population std dev
377
double sampleVariance = stats.sampleVariance(); // Sample variance  
378
double sampleStdDev = stats.sampleStandardDeviation(); // Sample std dev
379

380
// Accumulating statistics incrementally
381
StatsAccumulator accumulator = new StatsAccumulator();
382
accumulator.add(1.0);
383
accumulator.add(2.0, 3.0, 4.0); // Add multiple values
384
accumulator.addAll(Arrays.asList(5.0, 6.0)); // Add from collection
385

386
Stats incrementalStats = accumulator.snapshot(); // Get current stats
387

388
// Paired statistics (for correlation analysis)
389
double[] xValues = {1.0, 2.0, 3.0, 4.0, 5.0};
390
double[] yValues = {2.0, 4.0, 6.0, 8.0, 10.0};
391

392
PairedStatsAccumulator pairedAccumulator = new PairedStatsAccumulator();
393
for (int i = 0; i < xValues.length; i++) {
394
    pairedAccumulator.add(xValues[i], yValues[i]);
395
}
396

397
PairedStats pairedStats = pairedAccumulator.snapshot();
398

399
// Individual variable statistics
400
Stats xStats = pairedStats.xStats();
401
Stats yStats = pairedStats.yStats();
402

403
// Correlation analysis
404
double correlation = pairedStats.pearsonsCorrelationCoefficient(); // 1.0 (perfect positive)
405

406
// Linear regression
407
PairedStats.LinearTransformation regression = pairedStats.leastSquaresFit();
408
double slope = regression.slope(); // 2.0
409
double intercept = regression.intercept(); // 0.0
410

411
// Predict y value for given x
412
double predicted = regression.transform(3.5); // 7.0
413
```
414

415
### Quantiles
416

417
Computing percentiles, quartiles, and other quantiles from data.
418

419
```java { .api }
420
import com.google.common.math.Quantiles;
421

422
double[] data = {1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0, 9.0, 10.0};
423

424
// Median (50th percentile)
425
double median = Quantiles.median().compute(data); // 5.5
426

427
// Quartiles
428
Map<Integer, Double> quartiles = Quantiles.quartiles().compute(data);
429
double q1 = quartiles.get(1); // 25th percentile (3.25)
430
double q2 = quartiles.get(2); // 50th percentile (5.5) - same as median  
431
double q3 = quartiles.get(3); // 75th percentile (7.75)
432

433
// Percentiles
434
Map<Integer, Double> percentiles = Quantiles.percentiles().compute(data);
435
double p10 = percentiles.get(10); // 10th percentile
436
double p90 = percentiles.get(90); // 90th percentile
437

438
// Custom quantile scale
439
Quantiles.ScaleAndIndex scale = Quantiles.scale(100); // Percentiles (0-100)
440
double p95 = scale.index(95).compute(data); // 95th percentile
441

442
// Multiple quantiles at once
443
Map<Integer, Double> deciles = Quantiles.scale(10).indexes(1, 2, 3, 4, 5, 6, 7, 8, 9)
444
    .compute(data); // 10th, 20th, ..., 90th percentiles
445

446
// Working with collections
447
List<Double> dataList = Arrays.asList(1.0, 2.0, 3.0, 4.0, 5.0);
448
double medianFromList = Quantiles.median().compute(dataList);
449
```
450

451
### Practical Applications
452

453
Real-world examples combining hash and math utilities.
454

455
```java { .api }
456
// Data integrity verification
457
public class DataVerifier {
458
    private final HashFunction hashFunction = Hashing.sha256();
459
    
460
    public String computeChecksum(File file) throws IOException {
461
        HashCode hash = Files.asByteSource(file).hash(hashFunction);
462
        return hash.toString();
463
    }
464
    
465
    public boolean verifyIntegrity(File file, String expectedChecksum) throws IOException {
466
        String actualChecksum = computeChecksum(file);
467
        return actualChecksum.equals(expectedChecksum);
468
    }
469
}
470

471
// Consistent hashing for load balancing
472
public class ConsistentHashLoadBalancer {
473
    private final List<String> servers;
474
    private final HashFunction hashFunction = Hashing.murmur3_32();
475
    
476
    public ConsistentHashLoadBalancer(List<String> servers) {
477
        this.servers = ImmutableList.copyOf(servers);
478
    }
479
    
480
    public String selectServer(String key) {
481
        HashCode hash = hashFunction.hashString(key, StandardCharsets.UTF_8);
482
        int bucket = Hashing.consistentHash(hash, servers.size());
483
        return servers.get(bucket);
484
    }
485
}
486

487
// Mathematical analysis with overflow protection
488
public class SafeCalculator {
489
    
490
    public OptionalLong safeMultiply(int... values) {
491
        try {
492
            long result = 1L;
493
            for (int value : values) {
494
                result = LongMath.checkedMultiply(result, value);
495
            }
496
            return OptionalLong.of(result);
497
        } catch (ArithmeticException e) {
498
            return OptionalLong.empty(); // Overflow occurred
499
        }
500
    }
501
    
502
    public Stats analyzeDataset(double[] values) {
503
        Stats stats = Stats.of(values);
504
        
505
        System.out.println("Dataset Analysis:");
506
        System.out.println("Count: " + stats.count());
507
        System.out.println("Mean: " + stats.mean());
508
        System.out.println("Std Dev: " + stats.populationStandardDeviation());
509
        
510
        // Detect outliers (values more than 2 std devs from mean)
511
        double threshold = 2.0 * stats.populationStandardDeviation();
512
        List<Double> outliers = Arrays.stream(values)
513
            .filter(v -> Math.abs(v - stats.mean()) > threshold)
514
            .boxed()
515
            .collect(Collectors.toList());
516
        
517
        System.out.println("Outliers: " + outliers);
518
        
519
        return stats;
520
    }
521
}
522

523
// Bloom filter for duplicate detection
524
public class DuplicateDetector<T> {
525
    private final BloomFilter<T> bloomFilter;
526
    private final Set<T> confirmedItems = new HashSet<>();
527
    
528
    public DuplicateDetector(Funnel<T> funnel, int expectedItems) {
529
        this.bloomFilter = BloomFilter.create(funnel, expectedItems, 0.01);
530
    }
531
    
532
    public boolean addIfAbsent(T item) {
533
        if (bloomFilter.mightContain(item)) {
534
            // Might be duplicate, check actual set
535
            if (confirmedItems.contains(item)) {
536
                return false; // Confirmed duplicate
537
            }
538
        }
539
        
540
        // Add to both bloom filter and confirmed set
541
        bloomFilter.put(item);
542
        confirmedItems.add(item);
543
        return true; // Successfully added
544
    }
545
}
546
```
547

548
Guava's hash and math utilities provide robust, efficient solutions for data integrity, mathematical computations, and statistical analysis with proper error handling and precision control.