Primitive Collections in Eclipse Collections

1. Introduction

In this tutorial, we'll talk about primitive collections in Java and how Eclipse Collections can help.

2. Motivation

Suppose we want to create a simple list of integers:

List<Integer> myList = new ArrayList<>; 
int one = 1; 
myList.add(one);

Since collections can only hold object references, behind the scenes, the one is converted to an Integer in the process. The boxing and unboxing aren't free, of course. As a result, there's a performance loss in this process.

So, first, using primitive collections from Eclipse Collections can give us a speed boost.

Second, it reduces memory footprint. The graph below compares memory usage between the traditional ArrayList and IntArrayList from Eclipse Collections:

*Image extracted from https://www.eclipse.org/collections/#concept

And of course, let's not forget, the variety of implementations is a big seller for Eclipse Collections.

Note also that Java up to this point doesn't have support for primitive collections. However, Project Valhalla through JEP 218 aims to add it.

3. Dependencies

We'll use Maven to include the required dependencies:

<dependency>
    <groupId>org.eclipse.collections</groupId>
    <artifactId>eclipse-collections-api</artifactId>
    <version>10.0.0</version>
</dependency>

<dependency>
    <groupId>org.eclipse.collections</groupId>
    <artifactId>eclipse-collections</artifactId>
    <version>10.0.0</version>
</dependency>

4. long List

Eclipse Collections has memory-optimized lists, sets, stacks, maps, and bags for all the primitive types. Let's jump into a few examples.

First, let's take a look at a list of longs:

@Test
public void whenListOfLongHasOneTwoThree_thenSumIsSix() {
    MutableLongList longList = LongLists.mutable.of(1L, 2L, 3L);
    assertEquals(6, longList.sum());
}

5. int List

Likewise, we can create an immutable list of ints:

@Test
public void whenListOfIntHasOneTwoThree_thenMaxIsThree() {
    ImmutableIntList intList = IntLists.immutable.of(1, 2, 3);
    assertEquals(3, intList.max());
}

6. Maps

In addition to the Map interface methods, Eclipse Collections present new ones for each primitive pairing:

@Test
public void testOperationsOnIntIntMap() {
    MutableIntIntMap map = new IntIntHashMap();
    assertEquals(5, map.addToValue(0, 5));
    assertEquals(5, map.get(0));
    assertEquals(3, map.getIfAbsentPut(1, 3));
}

7. From Iterable to Primitive Collections

Also, Eclipse Collections works with Iterable:

@Test
public void whenConvertFromIterableToPrimitive_thenValuesAreEqual() {
    Iterable<Integer> iterable = Interval.oneTo(3);
    MutableIntSet intSet = IntSets.mutable.withAll(iterable);
    IntInterval intInterval = IntInterval.oneTo(3);
    assertEquals(intInterval.toSet(), intSet);
}

Further, we can create a primitive map from Iterable:

@Test
public void whenCreateMapFromStream_thenValuesMustMatch() {
    Iterable<Integer> integers = Interval.oneTo(3);
    MutableIntIntMap map = 
      IntIntMaps.mutable.from(
        integers,
        key -> key,
        value -> value * value);
    MutableIntIntMap expected = IntIntMaps.mutable.empty()
      .withKeyValue(1, 1)
      .withKeyValue(2, 4)
      .withKeyValue(3, 9);
    assertEquals(expected, map);
}

8. Streams On Primitives

Since Java already comes with primitive streams, and Eclipse Collections integrates nicely with them:

@Test
public void whenCreateDoubleStream_thenAverageIsThree() {
    DoubleStream doubleStream = DoubleLists
      .mutable.with(1.0, 2.0, 3.0, 4.0, 5.0)
      .primitiveStream();
    assertEquals(3, doubleStream.average().getAsDouble(), 0.001);
}

9. Conclusion

In conclusion, this tutorial presented primitive collections from Eclipse Collections. We demonstrated reasons to utilize it and presented how easily we can add it to our applications.

As always the code is available over on GitHub.