Package io.microsphere.lang.function

Interface Streams

  • public interface Streams
    The utilities class for Stream
    Since:
    1.0.0
    Author:
    Mercy

    • Method Summary

      Static Methods 
      Modifier and Type Method Description
      static <T,​S extends java.lang.Iterable<T>>
      S      		 filter​(S values, java.util.function.Predicate<? super T> predicate)
      Filters elements from the given Iterable using the provided Predicate and returns a collection of the same type as the input, either a List or a Set.
      static <T,​S extends java.lang.Iterable<T>>
      S      		 filterAll​(S values, java.util.function.Predicate<? super T>... predicates)
      Filters elements from the given Iterable using the combined result of multiple predicates in a logical AND fashion.
      static <T> java.util.List<T> filterAllList​(T[] values, java.util.function.Predicate<? super T>... predicates)
      Filters elements from the given array using the combined result of multiple predicates in a logical AND fashion, and returns a List containing the matching elements.
      static <T> java.util.Set<T> filterAllSet​(T[] values, java.util.function.Predicate<? super T>... predicates)
      Filters elements from the given array using the combined result of multiple predicates in a logical AND fashion, and returns a Set containing the matching elements.
      static <T,​S extends java.lang.Iterable<T>>
      S      		 filterAny​(S values, java.util.function.Predicate<? super T>... predicates)
      Filters elements from the given Iterable using the combined result of multiple predicates in a logical OR fashion.
      static <T> java.util.List<T> filterAnyList​(T[] values, java.util.function.Predicate<? super T>... predicates)
      Filters elements from the given array using the combined result of multiple predicates in a logical OR fashion, and returns a List containing the matching elements.
      static <T> java.util.Set<T> filterAnySet​(T[] values, java.util.function.Predicate<? super T>... predicates)
      Filters elements from the given array using the combined result of multiple predicates in a logical OR fashion, and returns a Set containing the matching elements.
      static <T> T filterFirst​(java.lang.Iterable<T> values, java.util.function.Predicate<? super T>... predicates)
      Filters elements from the given Iterable using the combined result of multiple predicates in a logical AND fashion, and returns the first matching element.
      static <T,​S extends java.lang.Iterable<T>>
      java.util.List<T>      		 filterList​(S values, java.util.function.Predicate<? super T> predicate)
      Filters the elements from the given Iterable using the provided predicate and returns a List.
      static <T> java.util.List<T> filterList​(T[] values, java.util.function.Predicate<? super T> predicate)
      Filters the elements from the given array using the provided predicate and returns a List.
      static <T,​S extends java.lang.Iterable<T>>
      java.util.Set<T>      		 filterSet​(S values, java.util.function.Predicate<? super T> predicate)
      Filters elements from the given Iterable using the provided Predicate and collects the result into a new Set that maintains insertion order.
      static <T> java.util.Set<T> filterSet​(T[] values, java.util.function.Predicate<? super T> predicate)
      Filters the elements from the given array using the provided predicate and returns a Set.
      static <T,​S extends java.lang.Iterable<T>>
      java.util.stream.Stream<T>      		 filterStream​(S values, java.util.function.Predicate<? super T> predicate)
      Filters the elements from the provided Iterable using the given predicate and returns a Stream.
      static <T> java.util.stream.Stream<T> filterStream​(T[] values, java.util.function.Predicate<? super T> predicate)
      Filters the elements from the provided array using the given predicate and returns a Stream.
      static <T> java.util.stream.Stream<T> stream​(java.lang.Iterable<T> iterable)
      Creates a sequential Stream from the given Iterable.
      static <T> java.util.stream.Stream<T> stream​(T... values)
      Creates a sequential Stream from the given array of values.

    • Method Detail

      • stream

        @Nonnull
