Package com.helger.commons.collection.impl

Interface ICommonsIterable<ELEMENTTYPE>

Type Parameters:

ELEMENTTYPE - The data type to iterate

All Superinterfaces:

Iterable<ELEMENTTYPE>

All Known Subinterfaces:

ICallbackList<CALLBACKTYPE>, ICommonsCollection<ELEMENTTYPE>, ICommonsList<ELEMENTTYPE>, ICommonsNavigableSet<ELEMENTTYPE>, ICommonsOrderedSet<ELEMENTTYPE>, ICommonsSet<ELEMENTTYPE>, ICommonsSortedSet<ELEMENTTYPE>, IErrorList, IHasErrorLevels<IMPLTYPE>, IIterableIterator<ELEMENTTYPE>

All Known Implementing Classes:

ArrayIterator, CallbackList, CombinationGenerator, CommonsArrayList, CommonsCopyOnWriteArrayList, CommonsCopyOnWriteArraySet, CommonsHashSet, CommonsLinkedHashSet, CommonsLinkedList, CommonsTreeSet, CommonsVector, CSVReader, ErrorList, FileSystemIterator, FileSystemRecursiveIterator, FilterIterator, HttpHeaderMap, InMemoryLogger, IterableIterator, IterableIteratorFromEnumeration, LRUSet, MapperIterator, NonBlockingStack, URLParameterList

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	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 int	findFirstIndex(Predicate<? super ELEMENTTYPE> aFilter)	Find the first index where the provided filter matches.
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 int	findLastIndex(Predicate<? super ELEMENTTYPE> aFilter)	Find the last index where the provided filter matches.
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 void	forEachByIndex(ObjIntConsumer<? super ELEMENTTYPE> aConsumer)	Special forEach that takes an ObjIntConsumer which is provided the value AND the index.
default <EXTYPE extends Throwable> void	forEachThrowing(IThrowingConsumer<? super ELEMENTTYPE,EXTYPE> aConsumer)	A special version of Iterable.forEach(Consumer) where a consumer can throw an exception.
default int	getCount()	Retrieve the size of this Iterable.
default int	getCount(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

forEachByIndex

default void forEachByIndex(@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.

forEachThrowing

default <EXTYPE extends Throwable> void forEachThrowing(@Nonnull
                                                        IThrowingConsumer<? super ELEMENTTYPE,EXTYPE> aConsumer)
                                                 throws EXTYPE extends Throwable

A special version of Iterable.forEach(Consumer) where a consumer can throw an exception.

Type Parameters:

EXTYPE - the type of Exception to be thrown

Parameters:

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

Throws:

EXTYPE - If one of the consumer throws this exception

EXTYPE extends Throwable

Since:

10.0.0

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 IHasSize.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 IHasSize.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 IHasSize.isNotEmpty().

getCount

@Nonnegative
default int getCount()

Retrieve the size of this Iterable. This method does by default iterate all elements. Please provide a more efficient solution. If this is a collection, consider using size() instead.

Returns:

The number objects contained. Always ≥ 0.

getCount

@Nonnegative
default int getCount(@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 getCount().

findFirstIndex

@Nonnegative
default int findFirstIndex(@Nonnull
                           Predicate<? super ELEMENTTYPE> aFilter)

Find the first index where the provided filter matches.

Parameters:

aFilter - The filter to use. May not be null.

Returns:

-1 if no element matches the filter, the 0-based index otherwise.

Since:

9.3.3

findLastIndex

@Nonnegative
default int findLastIndex(@Nonnull
                          Predicate<? super ELEMENTTYPE> aFilter)

Find the last index where the provided filter matches.

Parameters:

aFilter - The filter to use. May not be null.

Returns:

-1 if no element matches the filter, the 0-based index otherwise.

Since:

9.3.3