Package org.organicdesign.fp.collections

Interface UnmodCollection<E>

All Superinterfaces:

Collection<E>, Iterable<E>, Sized, Transformable<E>, UnmodIterable<E>

All Known Subinterfaces:

BaseList<E>, BaseSet<E>, ImList<E>, ImSet<E>, ImSortedSet<E>, MutList<E>, MutSet<E>, UnmodList<E>, UnmodSet<E>, UnmodSortedCollection<E>, UnmodSortedSet<E>

All Known Implementing Classes:

AbstractUnmodSet, PersistentHashSet, PersistentHashSet.MutHashSet, PersistentTreeSet, PersistentVector, PersistentVector.MutVector, RangeOfInt, RrbTree, RrbTree.ImRrbt, RrbTree.MutRrbt, UnmodList.AbstractUnmodList

public interface UnmodCollection<E>
extends 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().

Nested Class Summary

Nested classes/interfaces inherited from interface org.organicdesign.fp.collections.UnmodIterable

UnmodIterable.UnIterable

Method Summary

Modifier and Type	Method	Description
default boolean	add(E e)	Deprecated.
default boolean	addAll(@NotNull Collection<? extends E> c)	Deprecated.
default void	clear()	Deprecated.
default boolean	containsAll(@NotNull Collection<?> c)	The default implementation of this method has O(this.size() + that.size()) or O(n) performance.
default boolean	isEmpty()
@NotNull 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(Object o)	Deprecated.
default boolean	removeAll(@NotNull Collection<?> c)	Deprecated.
default boolean	removeIf(Predicate<? super E> filter)	Deprecated.
default boolean	retainAll(@NotNull Collection<?> c)	Deprecated.
default Object @NotNull []	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 @NotNull []	toArray(T @NotNull [] 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

any, toImList, toImMap, toImRrbt, toImSet, toImSortedMap, toImSortedSet, toMutList, toMutMap, toMutRrbt, toMutSet, toMutSortedMap, toMutSortedSet

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

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

Method Detail

add

@Deprecated
default boolean add(E e)

Deprecated.

Not allowed - this is supposed to be unmodifiable

Specified by:

add in interface Collection<E>

addAll

@Deprecated
default boolean addAll(@NotNull
                       @NotNull Collection<? extends E> c)

Deprecated.

Not allowed - this is supposed to be unmodifiable

Specified by:

addAll in interface Collection<E>

clear

@Deprecated
default void clear()

Deprecated.

Not allowed - this is supposed to be unmodifiable

Specified by:

clear in interface Collection<E>

containsAll

default boolean containsAll(@NotNull
                            @NotNull 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 Collection<E>

isEmpty

default boolean isEmpty()

Specified by:

isEmpty in interface Collection<E>

iterator

@NotNull
@NotNull 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 Collection<E>

Specified by:

iterator in interface Iterable<E>

Specified by:

iterator in interface UnmodIterable<E>

remove

@Deprecated
default boolean remove(Object o)

Deprecated.

Not allowed - this is supposed to be unmodifiable

Specified by:

remove in interface Collection<E>

removeAll

@Deprecated
default boolean removeAll(@NotNull
                          @NotNull Collection<?> c)

Deprecated.

Not allowed - this is supposed to be unmodifiable

Specified by:

removeAll in interface Collection<E>

removeIf

@Deprecated
default boolean removeIf(Predicate<? super E> filter)

Deprecated.

Not allowed - this is supposed to be unmodifiable

Specified by:

removeIf in interface Collection<E>

retainAll

@Deprecated
default boolean retainAll(@NotNull
                          @NotNull Collection<?> c)

Deprecated.

Not allowed - this is supposed to be unmodifiable

Specified by:

retainAll in interface Collection<E>

toArray

default Object @NotNull [] 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 Collection<E>

toArray

default <T> T @NotNull [] toArray(T @NotNull [] 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 Collection<E>