What's the difference between peekOption and headOption in Vavr Collection

Question

Here the doc for Vavr List peekOption

https://www.javadoc.io/doc/io.vavr/vavr/0.10.1/io/vavr/collection/List.html#peekOption--

Here the doc of Vavr Traversable headOption

https://www.javadoc.io/doc/io.vavr/vavr/0.10.1/io/vavr/collection/Traversable.html#headOption--

Implémentation seems exactly the same so with that kind of usage i can use both but which is the best..?

MyObject myObject = myJavaCollection.stream()
.filter(SomePredicate::isTrue)
.collect(io.vavr.collection.List.collector()) //Collect to vavr list to have vavr methods availables
.peek(unused -> LOGGER.info("some log"))
.map(MyObject::new)
.peekOption() //or .headOption()
.getOrNull();

So i was wondering what is the différence between those methods.

Answer 1

According to their documentation (List and Traversable)

List's peekOption

default Option peekOption()

Returns the head element without modifying the List.

Returns: None if this List is empty, otherwise a Some containing the head element

Traversable's headOption

default Option headOption()

Returns the first element of a non-empty Traversable as Option.

Returns: Some(element) or None if this is empty.

They act exactly the same way. They either return the head element or Option.none(). Only their variants head and peek throw an exception if no elements are present. List simply happens to have two methods that behave the same way only because it extends the Traversable interface.

Answer 2

From the sourcecode of Vavr's List (see https://github.com/vavr-io/vavr/blob/master/src/main/java/io/vavr/collection/List.java) we have:

/**
 * Returns the head element without modifying the List.
 *
 * @return {@code None} if this List is empty, otherwise a {@code Some} containing the head element
 * @deprecated use headOption() instead
 */
@Deprecated
public final Option<T> peekOption() {
    return headOption();
}

So they do exactly the same, like you say, and since peekOption() is deprecated, headOption() seems to be the one to use.

---

As for the reason to use one over the other:

It looks like the Vavr List interface defines some stack related methods (like push, pop, peek, etc) to make it easier to use lists as stacks in a convenient way, if you should want that. (For example, you would use peekOption() if you consider the list to be a stack and headOption() otherwise)

These stack-methods are however all deprecated - probably because there are always non-stack methods that can be used instead of them. So they probably backed away from the idea that "a list is also a stack" - maybe because they thought it mixes concepts a bit and makes the interface too big (just a guess). So that must be the reason headOption() is preferred - all the stack-methods are deprecated.

(Normal Java Lists also have stack methods, but that is through an interface, so all lists are also stacks but you can have a stack which is not a list.))