Module com.jongsoft.lang
Package com.jongsoft.lang.collection

Interface Collection<T>

    • Method Summary

      All Methods Instance Methods Abstract Methods Default Methods 
      Modifier and Type Method Description
      default boolean containsAll​(java.lang.Iterable<? extends T> elements)
      Checks if all elements in the provided iterable are contained in this collection.
      default int count​(java.util.function.Predicate<T> predicate)
      Count all elements that match the provided predicate.
      Collection<T> filter​(java.util.function.Predicate<T> predicate)
      Filter out an element if it does not match the supplied predicate.
      default Optional<T> first​(java.util.function.Predicate<T> predicate)
      Find the first match in the elements using the provided Predicate.
      default <U> U foldLeft​(U start, java.util.function.BiFunction<? super U,​? super T,​? extends U> combiner)
      Folds the elements from the left, starting with the start value and combining the result by successively calling the combiner operation.
      default <U> U foldRight​(U start, java.util.function.BiFunction<? super T,​? super U,​? extends U> combiner)
      Folds the elements from the right, starting with the start value and combining the result by successively calling the combiner.
      default T get()
      Fetch the head of the collection and return it.
      T head()
      Fetch the head of the collection and return it.
      default boolean isEmpty()
      Convenience method to see if the current list is empty or not.
      default boolean isSingleValued()
      Is this instance single-valued or not.
      default Optional<T> last​(java.util.function.Predicate<T> predicate)
      Find the last match in the Iterator using the provided Predicate.
      <U> Collection<U> map​(java.util.function.Function<T,​U> mapper)
      Perform a mapping operation on the elements in the stream.
      Collection<T> orElse​(java.lang.Iterable<? extends T> other)
      Returns either this if it is non empty, otherwise will return the provided other.
      Collection<T> orElse​(java.util.function.Supplier<? extends java.lang.Iterable<? extends T>> supplier)
      Returns either this if it is non empty, otherwise the provided supplier is evaluated and returned.
      default T reduceLeft​(java.util.function.BiFunction<? super T,​? super T,​? extends T> reducer)
      Reduce the collection from the left, starting with the first element in the collection and successively calling the reducer until there are no more elements.
      Collection<T> reject​(java.util.function.Predicate<T> predicate)
      Return a list that removes all elements that match the predicate provided.
      int size()
      Get the amount of elements contained in the collection.
      Pair<? extends Collection<T>,​? extends Collection<T>> split​(java.util.function.Predicate<T> predicate)
      The split operation is an execution that combines the reject(Predicate) and the filter(Predicate) methods into one.
      default long summing​(java.util.function.BiFunction<java.lang.Long,​T,​java.lang.Long> accumulator)
      Sum all elements using the provided accumulator.
      Collection<T> tail()
      Build a new collection with all elements except for the head.

      • Methods inherited from interface java.lang.Iterable

        forEach, spliterator

    • Method Detail

      • containsAll

        default boolean containsAll​(java.lang.Iterable<? extends T> elements)
        Checks if all elements in the provided iterable are contained in this collection.

        This is a convenience method that uses the Value.contains(Object) to verify existence.

        Parameters:
        elements - the elements that should be present
        Returns:
        true if all elements are present, false otherwise
        See Also:
        Value.contains(Object)

      • count

        default int count​(java.util.function.Predicate<T> predicate)
        Count all elements that match the provided predicate.
        Parameters:
        predicate - the predicate that must be true
        Returns:
        the amount of elements matching the predicate
        Throws:
        java.lang.NullPointerException - in case predicate is null

      • filter

        Collection<T> filter​(java.util.function.Predicate<T> predicate)
        Description copied from interface: Streamable
        Filter out an element if it does not match the supplied predicate. This operation will iterate over all elements and return a new set containing only the elements where the predicate returns true for.
        Specified by:
        filter in interface Streamable<T>
        Specified by:
        filter in interface Traversable<T>
        Parameters:
        predicate - the predicate to apply to the contents of this
        Returns:
        the filtered value

      • first

        default Optional<T> first​(java.util.function.Predicate<T> predicate)
        Description copied from interface: Traversable
        Find the first match in the elements using the provided Predicate. The returned Optional is null safe and will either contain the element or be an empty Optional.

        Example:

        // the result will be an Optional with the value 2
    int firstMatch = Collection(1, 2, 3, 4)
          .first(i -> i % 2 == 0);
        Specified by:
        first in interface Traversable<T>
        Parameters:
        predicate - the predicate to use
        Returns:
        the first match found

      • foldLeft

        default <U> U foldLeft​(U start,
                       java.util.function.BiFunction<? super U,​? super T,​? extends U> combiner)
        Description copied from interface: Foldable
        Folds the elements from the left, starting with the start value and combining the result by successively calling the combiner operation.

        Example: 

        // result "!test"
    List("t", "e", "s", "t").foldLeft("!",  (x, y) -> x + y)
        Specified by:
        foldLeft in interface Foldable<T>
        Type Parameters:
        U - the type of value returned
        Parameters:
        start - the start value for the fold operation
        combiner - the operation used to combine elements
        Returns:
        the folded value

      • foldRight

        default <U> U foldRight​(U start,
                        java.util.function.BiFunction<? super T,​? super U,​? extends U> combiner)
        Description copied from interface: Foldable
        Folds the elements from the right, starting with the start value and combining the result by successively calling the combiner.

        Example: 

        // result "tset!"
    List("t", "e", "s", "t").foldRight("!",  (x, y) -> x + y)
        Specified by:
        foldRight in interface Foldable<T>
        Type Parameters:
        U - the targeted type of combination method
        Parameters:
        start - the start value for the fold operation
        combiner - the operation used to combine elements
        Returns:
        the folded value

      • get

        default T get()
        Fetch the head of the collection and return it. The following operations will all return the same value for a non empty collection. 
          Collection(0, 1).get();
   Collection(0, 1).head();
        The caller must verify the collection is not empty using either size() or isEmpty() to prevent a NoSuchElementException to be thrown.
        Specified by:
        get in interface Value<T>
        Returns:
        the first element in the collection
        Throws:
        java.util.NoSuchElementException - when there are no elements
        See Also:
        head()

      • head

        T head()
        Fetch the head of the collection and return it. The following operations will all return the same value for a non empty collection. 
          Collection(0, 1).get();
   Collection(0, 1).head();
        The caller must verify the collection is not empty using either size() or isEmpty() to prevent a NoSuchElementException to be thrown.
        Returns:
        the first element in the collection
        Throws:
        java.util.NoSuchElementException - if the collection is #isEmpty

      • isEmpty

        default boolean isEmpty()
        Convenience method to see if the current list is empty or not. This method will yield the same result as checking if the size() returns the value 0.
        Returns:
        true if the list contains elements, otherwise false
        See Also:
        size()

      • isSingleValued

        default boolean isSingleValued()
        Description copied from interface: Value
        Is this instance single-valued or not.
        Specified by:
        isSingleValued in interface Value<T>
        Returns:
        true if single-valued, otherwise false

      • last

        default Optional<T> last​(java.util.function.Predicate<T> predicate)
        Description copied from interface: Traversable
        Find the last match in the Iterator using the provided Predicate. The returned Optional is null safe and will either contain the element or be an empty Optional.

        Example:

        // the result will be an Optional with the value 4
    int firstMatch = Collection(1, 2, 3, 4)
          .last(i -> i % 2 == 0);
        Specified by:
        last in interface Traversable<T>
        Parameters:
        predicate - the predicate to use
        Returns:
        the last match found

      • map

        <U> Collection<U> map​(java.util.function.Function<T,​U> mapper)
        Description copied from interface: Streamable
        Perform a mapping operation on the elements in the stream.

        This operation will loop over all elements in the stream and apply the mapper method. The mapped values will be returned in as a new stream of elements.

        Specified by:
        map in interface Streamable<T>
        Specified by:
        map in interface Traversable<T>
        Type Parameters:
        U - the type of object expected as a result
        Parameters:
        mapper - the mapping functionality
        Returns:
        the mapped object

      • orElse

        Collection<T> orElse​(java.lang.Iterable<? extends T> other)
        Description copied from interface: Traversable
        Returns either this if it is non empty, otherwise will return the provided other.
        Specified by:
        orElse in interface Traversable<T>
        Parameters:
        other - the alternative
        Returns:
        this Traversable if non empty, or other

      • orElse

        Collection<T> orElse​(java.util.function.Supplier<? extends java.lang.Iterable<? extends T>> supplier)
        Description copied from interface: Traversable
        Returns either this if it is non empty, otherwise the provided supplier is evaluated and returned.
        Specified by:
        orElse in interface Traversable<T>
        Parameters:
        supplier - the supplier to generate the other
        Returns:
        this (@code Traversable} if non empty, otherwise other

      • reduceLeft

        default T reduceLeft​(java.util.function.BiFunction<? super T,​? super T,​? extends T> reducer)
        Description copied from interface: Foldable

        Reduce the collection from the left, starting with the first element in the collection and successively calling the reducer until there are no more elements.

        Example: 

        // result "test"
    List("t", "e", "s", "t").reduceLeft((x, y) -> x + y)

        This operation is similar to the Foldable.foldLeft(Object, BiFunction) where the first element is the head of the elements.

        Specified by:
        reduceLeft in interface Foldable<T>
        Parameters:
        reducer - the operation to use to reduce the elements to one value
        Returns:
        the reduced value
        See Also:
        Foldable.foldLeft(Object, BiFunction)

      • reject

        Collection<T> reject​(java.util.function.Predicate<T> predicate)
        Description copied from interface: Traversable
        Return a list that removes all elements that match the predicate provided.
        Specified by:
        reject in interface Traversable<T>
        Parameters:
        predicate - the predicate to use
        Returns:
        the elements that do not match the predicate

      • split

        Pair<? extends Collection<T>,​? extends Collection<T>> split​(java.util.function.Predicate<T> predicate)
        The split operation is an execution that combines the reject(Predicate) and the filter(Predicate) methods into one. Separating the values into 2 separate buckets. The first bucket will contain the same as the filter(Predicate) operation. The second bucket will contain the result of the reject(Predicate) operation.
        Parameters:
        predicate - the predicate to use
        Returns:
        the two buckets of this operation

      • size

        int size()
        Get the amount of elements contained in the collection.
        Returns:
        0 if empty, otherwise the amount of entries

      • summing

        default long summing​(java.util.function.BiFunction<java.lang.Long,​T,​java.lang.Long> accumulator)
        Sum all elements using the provided accumulator. This reduces the Collection to a single numbered value.
        Parameters:
        accumulator - the accumulator to be used
        Returns:
        the resulting value
        Throws:
        java.lang.NullPointerException - in case accumulator is null

      • tail

        Collection<T> tail()
        Build a new collection with all elements except for the head. If there is only one element present then an empty collection will be returned. If the operation is called on an empty collection an NoSuchElementException will be thrown.
        Returns:
        a collection containing the tail
        Throws:
        java.util.NoSuchElementException - if the collection is #isEmpty