1

In PriorityQueue class description in oracle, specifically about method add, the page says about add's return value:

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

Does it mean that this method always returns true?

Thanks in advance !

Link to class description: https://docs.oracle.com/javase/7/docs/api/java/util/PriorityQueue.html

guyr79
  • 169
  • 1
  • 11
  • it can return true. It can also throw an Exception, in which case, it won't return anything – Stultuske Aug 21 '19 at 07:44
  • It's funny that the title says, "Can it return false?" and inside your description you ask, "Does it always return true?" So if somebody were to answer "Yes," then he'd be right ... or wrong ... depending on which question he answered. You should take care in the future to be consistent with how you ask your questions. – Jim Mischel Aug 21 '19 at 14:48
  • @Jim Mischel, thank you for your comment. Will take notice of it – guyr79 Aug 21 '19 at 15:32

2 Answers2

2

If you clicked on the link in the documentation you would read what Collection.add says about the return value:

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 the contract for the return value is that it must always return true except if:

  1. The collection does not allow duplicates
  2. The element is already present

Does the PriorityQueue permit duplicates? Yes. Hence it can never return false.

Giacomo Alzetta
  • 2,431
  • 6
  • 17
  • you forgot the except "when an exception is thrown" – Stultuske Aug 21 '19 at 07:45
  • @Stultuske Are you saying that when an exception is thrown the method returns `false`? – Giacomo Alzetta Aug 21 '19 at 07:45
  • 2
    no, when an exeption is thrown it returns neither true nor false. It throws an exception – Tim Aug 21 '19 at 07:46
  • what @TimCastelijns said. You stated that it must always return true except in case it doesn't allow duplicates and it would be a duplicate. Which is incomplete. It doesn't return true in case of an exception being thrown, which was my point. – Stultuske Aug 21 '19 at 07:48
  • @Stultuske The value returned is always relevant if the function returns at all, so I believe the statement is self-explaining as the documentation is. – Giacomo Alzetta Aug 21 '19 at 12:36
  • @GiacomoAlzetta yes, but according to your explanation, there is always a value returned. again, I don't disagree with the explanation of true/false, I 'm merely stating it's incomplete – Stultuske Aug 21 '19 at 13:00
  • Giacomo Alzetta, thank you for the fast reply and coherent answer! – guyr79 Aug 21 '19 at 15:34
2

The method add is defined as

public boolean add(E e) {
    return offer(e);
}

The method offer is defined as

public boolean offer(E e) {
    if (e == null)
        throw new NullPointerException();
    modCount++;
    int i = size;
    if (i >= queue.length)
        grow(i + 1);
    size = i + 1;
    if (i == 0)
        queue[0] = e;
    else
        siftUp(i, e);
    return true;
}

So the answer to your question is yes. This current implementation always returns true unless an exception is thrown.

The contract of Collection#add says the method returns "true if this collection changed as a result of the call". Since PriorityQueue isn't a final class and it may have children, we can't say "it will never return false". I may implement a bounded PriorityQueue. I may come up with a PriorityQueue that rejects particular values or doesn't accept new values at all.

PriorityQueue<Integer> queue = new PriorityQueue<Integer>() {
  @Override
  public boolean add(Integer integer) {
    super.add(integer);
    return false;
  }
};
Andrew Tobilko
  • 48,120
  • 14
  • 91
  • 142