com.helger.commons.collection.ext

Interface ICommonsIterable<ELEMENTTYPE>

Type Parameters:

ELEMENTTYPE - The data type to iterate

All Superinterfaces:

Iterable<ELEMENTTYPE>

All Known Subinterfaces:

IApplicationScope, IAttributeContainer<KEYTYPE,VALUETYPE>, ICallbackList<CALLBACKTYPE>, ICommonsCollection<ELEMENTTYPE>, ICommonsList<ELEMENTTYPE>, ICommonsNavigableSet<ELEMENTTYPE>, ICommonsOrderedSet<ELEMENTTYPE>, ICommonsSet<ELEMENTTYPE>, ICommonsSortedSet<ELEMENTTYPE>, IErrorBaseList<IMPLTYPE>, IErrorList, IGlobalScope, IHasErrorLevels<IMPLTYPE>, IIterableIterator<ELEMENTTYPE>, IMutableAttributeContainer<KEYTYPE,VALUETYPE>, IMutableAttributeContainerAny<KEYTYPE>, IRequestScope, IScope, ISessionApplicationScope, ISessionScope

All Known Implementing Classes:

AbstractMapBasedScope, ApplicationScope, ArrayIterator, CallbackList, CombinationGenerator, CommonsArrayList, CommonsCopyOnWriteArrayList, CommonsCopyOnWriteArraySet, CommonsHashSet, CommonsLinkedHashSet, CommonsLinkedList, CommonsTreeSet, CommonsVector, CSVReader, EmptySortedSet, ErrorList, FileSystemIterator, FileSystemRecursiveIterator, FilterIterator, GlobalScope, InMemoryLogger, IterableIterator, IterableIteratorFromEnumeration, LRUSet, MapBasedAttributeContainer, MapBasedAttributeContainerAny, MapBasedReadOnlyAttributeContainer, MapperIterator, NonBlockingStack, RequestScope, SafeArrayList, SafeVector, SessionApplicationScope, SessionScope, SingleElementList, URLParameterList, WrappedCollection, WrappedList, WrappedSet

public interface ICommonsIterable<ELEMENTTYPE>
extends Iterable<ELEMENTTYPE>

Extended version of Iterable with some additional default methods.

Author:

Philip Helger

Method Summary

Modifier and Type	Method and Description
default boolean	containsAny(Predicate<? super ELEMENTTYPE> aFilter) Check if this collection contains any (=at least one) element matching the provided filter.
default boolean	containsNone(Predicate<? super ELEMENTTYPE> aFilter) Check if this collection contains no (=zero) element matching the provided filter.
default boolean	containsOnly(Predicate<? super ELEMENTTYPE> aFilter) Check if this collection contains only (=all) elements matching the provided filter.
default void	findAll(Predicate<? super ELEMENTTYPE> aFilter, Consumer<? super ELEMENTTYPE> aConsumer) Find all elements matching the supplied filter and invoke the provided consumer for each matching element.
default <DSTTYPE extends ELEMENTTYPE> void	findAllInstanceOf(Class<DSTTYPE> aDstClass, Consumer<? super DSTTYPE> aConsumer) Find all elements that are instanceOf the provided class and invoke the provided consumer for all matching elements.
default <DSTTYPE> void	findAllMapped(Function<? super ELEMENTTYPE,DSTTYPE> aMapper, Consumer<? super DSTTYPE> aConsumer) Convert all elements using the provided function and invoke the provided consumer for all mapped elements.
default <DSTTYPE> void	findAllMapped(Function<? super ELEMENTTYPE,DSTTYPE> aMapper, Predicate<? super DSTTYPE> aFilter, Consumer<? super DSTTYPE> aConsumer) Convert all elements using the provided function, find all mapped elements matching the provided filter and invoke the provided consumer for all matching elements.
default <DSTTYPE> void	findAllMapped(Predicate<? super ELEMENTTYPE> aFilter, Function<? super ELEMENTTYPE,DSTTYPE> aMapper, Consumer<? super DSTTYPE> aConsumer) Find all elements matching the provided filter, convert the matching elements using the provided function and invoke the provided consumer for all mapped elements.
default ELEMENTTYPE	findFirst(Predicate<? super ELEMENTTYPE> aFilter) Find the first element that matches the provided filter.
default ELEMENTTYPE	findFirst(Predicate<? super ELEMENTTYPE> aFilter, ELEMENTTYPE aDefault) Find the first element that matches the provided filter.
default <DSTTYPE> DSTTYPE	findFirstMapped(Predicate<? super ELEMENTTYPE> aFilter, Function<? super ELEMENTTYPE,DSTTYPE> aMapper) Find the first element that matches the provided filter and convert it using the provided mapper.
default <DSTTYPE> DSTTYPE	findFirstMapped(Predicate<? super ELEMENTTYPE> aFilter, Function<? super ELEMENTTYPE,DSTTYPE> aMapper, DSTTYPE aDefault) Find the first element that matches the provided filter and convert it using the provided mapper.
default void	forEach(Consumer<? super ELEMENTTYPE> aConsumer, Predicate<? super ELEMENTTYPE> aFilter) Special forEach that takes an additional filter so that the consumer is only invoked for elements matching the provided filter.
default void	forEach(ObjIntConsumer<? super ELEMENTTYPE> aConsumer) Special forEach that takes an ObjIntConsumer which is provided the value AND the index.
default EContinue	forEachBreakable(Function<? super ELEMENTTYPE,EContinue> aConsumer) A special version of Iterable.forEach(Consumer) that can break iteration if a certain requirement is fulfilled.
default int	getIteratorCount() Retrieve the size of this Iterable.
default int	getIteratorCount(Predicate<? super ELEMENTTYPE> aFilter) Count the number of elements in this iterable matching the provided filter.

