[Code Compare] 2. Collections.singletonList vs List.of

In this serie of posts, I'm comparing different ways to code the same functionality. Last post compared Collections.singletonList and ArrayList for creating a single-element list.

In this post I'll compare Collections.singletonList whith another well-known Factory Method, List.of.

Collections::singletonList

Method signature

public static <T> List<T> singletonList(T o)

  public static void main(String[] args) {
    final var addresses = Collections.singletonList(
        new Address(
            "742 Evergreen Terrace",
            "Springfield",
            "New York",
            "13468",
            "US"
        ));

    System.out.println(addresses);
  }

Description

This method returns an immutable list containing only the specified object. It was introduced in Java 1.3. The advantages over ArrayList were covered in the last post, but to recap:

1. Inline implementation: Initialize with the desired element in a single line.
2. Immutability: The list's size and content of its single element cannot be changed.
3. Memory Allocation: The SingletonList class contains only one field for the single element.
4. CPU usage: The SingletonList constructor accepts the single element as a parameter, requiring no resizing or array maniputalion.

List::of

Method signature

static <E> List<E> of()

  public static void main(String[] args) {
     final var addresses2 = List.of(
        new Address(
            "1007 Mountain Drive",
            "Bristol Township",
            "New Jersey",
            null,
            "US"
        ));

    System.out.println(addresses2);
  }

Description

The List.of(E e) method is also a Factory Method that returns an unmodifiable list. Unlike Collections.singletonList(E e), which supports only one element, List.of supports 0 to 10 elements, as well as arrays with multiple elements. It was introduced in Java 9, 17 years after singletonList.

It's interesting note that, unlike SingletonList, which has the comment:

Returns an immutable list containing only the specified object.

the Array.of states that it is an Unmodifiable List:

Returns an unmodifiable list containing one element.

This reflects a new understand of immutability of collections. According this documentation:

A collection is considered unmodifiable if elements cannot be added, removed, or replaced. However, an unmodifiable collection is only immutable if the elements contained in the collection are immutable.

Dispite this differences in terminology, both factory methods have almost the same functionality. Looking deeper inside the UnmodifiableList, we can find:

  static <E> List<E> of(E e1) {
      return new ImmutableCollections.List12<>(e1);
  }

What a surprise, they went with the not-so-precise term Immutable, though!

  static final class List12<E> extends     
    AbstractImmutableList<E> implements Serializable {

        @Stable
        private final E e0;

        @Stable
        private final E e1;

        List12(E e0) {
            this.e0 = Objects.requireNonNull(e0);
            this.e1 = null;
        }
        ...
    }

static abstract class AbstractImmutableList<E> extends
  AbstractImmutableCollection<E> implements List<E>, RandomAccess {

      // all mutating methods throw UnsupportedOperationException
      @Override public void    add(int index, E element) { throw uoe(); }
      @Override public boolean addAll(int index, Collection<? extends E> c) { throw uoe(); }
      @Override public E       remove(int index) { throw uoe(); }
      @Override public void    replaceAll(UnaryOperator<E> operator) { throw uoe(); }
      @Override public E       set(int index, E element) { throw uoe(); }
      @Override public void    sort(Comparator<? super E> c) { throw uoe(); }

The only difference is that List12 has two fields for potentially two elements, which also results in a negligible memory footprint unless dealing with large objects.

Conclusion

This time, we compared Collections.singletonList and List.of factory methods to create a single-element list. We discussed about the semantics of immutable and unmodifiable and showed that both methods are efficient, concise, and resource-light. If you can use a more recent Java version, it's prefferable for its familiarity, clarity and because we use List interface much more than Collections. If restritcted to an older Java version, Collections.singletonList remains a solid choice.