Java – Return Value of Collection.add() vs Map.put()

api-designjava

In Java, Collection.add() returns a boolean which is true if the added element wasn't present in the set whereas Map.put() returns the value that was previously associated with the key (or null if there was none).

Is there any reason that aren't implemented the same way (e.g. both returning boolean)?

Best Answer

I assume you mean Map.put - because there is no Map.add. But even if they had the same name - these methods behave differently enough to render any attempt to unify their interface meaningless.

Look at the way Collection.add's return value's doc is worded:

true if this collection changed as a result of the call

Now, the only valid reason for the collection to not change is if it's a set and the item is already in there(any other reason should throw), but that wording was chosen because it makes sense for all collections, without having to make special clauses for sets and not-sets.

But does it make sense for maps? Consider this:

HashMap<Integer, Integer> map = new HashMap<Integer, Integer>();
map.put(1, 2);
map.put(2, 2);

/*case 1*/ map.put(1, 1); // value changed - would have returned `true`
/*case 2*/ map.put(2, 2); // nothing changed - would have returned `false`
/*case 3*/ map.put(3, 3); // key-value pair added - would have returned `true`

Case 1 and 3 both return true, but they are very different - one is overriding an entry and the other adding a new one. So maybe case 1 should have returned false? But then it would have been the same as case 2, even though one is changing the map and the other doesn't...

So, copying Collection.add's behavior to Map.put makes no sense. How about copying Map.put's behavior to Collection.add? What if we had Collection.add return the old value?

I see several problems with that:

  1. It makes the interface more complicated - now it needs to give different definitions for maps and sets, or make a more complex definition(e.g. - "if the item was not added because it was already there, return the item that was already there". Ugh...)
  2. It's not very useful. You already have the item that's already in the collection - you just sent it as an argument to add!

  3. What if we have a TreeSet with a custom comparator?

    TreeSet<Integer> treeSet = new TreeSet<Integer>((a, b) -> Integer.compare(a % 10, b % 10));

treeSet.add(11);
treeSet.add(21); // should this return `11` or `21`?

    This is not a problem with Map, because it's looking by the key, and is already forced to define what you get when you request for that key.

  4. It forces the collection to actually retrieve the value. What if the Collection implementation is a bloom filter? It now has to actually look for the object instead of doing a quick hash match. What if it's a wrapper around a database table? It now has to create an object that you already have!

    Of course, Map would have a similar problem - but at least there the old value is important, because you don't know what it is and it's going to disappear. But with Collection? It's all cost and no gain...

Related Topic