Methods inherited from interface java.lang.Iterable

forEach, iterator, spliterator

Method Detail

forEach

default void forEach(@Nonnull
                     ObjIntConsumer<? super ELEMENTTYPE> aConsumer)

Special forEach that takes an ObjIntConsumer which is provided the value AND the index.

Parameters:

aConsumer - The consumer to use. May not be null.

forEachBreakable

@Nonnull
default EContinue forEachBreakable(@Nonnull
                                             Function<? super ELEMENTTYPE,EContinue> aConsumer)

A special version of Iterable.forEach(Consumer) that can break iteration if a certain requirement is fulfilled.

Parameters:

aConsumer - The consumer to be invoked. May not be null.

Returns:

EContinue.BREAK if iteration was stopped, EContinue.CONTINUE otherwise.

forEach

default void forEach(@Nonnull
                     Consumer<? super ELEMENTTYPE> aConsumer,
                     @Nullable
                     Predicate<? super ELEMENTTYPE> aFilter)

Special forEach that takes an additional filter so that the consumer is only invoked for elements matching the provided filter.

Parameters:

aConsumer - The consumer to use. May not be null.

aFilter - The filter to be applied. May be null. If the filter is null this method behaves like Iterable.forEach(Consumer).

Since:

8.5.2

findAll

default void findAll(@Nullable
                     Predicate<? super ELEMENTTYPE> aFilter,
                     @Nonnull
                     Consumer<? super ELEMENTTYPE> aConsumer)

Find all elements matching the supplied filter and invoke the provided consumer for each matching element.

Parameters:

aFilter - The filter to be applied. May be null.

aConsumer - The consumer to be invoked for all matching elements. May not be null.

findAllMapped

default <DSTTYPE> void findAllMapped(@Nonnull
                                     Function<? super ELEMENTTYPE,DSTTYPE> aMapper,
                                     @Nonnull
                                     Consumer<? super DSTTYPE> aConsumer)

Convert all elements using the provided function and invoke the provided consumer for all mapped elements.

Type Parameters:

DSTTYPE - The destination type to be mapped to

Parameters:

aMapper - The mapping function to be executed for all elements. May not be null.

aConsumer - The consumer to be invoked for all mapped elements. May not be null.

findAllMapped

default <DSTTYPE> void findAllMapped(@Nullable
                                     Predicate<? super ELEMENTTYPE> aFilter,
                                     @Nonnull
                                     Function<? super ELEMENTTYPE,DSTTYPE> aMapper,
                                     @Nonnull
                                     Consumer<? super DSTTYPE> aConsumer)

Find all elements matching the provided filter, convert the matching elements using the provided function and invoke the provided consumer for all mapped elements.

Type Parameters:

DSTTYPE - The destination type to be mapped to

Parameters:

aFilter - The filter to be applied. May be null.

aMapper - The mapping function to be executed for all matching elements. May not be null.

aConsumer - The consumer to be invoked for all matching mapped elements. May not be null.

findAllMapped

default <DSTTYPE> void findAllMapped(@Nonnull
                                     Function<? super ELEMENTTYPE,DSTTYPE> aMapper,
                                     @Nullable
                                     Predicate<? super DSTTYPE> aFilter,
                                     @Nonnull
                                     Consumer<? super DSTTYPE> aConsumer)

Convert all elements using the provided function, find all mapped elements matching the provided filter and invoke the provided consumer for all matching elements.

Type Parameters:

DSTTYPE - The destination type to be mapped to

Parameters:

aMapper - The mapping function to be executed for all matching elements. May not be null.

aFilter - The filter to be applied. May be null.

aConsumer - The consumer to be invoked for all matching mapped elements. May not be null.

Since:

8.5.2

findAllInstanceOf

default <DSTTYPE extends ELEMENTTYPE> void findAllInstanceOf(@Nonnull
                                                             Class<DSTTYPE> aDstClass,
                                                             @Nonnull
                                                             Consumer<? super DSTTYPE> aConsumer)

Find all elements that are instanceOf the provided class and invoke the provided consumer for all matching elements. This is a special implementation of findAllMapped(Predicate, Function, Consumer).

Type Parameters:

DSTTYPE - The destination type to be casted to

