tessl/maven-it-unimi-dsi--fastutil
High-performance type-specific collections extending the Java Collections Framework with memory-efficient primitive containers and big data structures.
—
Pending
type-specific-collections.mddocs/
Type-Specific Collections
High-performance primitive collections for int, long, double, float, char, short, byte, and boolean types. These collections avoid the boxing/unboxing overhead of standard Java collections by working directly with primitive values while maintaining compatibility with standard collection interfaces.
Overview
Each primitive type has its own dedicated package with complete collection implementations:
it.unimi.dsi.fastutil.ints- Integer collectionsit.unimi.dsi.fastutil.longs- Long collectionsit.unimi.dsi.fastutil.doubles- Double collectionsit.unimi.dsi.fastutil.floats- Float collectionsit.unimi.dsi.fastutil.chars- Character collectionsit.unimi.dsi.fastutil.shorts- Short collectionsit.unimi.dsi.fastutil.bytes- Byte collectionsit.unimi.dsi.fastutil.booleans- Boolean collections
Each package follows the same naming convention and provides the same collection types, differing only in the primitive type they handle.
Note: In version 8.5.16 source code examined, these packages contain only package-info.java placeholder files. The actual implementation classes are generated during the build process using preprocessor techniques from driver files, or may be available in the compiled JAR distribution.
Capabilities
Type-Specific Lists
Lists optimized for primitive types with direct primitive access methods alongside standard List interface compatibility.
/**
* List specialized for int elements, avoiding boxing overhead
*/
public interface IntList extends List<Integer>, IntCollection {
/**
* Get int element at specified index without boxing
* @param index the index
* @return the int value at index
*/
int getInt(int index);
/**
* Set int element at specified index without boxing
* @param index the index
* @param k the int value to set
* @return the previous int value at index
*/
int set(int index, int k);
/**
* Add int element at specified index without boxing
* @param index the index
* @param k the int value to add
*/
void add(int index, int k);
/**
* Remove int element at specified index without boxing
* @param index the index
* @return the removed int value
*/
int removeInt(int index);
/**
* Find first occurrence of int value
* @param k the int value to find
* @return the index, or -1 if not found
*/
int indexOf(int k);
/**
* Find last occurrence of int value
* @param k the int value to find
* @return the index, or -1 if not found
*/
int lastIndexOf(int k);
/**
* Get specialized int iterator
* @return IntListIterator for this list
*/
IntListIterator listIterator();
/**
* Get specialized int iterator starting at index
* @param index starting position
* @return IntListIterator starting at index
*/
IntListIterator listIterator(int index);
/**
* Get sublist view
* @param from start index (inclusive)
* @param to end index (exclusive)
* @return IntList view of the specified range
*/
IntList subList(int from, int to);
}
// Similar interfaces exist for all primitive types:
// LongList, DoubleList, FloatList, CharList, ShortList, ByteList, BooleanListUsage Examples:
import it.unimi.dsi.fastutil.ints.*;
// Create and populate an int list
IntList numbers = new IntArrayList();
numbers.add(42); // Direct int addition
numbers.add(1, 24); // Insert at index 1
// Direct primitive access (no boxing)
int value = numbers.getInt(0); // Get without boxing
int oldValue = numbers.set(1, 99); // Set without boxing
// Still compatible with standard List<Integer>
List<Integer> standardList = numbers; // Works seamlessly
standardList.add(Integer.valueOf(15)); // Boxing when neededType-Specific Sets
Sets optimized for primitive types with direct primitive membership testing and modification.
/**
* Set specialized for int elements, avoiding boxing overhead
*/
public interface IntSet extends Set<Integer>, IntCollection {
/**
* Add int element to set without boxing
* @param k the int value to add
* @return true if the set was modified
*/
boolean add(int k);
/**
* Test membership of int value without boxing
* @param k the int value to test
* @return true if the set contains the value
*/
boolean contains(int k);
/**
* Remove int value from set without boxing
* @param k the int value to remove
* @return true if the set was modified
*/
boolean remove(int k);
/**
* Get specialized int iterator
* @return IntIterator for this set
*/
IntIterator iterator();
}
/**
* Sorted set specialized for int elements
*/
public interface IntSortedSet extends IntSet, SortedSet<Integer> {
/**
* Get comparator for int values
* @return IntComparator used by this set
*/
IntComparator comparator();
/**
* Get subset from fromElement (inclusive) to toElement (exclusive)
* @param fromElement start value
* @param toElement end value
* @return IntSortedSet view of the range
*/
IntSortedSet subSet(int fromElement, int toElement);
/**
* Get subset with elements less than toElement
* @param toElement upper bound (exclusive)
* @return IntSortedSet view of elements < toElement
*/
IntSortedSet headSet(int toElement);
/**
* Get subset with elements >= fromElement
* @param fromElement lower bound (inclusive)
* @return IntSortedSet view of elements >= fromElement
*/
IntSortedSet tailSet(int fromElement);
/**
* Get first (smallest) int value
* @return the first int value
*/
int firstInt();
/**
* Get last (largest) int value
* @return the last int value
*/
int lastInt();
}
// Similar interfaces exist for all primitive types:
// LongSet, DoubleSet, FloatSet, CharSet, ShortSet, ByteSet, BooleanSet
// LongSortedSet, DoubleSortedSet, etc.Usage Examples:
import it.unimi.dsi.fastutil.ints.*;
// Create and populate an int set
IntSet uniqueNumbers = new IntOpenHashSet();
uniqueNumbers.add(42); // Direct int addition
uniqueNumbers.add(42); // Duplicate, ignored
boolean hasValue = uniqueNumbers.contains(42); // Direct primitive test
boolean removed = uniqueNumbers.remove(42); // Direct primitive removal
// Sorted set usage
IntSortedSet sortedNumbers = new IntAVLTreeSet();
sortedNumbers.add(30);
sortedNumbers.add(10);
sortedNumbers.add(20);
int smallest = sortedNumbers.firstInt(); // 10
int largest = sortedNumbers.lastInt(); // 30
IntSortedSet range = sortedNumbers.subSet(15, 25); // [20]Type-Specific Maps
Maps with primitive keys and/or values, providing direct primitive access without boxing overhead.
/**
* Map with int keys and Object values
* @param <V> the type of values
*/
public interface Int2ObjectMap<V> extends Map<Integer, V> {
/**
* Put mapping with int key without boxing
* @param key the int key
* @param value the value
* @return the previous value, or null
*/
V put(int key, V value);
/**
* Get value for int key without boxing
* @param key the int key
* @return the value, or null if not present
*/
V get(int key);
/**
* Remove mapping for int key without boxing
* @param key the int key
* @return the removed value, or null
*/
V remove(int key);
/**
* Test if int key is present without boxing
* @param key the int key
* @return true if key is present
*/
boolean containsKey(int key);
/**
* Get set of int keys
* @return IntSet containing all keys
*/
IntSet keySet();
/**
* Get collection of values
* @return Collection<V> containing all values
*/
Collection<V> values();
/**
* Get set of int key-value entries
* @return ObjectSet<Entry> containing all entries
*/
ObjectSet<Int2ObjectMap.Entry<V>> int2ObjectEntrySet();
/**
* Entry with int key and Object value
* @param <V> the type of value
*/
interface Entry<V> extends Map.Entry<Integer, V> {
/**
* Get int key without boxing
* @return the int key
*/
int getIntKey();
/**
* Set int key without boxing
* @param key the new int key
* @return the old int key
*/
int setValue(V value);
}
}
/**
* Map with int keys and int values (fully primitive)
*/
public interface Int2IntMap extends Map<Integer, Integer> {
/**
* Put int-to-int mapping without boxing
* @param key the int key
* @param value the int value
* @return the previous int value, or default return value
*/
int put(int key, int value);
/**
* Get int value for int key without boxing
* @param key the int key
* @return the int value, or default return value if not present
*/
int get(int key);
/**
* Remove int key without boxing
* @param key the int key
* @return the removed int value, or default return value
*/
int remove(int key);
/**
* Test if int key is present without boxing
* @param key the int key
* @return true if key is present
*/
boolean containsKey(int key);
/**
* Test if int value is present without boxing
* @param value the int value
* @return true if value is present
*/
boolean containsValue(int value);
/**
* Get default return value for missing keys
* @return the default return value
*/
int defaultReturnValue();
/**
* Set default return value for missing keys
* @param rv the new default return value
*/
void defaultReturnValue(int rv);
}
// All combinations of primitive types are available:
// Int2LongMap, Int2DoubleMap, Long2IntMap, Double2ObjectMap, etc.Usage Examples:
import it.unimi.dsi.fastutil.ints.*;
import it.unimi.dsi.fastutil.objects.*;
// Int-to-Object map
Int2ObjectMap<String> intToString = new Int2ObjectOpenHashMap<>();
intToString.put(1, "one"); // Direct int key
intToString.put(2, "two");
String value = intToString.get(1); // Direct int key lookup
// Fully primitive int-to-int map
Int2IntMap countMap = new Int2IntOpenHashMap();
countMap.defaultReturnValue(0); // Return 0 for missing keys
countMap.put(42, 5); // Both key and value are primitive
int count = countMap.get(42); // Direct primitive access
int missing = countMap.get(99); // Returns 0 (default)
// Increment counter without boxing
countMap.put(42, countMap.get(42) + 1); // All primitive operationsType-Specific Functions
Functional interfaces for primitive-to-primitive and primitive-to-object mappings.
/**
* Function mapping int to int
*/
@FunctionalInterface
public interface Int2IntFunction extends Function<Integer, Integer> {
/**
* Apply function to int value without boxing
* @param key the int input
* @return the int output
*/
int get(int key);
/**
* Get default return value for undefined inputs
* @return the default return value
*/
int defaultReturnValue();
/**
* Set default return value for undefined inputs
* @param rv the new default return value
*/
void defaultReturnValue(int rv);
}
/**
* Function mapping int to Object
* @param <V> the type of output values
*/
@FunctionalInterface
public interface Int2ObjectFunction<V> extends Function<Integer, V> {
/**
* Apply function to int value without boxing
* @param key the int input
* @return the output value
*/
V get(int key);
}
/**
* Function mapping Object to int
* @param <K> the type of input keys
*/
@FunctionalInterface
public interface Object2IntFunction<K> extends Function<K, Integer> {
/**
* Apply function to get int result without boxing
* @param key the input
* @return the int output
*/
int getInt(K key);
/**
* Get default return value for undefined inputs
* @return the default return value
*/
int defaultReturnValue();
/**
* Set default return value for undefined inputs
* @param rv the new default return value
*/
void defaultReturnValue(int rv);
}
// All primitive type combinations are available:
// Long2LongFunction, Double2DoubleFunction, Char2IntFunction, etc.Type-Specific Iterators and Comparators
Specialized iterators and comparators for primitive types, avoiding boxing during iteration and comparison.
/**
* Iterator specialized for int values
*/
public interface IntIterator extends Iterator<Integer> {
/**
* Get next int value without boxing
* @return the next int value
*/
int nextInt();
/**
* Skip next n elements efficiently
* @param n number of elements to skip
* @return number of elements actually skipped
*/
default int skip(int n) {
int i = 0;
while (i < n && hasNext()) {
nextInt();
i++;
}
return i;
}
}
/**
* List iterator specialized for int values
*/
public interface IntListIterator extends IntIterator, ListIterator<Integer> {
/**
* Get previous int value without boxing
* @return the previous int value
*/
int previousInt();
/**
* Set current int value without boxing
* @param k the int value to set
*/
void set(int k);
/**
* Add int value at current position without boxing
* @param k the int value to add
*/
void add(int k);
}
/**
* Comparator specialized for int values
*/
@FunctionalInterface
public interface IntComparator extends Comparator<Integer> {
/**
* Compare two int values without boxing
* @param k1 first int value
* @param k2 second int value
* @return comparison result
*/
int compare(int k1, int k2);
/**
* Get natural order comparator for int values
* @return IntComparator using natural ordering
*/
static IntComparator naturalOrder() {
return Integer::compare;
}
/**
* Get reverse order comparator for int values
* @return IntComparator using reverse ordering
*/
static IntComparator reverseOrder() {
return (a, b) -> Integer.compare(b, a);
}
}
// Similar specialized iterators and comparators exist for all primitive types:
// LongIterator, DoubleIterator, FloatIterator, etc.
// LongComparator, DoubleComparator, FloatComparator, etc.Usage Examples:
import it.unimi.dsi.fastutil.ints.*;
// Efficient iteration without boxing
IntList numbers = new IntArrayList();
numbers.add(10);
numbers.add(20);
numbers.add(30);
IntIterator iter = numbers.iterator();
while (iter.hasNext()) {
int value = iter.nextInt(); // No boxing overhead
System.out.println(value);
}
// Custom comparator for reverse order
IntComparator reverse = (a, b) -> Integer.compare(b, a);
numbers.sort(reverse); // Sorts in descending order
// Efficient skipping
IntIterator skipIter = numbers.iterator();
int skipped = skipIter.skip(2); // Skip first 2 elements efficiently
if (skipIter.hasNext()) {
int value = skipIter.nextInt(); // Get 3rd element
}Implementation Classes
Each primitive type package provides multiple implementation classes optimized for different use cases:
Array-Based Implementations
IntArrayList,LongArrayList, etc. - Dynamic arrays with primitive storageIntArraySet,LongArraySet, etc. - Sets backed by sorted arrays
Hash-Based Implementations
IntOpenHashSet,LongOpenHashSet, etc. - Open addressing hash setsInt2ObjectOpenHashMap,Long2IntOpenHashMap, etc. - Open addressing hash maps
Tree-Based Implementations
IntAVLTreeSet,LongAVLTreeSet, etc. - AVL tree sorted setsIntRBTreeSet,LongRBTreeSet, etc. - Red-black tree sorted sets
Specialized Implementations
IntLinkedOpenHashSet- Hash set maintaining insertion orderInt2IntLinkedOpenHashMap- Hash map maintaining insertion order
Each implementation is optimized for specific usage patterns while maintaining the same interface, allowing easy switching between implementations based on performance requirements.
Install with Tessl CLI
npx tessl i tessl/maven-it-unimi-dsi--fastutil