static <T> java.util.stream.Stream<T> stream​(T... values)
        Creates a sequential Stream from the given array of values.

        This method is useful for converting an array into a Stream to enable functional-style operations such as filtering, mapping, and collecting.

        Example Usage

        
 String[] names = {"Alice", "Bob", "Charlie"};
 Stream<String> stream = Streams.stream(names);
 stream.filter(name -> name.startsWith("A"))
       .forEach(System.out::println);  // Prints: Alice
        Type Parameters:
        T - the type of the stream elements
        Parameters:
        values - the array of elements to form the stream
        Returns:
        a sequential Stream backed by the given array

      • stream

        @Nonnull
static <T> java.util.stream.Stream<T> stream​(java.lang.Iterable<T> iterable)
        Creates a sequential Stream from the given Iterable.

        This method is useful for converting an Iterable (like a List or a Set) into a Stream, enabling functional-style operations such as filtering, mapping, and collecting.

        Example Usage

        
 List<String> names = Arrays.asList("Alice", "Bob", "Charlie");
 Stream<String> stream = Streams.stream(names);
 stream.filter(name -> name.startsWith("B"))
       .forEach(System.out::println);  // Prints: Bob
        Type Parameters:
        T - the type of the stream elements
        Parameters:
        iterable - the Iterable to convert into a stream
        Returns:
        a sequential Stream backed by the given iterable

      • filterStream

        @Nonnull
static <T> java.util.stream.Stream<T> filterStream​(T[] values,
                                                   java.util.function.Predicate<? super T> predicate)
        Filters the elements from the provided array using the given predicate and returns a Stream.

        This method creates a sequential stream from the input array, then applies the given predicate to retain only the elements that match the condition.

        Example Usage

        
 String[] names = {"Alice", "Bob", "Charlie"};
 Stream<String> filteredStream = Streams.filterStream(names, name -> name.startsWith("C"));
 filteredStream.forEach(System.out::println);  // Prints: Charlie
        Type Parameters:
        T - the type of the stream elements
        Parameters:
        values - the array of elements to be filtered
        predicate - the condition to apply to each element
        Returns:
        a filtered stream containing only the elements that satisfy the predicate

      • filterStream

        @Nonnull
static <T,​S extends java.lang.Iterable<T>> java.util.stream.Stream<T> filterStream​(S values,
                                                                                         java.util.function.Predicate<? super T> predicate)
        Filters the elements from the provided Iterable using the given predicate and returns a Stream.

        This method creates a sequential stream from the input Iterable, then applies the given predicate to retain only the elements that match the condition.

        Example Usage

        
 List<String> names = Arrays.asList("Alice", "Bob", "Charlie");
 Stream<String> filteredStream = Streams.filterStream(names, name -> name.startsWith("B"));
 filteredStream.forEach(System.out::println);  // Prints: Bob
        Type Parameters:
        T - the type of the stream elements
        Parameters:
        values - the Iterable to convert into a stream and apply filtering
        predicate - the condition to apply to each element
        Returns:
        a filtered stream containing only the elements that satisfy the predicate

      • filterList

        @Nonnull
static <T> java.util.List<T> filterList​(T[] values,
                                        java.util.function.Predicate<? super T> predicate)
        Filters the elements from the given array using the provided predicate and returns a List.

        This method converts the input array into a List, then applies the given predicate to retain only the elements that match the condition.

        Example Usage

        
 String[] names = {"Alice", "Bob", "Charlie"};
 List<String> filteredList = Streams.filterList(names, name -> name.startsWith("A"));
 System.out.println(filteredList);  // Output: [Alice]
        Type Parameters:
        T - the type of the elements in the array and list
        Parameters:
        values - the array of elements to be filtered
        predicate - the condition to apply to each element
        Returns:
        a list containing only the elements that satisfy the predicate

      • filterList

        @Nonnull