Parameters:

aDstClass - The class of which all elements should be find. May not be null.

aConsumer - The consumer to be invoked for all instances of the provided class. May not be null.

findFirst

@Nullable
default ELEMENTTYPE findFirst(@Nullable
                                         Predicate<? super ELEMENTTYPE> aFilter)

Find the first element that matches the provided filter. If no element matches the provided filter or if the collection is empty, null is returned by default. If this collection does not maintain order (like Set) it is undefined which value is returned.

Parameters:

aFilter - The filter to be applied. May be null.

Returns:

null if no element matches the filter or if the collection is empty, the first matching element otherwise.

See Also:

findFirst(Predicate, Object)

findFirst

@Nullable
default ELEMENTTYPE findFirst(@Nullable
                                         Predicate<? super ELEMENTTYPE> aFilter,
                                         @Nullable
                                         ELEMENTTYPE aDefault)

Find the first element that matches the provided filter. If no element matches the provided filter or if the collection is empty, the provided default value is returned. If this collection does not maintain order (like Set) it is undefined which value is returned.

Parameters:

aFilter - The filter to be applied. May be null.

aDefault - The default value to be returned if no element matches. May be null.

Returns:

The provided default value if no element matches the filter or if the collection is empty, the first matching element otherwise.

See Also:

findFirst(Predicate)

findFirstMapped

@Nullable
default <DSTTYPE> DSTTYPE findFirstMapped(@Nullable
                                                     Predicate<? super ELEMENTTYPE> aFilter,
                                                     @Nonnull
                                                     Function<? super ELEMENTTYPE,DSTTYPE> aMapper)

Find the first element that matches the provided filter and convert it using the provided mapper. If no element matches the provided filter or if the collection is empty, null is returned by default. If this collection does not maintain order (like Set) it is undefined which value is returned.

Type Parameters:

DSTTYPE - The destination type to be mapped to

Parameters:

aFilter - The filter to be applied. May be null.

aMapper - The mapping function to be executed for the first matching element. May not be null.

Returns:

null if no element matches the filter or if the collection is empty, the first matching element otherwise.

See Also:

findFirstMapped(Predicate, Function, Object)

findFirstMapped

@Nullable
default <DSTTYPE> DSTTYPE findFirstMapped(@Nullable
                                                     Predicate<? super ELEMENTTYPE> aFilter,
                                                     @Nonnull
                                                     Function<? super ELEMENTTYPE,DSTTYPE> aMapper,
                                                     @Nullable
                                                     DSTTYPE aDefault)

Find the first element that matches the provided filter and convert it using the provided mapper. If no element matches the provided filter or if the collection is empty, the provided default value is returned. If this collection does not maintain order (like Set) it is undefined which value is returned.

Type Parameters:

DSTTYPE - The destination type to be mapped to

Parameters:

aFilter - The filter to be applied. May be null.

aMapper - The mapping function to be executed for the first matching element. May not be null.

aDefault - The default value to be returned if no element matches. May be null.

Returns:

The provided default value if no element matches the filter or if the collection is empty, the first matching element otherwise.

See Also:

findFirstMapped(Predicate, Function)

containsAny

default boolean containsAny(@Nullable
                            Predicate<? super ELEMENTTYPE> aFilter)

Check if this collection contains any (=at least one) element matching the provided filter.

Parameters:

aFilter - The filter to be applied. May be null.

Returns:

true if the container is not empty and at least one element matches the provided filter, false otherwise. If no filter is provided the response is the same as ICommonsCollection.isNotEmpty().

containsNone

default boolean containsNone(@Nullable
                             Predicate<? super ELEMENTTYPE> aFilter)

Check if this collection contains no (=zero) element matching the provided filter.

Parameters:

aFilter - The filter to be applied. May be null.

Returns:

true if the container is empty or if no element matches the provided filter, false otherwise. If no filter is provided, this is the same as Collection.isEmpty().

containsOnly

default boolean containsOnly(@Nonnull
                             Predicate<? super ELEMENTTYPE> aFilter)

Check if this collection contains only (=all) elements matching the provided filter. If this collection is empty, it does not fulfill this requirement! If no filter is provided the return value is identical to ICommonsCollection.isNotEmpty().

Parameters:

aFilter - The filter to be applied. May be null.

Returns:

true if this collection is not empty and all elements matching the filter or if no filter is provided and this collection is not empty, false otherwise. If no filter is supplied the return value is identical to ICommonsCollection.isNotEmpty().

getIteratorCount

@Nonnegative
default int getIteratorCount()

Retrieve the size of this Iterable.

Returns:

The number objects contained. Always ≥ 0.

getIteratorCount

@Nonnegative
default int getIteratorCount(@Nullable
                                           Predicate<? super ELEMENTTYPE> aFilter)

Count the number of elements in this iterable matching the provided filter.

Parameters:

aFilter - The filter to be applied. May be null.

Returns:

The number of matching elements. Always ≥ 0. If no filter is provided this is the same as getIteratorCount().