Why Java’s Sets Disagree About BigDecimal Duplicates
The same BigDecimal inputs can produce different HashSet and TreeSet sizes. Trace scale, equality and comparison before choosing a duplicate policy.
Two decimals go into a set. In one implementation you get two entries; in another you get one. Before looking for a lost insert, check whether those decimals have different scales. With BigDecimal, 2.0 and 2.00 compare as the same numerical value, but equals considers them different. A HashSet uses equality; a naturally ordered TreeSet uses comparison to decide whether an entry is already present.
This is an AI-prepared, documentation-based explainer, not a personally reproduced incident. The Java examples are illustrative and were not executed for this article. See the editorial policy.
The collection swap changed what “duplicate” means
Imagine a service collecting decimal measurements from two imports. One source sends "2.0", the other "2.00". A developer swaps a hash set for a tree set so the results come out sorted. There’s no new rounding code. There’s no floating-point conversion. Yet the number of unique entries changes. A sorting request has quietly acquired opinions about identity.
Try this illustrative example with your application’s JDK:
import java.math.BigDecimal;
import java.util.HashSet;
import java.util.List;
import java.util.TreeSet;
var a = new BigDecimal("2.0");
var b = new BigDecimal("2.00");
var values = List.of(a, b);
System.out.println(a.scale()); // expected: 1
System.out.println(b.scale()); // expected: 2
System.out.println(a.equals(b)); // expected: false
System.out.println(a.compareTo(b)); // expected: 0
System.out.println(new HashSet<>(values).size()); // expected: 2
System.out.println(new TreeSet<>(values).size()); // expected: 1The BigDecimal API describes a decimal in terms of an unscaled integer and a scale. The two inputs represent the same number but carry different scales. Its equality and hash-code rules account for that representation; its natural comparison groups numerically equal representations together. String constructors keep binary floating-point conversion out of this example. Switching to double would introduce a different problem, not settle this policy.
Ask the collection which relationship it uses
HashSet determines membership using equality, with hash codes supporting lookup. TreeSet uses its comparator, or natural ordering when no comparator is supplied. When comparison returns zero, the tree treats the entries as equivalent for membership. Hash-code collisions aren't the explanation here: a hash set can retain distinct objects whose hashes collide.
Before changing the implementation again, trace the collection at the boundary where the count changes. Inspect how each decimal was constructed and its scale, then compare equals and compareTo on the same pair. Check any supplied comparator too: a comparator that only examines part of an object can collapse entries for an entirely different reason. A map keyed by decimals deserves the same review when moving between hash-based and sorted implementations.
Java’s Comparable contract explicitly names BigDecimal as an exception to the recommendation that natural ordering be consistent with equality. TreeSet’s documentation also warns that an ordering inconsistent with equality doesn’t obey the general Set contract, even though the tree’s own behavior is defined. Treating those collections as interchangeable can therefore create surprises beyond the size of one result.
Choose identity first, then sorting
If 2.0 and 2.00 must remain distinct, preserve scale-sensitive identity. You can keep them in a hash set and sort a separate list for presentation. If a sorted set is essential, a comparator that compares numerical value first and scale second distinguishes these representations:
import java.util.Comparator;
Comparator<BigDecimal> valueThenScale =
Comparator.<BigDecimal>naturalOrder()
.thenComparingInt(BigDecimal::scale);
var representations = new TreeSet<BigDecimal>(valueThenScale);
representations.addAll(values); // expected size: 2That choice is specifically about BigDecimal value-and-scale identity. It doesn't preserve separate source records that happen to contain equal decimals; those records need their own identifiers.
If numerical identity is the intended rule instead, make it explicit at the boundary where keys enter the system. One option is to canonicalize every key with stripTrailingZeros() before using hash-based storage or lookup. Apply the same normalization to insertion, lookup and removal. Normalizing only the import path leaves a rather polite bug waiting at the next lookup.
That method can produce a negative scale: the API’s example turns 600.0 into 6E+2. Keep display formatting separate, and check downstream serialization and scale validation. If your domain requires a fixed scale, an explicit setScale policy may fit better; choose the rounding behavior deliberately. Neither a universal two-decimal rule nor indiscriminate zero stripping is an identity policy for every measurement.
Make the regression check about meaning
Test pairs with equal numerical value and different scales, unequal numerical values, zero representations and negative values. For each collection or key wrapper, assert the intended insert count and membership behavior, including a lookup constructed through a different input path. If the count must be stable when you change collection types, test that requirement directly.
For a separate collection boundary, Debugly’s Stream.toList() mutability explainer shows why an apparently convenient implementation swap can change another contract. Here the contract to write down is smaller: does a duplicate mean the same number, the same number and scale, or the same source record? Once that answer is explicit, the collection choice stops making it on your behalf.