static <T,​S extends java.lang.Iterable<T>> java.util.List<T> filterList​(S values,
                                                                              java.util.function.Predicate<? super T> predicate)
        Filters the elements from the given Iterable using the provided predicate and returns a List.

        This method converts the input Iterable into a Stream, applies the given predicate to retain only the elements that match the condition, and then collects the result into a new List.

        Example Usage

        
 List<String> names = Arrays.asList("Alice", "Bob", "Charlie");
 List<String> filteredList = Streams.filterList(names, name -> name.startsWith("B"));
 System.out.println(filteredList);  // Output: [Bob]
        Type Parameters:
        T - the type of the elements in the iterable and list
        Parameters:
        values - the Iterable to convert into a stream and apply filtering
        predicate - the condition to apply to each element
        Returns:
        a list containing only the elements that satisfy the predicate

      • filterSet

        @Nonnull
static <T> java.util.Set<T> filterSet​(T[] values,
                                      java.util.function.Predicate<? super T> predicate)
        Filters the elements from the given array using the provided predicate and returns a Set.

        This method converts the input array into a new Set using SetUtils.ofSet(Object[]), then applies the given predicate to retain only the elements that match the condition.

        Example Usage

        
 String[] names = {"Alice", "Bob", "Charlie"};
 Set<String> filteredSet = Streams.filterSet(names, name -> name.startsWith("A"));
 System.out.println(filteredSet);  // Output: [Alice]
        Type Parameters:
        T - the type of the elements in the array and set
        Parameters:
        values - the array of elements to be filtered
        predicate - the condition to apply to each element
        Returns:
        a set containing only the elements that satisfy the predicate

      • filterSet

        @Nonnull
static <T,​S extends java.lang.Iterable<T>> java.util.Set<T> filterSet​(S values,
                                                                            java.util.function.Predicate<? super T> predicate)
        Filters elements from the given Iterable using the provided Predicate and collects the result into a new Set that maintains insertion order.

        This method is particularly useful when you need to:

        • Filter elements based on a condition
        • Maintain the insertion order of filtered results
        • Avoid duplicate elements during filtering

        Example Usage

        
 List<String> names = Arrays.asList("Alice", "Bob", "Charlie", "Anna");
 Set<String> filteredSet = Streams.filterSet(names, name -> name.startsWith("A"));
 System.out.println(filteredSet);  // Output: [Alice, Anna]
        Type Parameters:
        T - the type of the stream elements
        Parameters:
        values - the iterable containing elements to be filtered
        predicate - the condition used to include elements in the resulting set
        Returns:
        a new Set containing only the elements that satisfy the predicate, maintaining insertion order using a LinkedHashSet

      • filter

        @Nonnull
static <T,​S extends java.lang.Iterable<T>> S filter​(S values,
                                                          java.util.function.Predicate<? super T> predicate)
        Filters elements from the given Iterable using the provided Predicate and returns a collection of the same type as the input, either a List or a Set.

        This method intelligently handles both List and Set types by:

        Example Usage with List

        
 List<String> names = Arrays.asList("Alice", "Bob", "Charlie");
 List<String> filteredList = Streams.filter(names, name -> name.startsWith("B"));
 System.out.println(filteredList);  // Output: [Bob]

        Example Usage with Set

        
 Set<String> names = new LinkedHashSet<>(Arrays.asList("Alice", "Bob", "Charlie", "Anna"));
 Set<String> filteredSet = Streams.filter(names, name -> name.startsWith("A"));
 System.out.println(filteredSet);  // Output: [Alice, Anna]
        Type Parameters:
        T - the type of the stream elements
        S - the type of the iterable, either a list or set
        Parameters:
        values - the iterable containing elements to be filtered
        predicate - the condition used to include elements in the resulting collection
        Returns:
        a new collection of the same type as the input, containing only the elements that satisfy the predicate

      • filterAll

        @Nonnull
