Overview   Package  Class  Tree  Deprecated  Index  Help 
 PREV PACKAGE   NEXT PACKAGE FRAMES    NO FRAMES    

Package net.openhft.collect

The root package of the collection library.

See:
          Description

Interface Summary
ByteCollection A Collection specialization with byte elements.
ByteCursor A mutable pointer to the element in an iteration of bytes.
ByteIterator Primitive specialization of Iterator<Byte>.
CharCollection A Collection specialization with char elements.
CharCursor A mutable pointer to the element in an iteration of chars.
CharIterator Primitive specialization of Iterator<Character>.
Container The root interface of all collections within the library.
Cursor A mutable pointer to the element in an iteration.
DoubleCollection A Collection specialization with double elements.
DoubleCursor A mutable pointer to the element in an iteration of doubles.
DoubleIterator Primitive specialization of Iterator<Double>.
FloatCollection A Collection specialization with float elements.
FloatCursor A mutable pointer to the element in an iteration of floats.
FloatIterator Primitive specialization of Iterator<Float>.
IntCollection A Collection specialization with int elements.
IntCursor A mutable pointer to the element in an iteration of ints.
IntIterator Primitive specialization of Iterator<Integer>.
LongCollection A Collection specialization with long elements.
LongCursor A mutable pointer to the element in an iteration of longs.
LongIterator Primitive specialization of Iterator<Long>.
ObjCollection<E> A collection of objects, the library's extension of the classic Collection interface.
ObjCursor<E> A mutable pointer to the element in an iteration of objects.
ObjIterator<E> Extends Iterator for the symmetry with primitive specializations.
ShortCollection A Collection specialization with short elements.
ShortCursor A mutable pointer to the element in an iteration of shorts.
ShortIterator Primitive specialization of Iterator<Short>.
 

Class Summary
Equivalence<T> A strategy for determining whether two instances are considered equivalent.
StatelessEquivalence<T> Base class for stateless Equivalence implementations.
 

Package net.openhft.collect Description

The root package of the collection library.

Table of equivalents of JDK collection patterns

JDK The closest equivalent from this library The recommended equivalent from this library 
new HashMap<String, String>();
 
HashObjObjMaps.getDefaultFactory()
         .withNullKeyAllowed(true)
         .<String, String>newMutableMap();
 
HashObjObjMaps.<String, String>newUpdatableMap();
 
// unclear how "capacity" (100)
 // is translated to size. 50? 75? 100?
 new HashMap<Integer, String>(100);
 
HashIntObjMaps.<String>newMutableMap(
         (int) (100 * HashConfig.getDefault().getTargetLoad()));
 
// 50 is expected _size_
 HashIntObjMaps.<String>newUpdatableMap(50);
 
new IdentityHashMap<Object, Double>(map);
 
HashObjDoubleMaps.getDefaultFactory()
         // these loads used in IdentityHashMap internally
         .withHashConfig(HashConfig.fromLoads(1./3., 2./3., 2./3.))
         .withNullKeyAllowed(true)
         .withKeyEquivalence(Equivalence.identity())
         .newMutableMap(map);
 
HashObjDoubleMaps.getDefaultFactory()
         .withKeyEquivalence(Equivalence.identity())
         .newImmutableMap(map);
 
 Collections.unmodifiableSet(new HashSet<>() {{
     add("Summer");
     add("Autumn");
     add("Winter");
     add("Spring");
 }});
 
HashObjSets.newImmutableSetOf("Summer", "Autumn", "Winter", "Spring")

Mutability profiles

Container factories allow to construct containers with several distinct degrees of mutability.

Immutable

Any operations that change the conceptual container state, e. g. insertions and removals, as well as that could touch internal representation, e. g. Container.shrink(), are disallowed. Other ones are allowed.

Updatable

Everything is allowed, except removals of individual elements (entries), typically these operations' names contain word "remove" or "retain". Emphasis on "individual" means that Container.clear() is allowed.

Think about updatable containers as "non-decreasing", which could be "reset" from time to time by clear().

In real practice individual removals are rarely needed, so most of the time you should use updatable containers rather than fully mutable ones. On the other hand, prohibit of removals permits faster implementation of hash containers and iterators over many data structures.

Mutable

All operations are allowed.

Collection mutability matrix

This matrix shows which methods of the Collection interface are supported by collections with different mutability profiles.
Method \ MutabilityMutableUpdatableImmutable
contains(Object) ✓✓✓
containsAll(Collection) ✓✓✓
iterator() ✓✓✓
toArray() ✓✓✓
toArray(Object[]) ✓✓✓
add(Object) ✓✓-
addAll(Collection) ✓✓-
remove(Object) ✓--
removeAll(Collection) ✓--
retainAll(Collection) ✓--

Map mutability matrix

This matrix shows which methods of the Map interface are supported by maps with different mutability profiles.
Method \ MutabilityMutableUpdatableImmutable
containsKey(Object) ✓✓✓
containsValue(Object) ✓✓✓
get(Object) ✓✓✓
keySet() ✓✓✓
entrySet() ✓✓✓
values() ✓✓✓
put(Object, Object) ✓✓-
putAll(Map) ✓✓-
remove(Object) ✓--

See other matrices for information if the concrete method is supported by the given mutability profile: Container.

Comparison of iteration ways

In addition to the standard way — iterators, the library supplies cursors for every container and forEach()-like methods which accept closures.
Overview comparison of the ways to iterate over containers within the library
Iterator Cursor forEach() forEachWhile() removeIf()
Available for Collection sub-interfaces in the library Yes
Available for Map sub-interfaces in the library Yes
Coding convenience High, if elements aren't removed and generic version of Iterator.next() method is used, Java "for-each" syntax is applicable. Medium otherwise. Medium Low, nasty anonymous classes declarations
Supports early break from the iteration Yes, by simple break from the loop Yes, by simple break from the loop No Yes, by returning false No
Supports remove of iterated elements (entries) Yes, by Iterator.remove() Yes, by Cursor.remove() No No Yes, by returning true
Performance, iteration over Map Medium, Map.Entry object are allocated Very high
Performance, iteration over Collection High, if specialized version of Iterator.next() method is used. Medium otherwise, because every element is boxed. Very high

Overview   Package  Class  Tree  Deprecated  Index  Help 
 PREV PACKAGE   NEXT PACKAGE FRAMES    NO FRAMES