High Performance Primitive Collections (HPPC) library provides typical data structures (lists, stacks, maps) template-generated for all Java primitive types (byte, int, etc.) to conserve memory and boost performance.

Why HPPC?

The Java Collections package is in many ways excellent, but it cannot be used for primitive types and autoboxing introduced in Java 1.5 kills the runtime performance (increased memory use, garbage collector overhead).

This library has different design goals than Java Collections (and many other collection packages). For example, the internals of each class are open and subject to free hacking and tuning up to one's wishes.

Why not other primitive collection libraries?

There are a few projects implementing collections over primitive types: fastutil, PCJ, GNU Trove, Apache Mahout (ported COLT collections), Apache Primitive Collections.

Some of these are LGPL-ed, a license type many commercial companies tend to avoid at all costs; other projects above are no longer maintained or complete. There is also a tendency to write tightly encapsulated code (private internals), implementing the API of standard Java packages and striving for fast error-recovery. Although these are good programming practices, they are not always practical (in many computationally intense applications access to the collection class' internals is a bliss). HPPC has a slightly different set of goals. If you need Java collections compliance, try fastutil, it is very, very good.

Assumptions and goals of HPPC

We assume that:

From these assumptions stem the following design drivers:

Design and implementation assumptions

Interfaces and their relation to Java Collections API

HPPC is not strictly modeled after Java Collections API, although we did try to make the APIs look similar enough for comfortable use. One particular thing largerly missing in HPPC are view projections (sublists or views over the collection of keys or values). Certain classes provide such views (like {@linkplain com.carrotsearch.hppc.ObjectObjectOpenHashMap ObjectObjectOpenHashMap}), but for the most part, specific methods are provided that accept ranges or closure-like filters. If performance is still unsatisfactory, the internals of each class are available for direct manipulation.

Rough relationships between Java Collections classes and HPPC classes are presented in the table below.

Relationships between HPPC and Java Collections.
Java Collections HPPC (primitives) HPPC (generics)
bit sets java.util.BitSet BitSet n/a
array-backed lists java.util.ArrayList, java.util.Vector [type]ArrayList {@linkplain com.carrotsearch.hppc.ObjectArrayList ObjectArrayList<T>}
stacks java.util.Stack [type]Stack {@linkplain com.carrotsearch.hppc.ObjectStack ObjectStack<T>}
deques java.util.ArrayDeque [type]ArrayDeque {@linkplain com.carrotsearch.hppc.ObjectArrayDeque ObjectArrayDeque<T>}
hash maps (dictionaries) java.util.HashMap [keyType][valueType]OpenHashMap {@linkplain com.carrotsearch.hppc.ObjectObjectOpenHashMap ObjectObjectOpenHashMap<K, V>}
[keyType]ObjectOpenHashMap<V>
Object[valueType]OpenHashMap<K>

The method-level API of the corresponding types is also similar, but distinct differences exist (consult the JavaDoc of each class).

Interfaces and container inheritance

HPPC's interfaces are modeled to encapsulate the common functionality enforced from all the classes that implement a given interface. The interface hierarchy is loosely inspired by STL.

An overview of interfaces and their relationship to data structures implemented in HPPC is depicted graphically in {@link com.carrotsearch.hppc.ObjectContainer}.