static <T,​S extends java.lang.Iterable<T>> S filterAll​(S values,
                                                             java.util.function.Predicate<? super T>... predicates)
        Filters elements from the given Iterable using the combined result of multiple predicates in a logical AND fashion.

        This method applies all provided predicates as a single condition where an element must satisfy all predicates to be included in the resulting collection. The return type matches the input's collection type (either a List or a Set) based on the same logic used by filter(Iterable, Predicate).

        Example Usage with List

        
 List<String> names = Arrays.asList("Alice", "Anna", "Bob", "Andrew");
 List<String> filtered = Streams.filterAll(names,
     name -> name.startsWith("A"),
     name -> name.length() > 4
 );
 System.out.println(filtered);  // Output: [Alice, Andrew]

        Example Usage with Set

        
 Set<String> names = new LinkedHashSet<>(Arrays.asList("Alice", "Anna", "Bob", "Andrew"));
 Set<String> filtered = Streams.filterAll(names,
     name -> name.startsWith("A"),
     name -> name.length() > 4
 );
 System.out.println(filtered);  // Output: [Alice, Andrew]
        Type Parameters:
        T - the type of the stream elements
        S - the type of the iterable, either a list or set
        Parameters:
        values - the iterable containing elements to be filtered
        predicates - the array of predicates to combine and apply to each element
        Returns:
        a new collection of the same type as the input, containing only the elements that satisfy all predicates

      • filterAllList

        @Nonnull
static <T> java.util.List<T> filterAllList​(T[] values,
                                           java.util.function.Predicate<? super T>... predicates)
        Filters elements from the given array using the combined result of multiple predicates in a logical AND fashion, and returns a List containing the matching elements.

        This method applies all provided predicates as a single condition where an element must satisfy all predicates to be included in the resulting list.

        Example Usage

        
 String[] names = {"Alice", "Anna", "Bob", "Andrew"};
 List<String> filtered = Streams.filterAllList(names,
     name -> name.startsWith("A"),
     name -> name.length() > 4
 );
 System.out.println(filtered);  // Output: [Alice, Andrew]
        Type Parameters:
        T - the type of the stream elements
        Parameters:
        values - the array containing elements to be filtered
        predicates - the array of predicates to combine and apply to each element
        Returns:
        a new List containing only the elements that satisfy all predicates

      • filterAllSet

        @Nonnull
static <T> java.util.Set<T> filterAllSet​(T[] values,
                                         java.util.function.Predicate<? super T>... predicates)
        Filters elements from the given array using the combined result of multiple predicates in a logical AND fashion, and returns a Set containing the matching elements.

        This method applies all provided predicates as a single condition where an element must satisfy all predicates to be included in the resulting set. The returned Set maintains insertion order using a LinkedHashSet.

        Example Usage

        
 String[] names = {"Alice", "Anna", "Bob", "Andrew"};
 Set<String> filtered = Streams.filterAllSet(names,
     name -> name.startsWith("A"),
     name -> name.length() > 4
 );
 System.out.println(filtered);  // Output: [Alice, Andrew]
        Type Parameters:
        T - the type of the stream elements
        Parameters:
        values - the array containing elements to be filtered
        predicates - the array of predicates to combine and apply to each element
        Returns:
        a new Set containing only the elements that satisfy all predicates, maintaining insertion order using a LinkedHashSet

      • filterAny

        @Nonnull
static <T,​S extends java.lang.Iterable<T>> S filterAny​(S values,
                                                             java.util.function.Predicate<? super T>... predicates)
        Filters elements from the given Iterable using the combined result of multiple predicates in a logical OR fashion.

        This method applies all provided predicates as a single condition where an element must satisfy at least one predicate to be included in the resulting collection. The return type matches the input's collection type (either a List or a Set) based on the same logic used by filter(Iterable, Predicate).

        Example Usage with List

        
 List<String> names = Arrays.asList("Alice", "Anna", "Bob", "Andrew");
 List<String> filtered = Streams.filterAny(names,
     name -> name.startsWith("B"),
     name -> name.length() <= 3
 );
 System.out.println(filtered);  // Output: [Anna, Bob]

        Example Usage with Set

        
 Set<String> names = new LinkedHashSet<>(Arrays.asList("Alice", "Anna", "Bob", "Andrew"));
 Set<String> filtered = Streams.filterAny(names,
     name -> name.startsWith("B"),
     name -> name.length() <= 3
 );
 System.out.println(filtered);  // Output: [Anna, Bob]
        Type Parameters:
        T - the type of the stream elements
        S - the type of the iterable, either a list or set
        Parameters:
        values - the iterable containing elements to be filtered
        predicates - the array of predicates to combine and apply to each element
        Returns:
        a new collection of the same type as the input, containing only the elements that satisfy at least one predicate

      • filterAnyList

        @Nonnull
