java - Why does List.add(E) return boolean while List.Add(int, E) returns void?

Question

Looking at the javadoc I saw the that an ArrayList has an overloaded add method:

public boolean add(E e)

Appends the specified element to the end of this list.

and

public void add(int index, E element)

Inserts the specified element at the specified position in this list. Shifts the element currently at that position (if any) and any subsequent elements to the right (adds one to their indices).

I noticed that the first one returned a boolean while the second one was a void. As it turns out, the first add HAS to return a boolean because:

Returns: true (as specified by Collection.add(E))

So I went to Collection.add(E):

boolean add(E e)

Ensures that this collection contains the specified element (optional operation). Returns true if this collection changed as a result of the call. (Returns false if this collection does not permit duplicates and already contains the specified element.)

So my question is, why is add specified to return boolean instead of being a void? When I add something I would expect to only do an operation.

I understand that there's other data structures that, as opposed to ArrayList, do not allow duplicates (such as sets). But even then, couldn't the problem be solved along the lines of:

public void add(E e){
    if(e is not in set){
        add e;
    }
}

That way if e IS in the set no action is taken. Why is it better to return a boolean instead of the void approach?

Answer 1

Collection.add is a pretty generic method (not in the sense of Java generics -- in the sense of being widely applicable). As such, they wanted a return value that would apply generally.

Some classes (like ArrayList) always accept elements, and so will always return true. You're right that in these cases, a return type of void would be just as good.

But others, like Set, will sometimes not allow an element to be added. In Set's case, this happens if an equal element was already present. It's often helpful to know that. Another example is a bounded collection (that can only hold a certain number of elements).

You could ask, "can't code just check this manually?" For instance, with a set:

if (!set.contains(item)) {
    set.add(item);
    itemWasAdded(item);
}

This is more verbose than what you can do now, but not a whole lot:

if (set.add(item)) {
    itemWasAdded(item);
}

But this check-then-act behavior isn't thread safe, which can be crucial in multithreaded applications. For instance, it could be that another thread added an equal item between you checking set.contains(item) and the set.add(item) in the first code snippet. In a multithreaded scenario, those two actions really need to be a single, atomic action; returning boolean from the method makes that possible.