Package org.organicdesign.fp.collections

Interface UnmodCollection<E>

All Superinterfaces:

java.util.Collection<E>, java.lang.Iterable<E>, Sized, Transformable<E>, UnmodIterable<E>

All Known Subinterfaces:

BaseList<E>, BaseSet<E>, ImList<E>, ImSet<E>, ImSortedSet<E>, MutableList<E>, MutableSet<E>, UnmodList<E>, UnmodSet<E>, UnmodSortedCollection<E>, UnmodSortedSet<E>

All Known Implementing Classes:

AbstractUnmodSet, PersistentHashSet, PersistentHashSet.MutableHashSet, PersistentTreeSet, PersistentVector, PersistentVector.MutableVector, RangeOfInt, RrbTree, RrbTree.ImRrbt, RrbTree.MutableRrbt, UnmodList.AbstractUnmodList

public interface UnmodCollection<E>
extends java.util.Collection<E>, UnmodIterable<E>, Sized

Don't implement this interface directly if you don't have to. A collection is an Iterable with a size (a size() method) and unfortunately a contains() method (deprecated on Lists). Collection defines the return of Map.values() which can have duplicates and may be ordered, or unordered. For this reason, I don't think it's possible to define an equals() method on Collection that works in all circumstances (when comparing it to a List, a Set, or another amorphous Collection). I don't think Map.values() would exist if Generics had existed and Map had implemented Iterable<Entry> from the beginning. UnmodCollection is an unmodifiable version of Collection which formalizes the return type of Collections.unmodifiableCollection() and Map.values().

Method Summary

Modifier and Type	Method	Description
default boolean	add(E e)	Deprecated.
default boolean	addAll(java.util.Collection<? extends E> c)	Deprecated.
default void	clear()	Deprecated.
default boolean	containsAll(java.util.Collection<?> c)	The default implementation of this method has O(this.size() + that.size()) or O(n) performance.
default boolean	isEmpty()
UnmodIterator<E>	iterator()	An unmodifiable iterator A one-time use, mutable, not-thread-safe way to get each value of the underling collection in turn.
default boolean	remove(java.lang.Object o)	Deprecated.
default boolean	removeAll(java.util.Collection<?> c)	Deprecated.
default boolean	removeIf(java.util.function.Predicate<? super E> filter)	Deprecated.
default boolean	retainAll(java.util.Collection<?> c)	Deprecated.
default java.lang.Object[]	toArray()	This method goes against Josh Bloch's Item 25: "Prefer Lists to Arrays", but is provided for backwards compatibility in some performance-critical situations.
default <T> T[]	toArray(T[] as)	This method goes against Josh Bloch's Item 25: "Prefer Lists to Arrays", but is provided for backwards compatibility in some performance-critical situations.

Methods inherited from interface java.util.Collection

contains, equals, hashCode, parallelStream, size, spliterator, stream, toArray

Methods inherited from interface java.lang.Iterable

forEach

Methods inherited from interface org.organicdesign.fp.collections.Sized

size

Methods inherited from interface org.organicdesign.fp.xform.Transformable

toImList, toImMap, toImRrbt, toImSet, toImSortedMap, toImSortedSet, toMutableList, toMutableMap, toMutableRrbt, toMutableSet, toMutableSortedMap, toMutableSortedSet

Methods inherited from interface org.organicdesign.fp.collections.UnmodIterable

concat, drop, dropWhile, filter, flatMap, fold, foldUntil, head, map, precat, take, takeWhile

Method Detail

add

@Deprecated
default boolean add(E e)

Deprecated.

Not allowed - this is supposed to be unmodifiable

Specified by:

add in interface java.util.Collection<E>

addAll

@Deprecated
default boolean addAll(java.util.Collection<? extends E> c)

Deprecated.

Not allowed - this is supposed to be unmodifiable

Specified by:

addAll in interface java.util.Collection<E>

clear

@Deprecated
default void clear()

Deprecated.

Not allowed - this is supposed to be unmodifiable

Specified by:

clear in interface java.util.Collection<E>

containsAll

default boolean containsAll(java.util.Collection<?> c)

The default implementation of this method has O(this.size() + that.size()) or O(n) performance. So even though contains() is impossible to implement efficiently for Lists, containsAll() has a decent implementation (brute force would be O(this.size() * that.size()) or O(n^2) ).

Specified by:

containsAll in interface java.util.Collection<E>

isEmpty

default boolean isEmpty()

Specified by:

isEmpty in interface java.util.Collection<E>

iterator

UnmodIterator<E> iterator()

An unmodifiable iterator A one-time use, mutable, not-thread-safe way to get each value of the underling collection in turn. I experimented with various thread-safe alternatives, but the JVM is optimized around iterators so this is the lowest common denominator of collection iteration, even though iterators are inherently mutable.

Specified by:

iterator in interface java.util.Collection<E>

Specified by:

iterator in interface java.lang.Iterable<E>

Specified by:

iterator in interface UnmodIterable<E>

remove

@Deprecated
default boolean remove(java.lang.Object o)

Deprecated.

Not allowed - this is supposed to be unmodifiable

Specified by:

remove in interface java.util.Collection<E>

removeAll

@Deprecated
default boolean removeAll(java.util.Collection<?> c)

Deprecated.

Not allowed - this is supposed to be unmodifiable

Specified by:

removeAll in interface java.util.Collection<E>

removeIf

@Deprecated
default boolean removeIf(java.util.function.Predicate<? super E> filter)

Deprecated.

Not allowed - this is supposed to be unmodifiable

Specified by:

removeIf in interface java.util.Collection<E>

retainAll

@Deprecated
default boolean retainAll(java.util.Collection<?> c)

Deprecated.

Not allowed - this is supposed to be unmodifiable

Specified by:

retainAll in interface java.util.Collection<E>

toArray

default java.lang.Object[] toArray()

This method goes against Josh Bloch's Item 25: "Prefer Lists to Arrays", but is provided for backwards compatibility in some performance-critical situations. If you really need an array, consider using the somewhat type-safe version of this method instead, but read the caveats first.

Specified by:

toArray in interface java.util.Collection<E>

toArray

default <T> T[] toArray(T[] as)

This method goes against Josh Bloch's Item 25: "Prefer Lists to Arrays", but is provided for backwards compatibility in some performance-critical situations. If you need to create an array (you almost always do) then the best way to use this method is: MyThing[] things = col.toArray(new MyThing[coll.size()]); Calling this method any other way causes unnecessary work to be done - an extra memory allocation and potential garbage collection if the passed array is too small, extra effort to fill the end of the array with nulls if it is too large.

Specified by:

toArray in interface java.util.Collection<E>