static <T> java.util.List<T> filterAnyList​(T[] values,
                                           java.util.function.Predicate<? super T>... predicates)
        Filters elements from the given array using the combined result of multiple predicates in a logical OR fashion, and returns a List containing the matching elements.

        This method applies all provided predicates as a single condition where an element must satisfy at least one predicate to be included in the resulting list. The order of elements is preserved, and duplicates are allowed if they exist in the input array.

        Example Usage

        
 String[] names = {"Alice", "Anna", "Bob", "Andrew"};
 List<String> filtered = Streams.filterAnyList(names,
     name -> name.startsWith("B"),
     name -> name.length() <= 3
 );
 System.out.println(filtered);  // Output: [Anna, Bob]
        Type Parameters:
        T - the type of the stream elements
        Parameters:
        values - the array containing elements to be filtered
        predicates - the array of predicates to combine and apply to each element
        Returns:
        a new List containing only the elements that satisfy at least one predicate

      • filterAnySet

        @Nonnull
static <T> java.util.Set<T> filterAnySet​(T[] values,
                                         java.util.function.Predicate<? super T>... predicates)
        Filters elements from the given array using the combined result of multiple predicates in a logical OR fashion, and returns a Set containing the matching elements.

        This method applies all provided predicates as a single condition where an element must satisfy at least one predicate to be included in the resulting set. The returned Set maintains insertion order using a LinkedHashSet.

        Example Usage

        
 String[] names = {"Alice", "Anna", "Bob", "Andrew"};
 Set<String> filtered = Streams.filterAnySet(names,
     name -> name.startsWith("B"),
     name -> name.length() <= 3
 );
 System.out.println(filtered);  // Output: [Anna, Bob]
        Type Parameters:
        T - the type of the stream elements
        Parameters:
        values - the array containing elements to be filtered
        predicates - the array of predicates to combine and apply to each element
        Returns:
        a new Set containing only the elements that satisfy at least one predicate, maintaining insertion order using a LinkedHashSet

      • filterFirst

        @Nullable
static <T> T filterFirst​(java.lang.Iterable<T> values,
                         java.util.function.Predicate<? super T>... predicates)
        Filters elements from the given Iterable using the combined result of multiple predicates in a logical AND fashion, and returns the first matching element.

        This method applies all provided predicates as a single condition where an element must satisfy all predicates to be considered a match. It returns the first such element found, or null if no element matches.

        If the input is a List, the method respects the list's iteration order. For a Set, especially a LinkedHashSet, it maintains insertion order during filtering.

        Example Usage with List

        
 List<String> names = Arrays.asList("Alice", "Anna", "Bob", "Andrew");
 String result = Streams.filterFirst(names,
     name -> name.startsWith("A"),
     name -> name.length() > 4
 );
 System.out.println(result);  // Output: Alice

        Example Usage with Set

        
 Set<String> names = new LinkedHashSet<>(Arrays.asList("Alice", "Anna", "Bob", "Andrew"));
 String result = Streams.filterFirst(names,
     name -> name.startsWith("A"),
     name -> name.length() > 4
 );
 System.out.println(result);  // Output: Alice
        Type Parameters:
        T - the type of the stream elements
        Parameters:
        values - the iterable containing elements to be filtered
        predicates - the array of predicates to combine and apply to each element
        Returns:
        the first element that satisfies all predicates, or null if none match