Class MoreCollections

java.lang.Object
com.google.mu.collect.MoreCollections
public final class MoreCollections extends Object
Utilities pertaining to Collection.
Since:
8.0

  • Method Summary

    Modifier and Type
    Method
    Description
    static <T> List<T>
    filter(List<T> list, Predicate<? super T> predicate)
    Returns a list containing the elements of the given list that match the given predicate.
    static <T,R> Optional<R>
    findFirstElements(Collection<T> collection, MapFrom3<? super T, ? extends R> found)
    If collection has at least 3 elements, passes the first 3 elements to found function and returns the non-null result wrapped in an Optional, or else returns Optional.empty().
    static <T,R> Optional<R>
    findFirstElements(Collection<T> collection, MapFrom4<? super T, ? extends R> found)
    If collection has at least 4 elements, passes the first 4 elements to found function and returns the non-null result wrapped in an Optional, or else returns Optional.empty().
    static <T,R> Optional<R>
    findFirstElements(Collection<T> collection, MapFrom5<? super T, ? extends R> found)
    If collection has at least 5 elements, passes the first 5 elements to found function and returns the non-null result wrapped in an Optional, or else returns Optional.empty().
    static <T,R> Optional<R>
    findFirstElements(Collection<T> collection, MapFrom6<? super T, ? extends R> found)
    If collection has at least 6 elements, passes the first 6 elements to found function and returns the non-null result wrapped in an Optional, or else returns Optional.empty().
    static <T,R> Optional<R>
    findFirstElements(Collection<T> collection, MapFrom7<? super T, ? extends R> found)
    If collection has at least 7 elements, passes the first 6 elements to found function and returns the non-null result wrapped in an Optional, or else returns Optional.empty().
    static <T,R> Optional<R>
    findFirstElements(Collection<T> collection, MapFrom8<? super T, ? extends R> found)
    If collection has at least 8 elements, passes the first 6 elements to found function and returns the non-null result wrapped in an Optional, or else returns Optional.empty().
    static <T,R> Optional<R>
    findFirstElements(Collection<T> collection, BiFunction<? super T, ? super T, ? extends R> found)
    If collection has at least two elements, passes the first two elements to found function and returns the non-null result wrapped in an Optional, or else returns Optional.empty().
    static <T,R> Optional<R>
    findOnlyElements(Collection<T> collection, MapFrom3<? super T, ? extends R> found)
    If collection has exactly 3 elements, passes the 3 elements to found function and returns the non-null result wrapped in an Optional, or else returns Optional.empty().
    static <T,R> Optional<R>
    findOnlyElements(Collection<T> collection, MapFrom4<? super T, ? extends R> found)
    If collection has exactly 4 elements, passes the 4 elements to found function and returns the non-null result wrapped in an Optional, or else returns Optional.empty().
    static <T,R> Optional<R>
    findOnlyElements(Collection<T> collection, MapFrom5<? super T, ? extends R> found)
    If collection has exactly 5 elements, passes the 5 elements to found function and returns the non-null result wrapped in an Optional, or else returns Optional.empty().
    static <T,R> Optional<R>
    findOnlyElements(Collection<T> collection, MapFrom6<? super T, ? extends R> found)
    If collection has exactly 6 elements, passes the 6 elements to found function and returns the non-null result wrapped in an Optional, or else returns Optional.empty().
    static <T,R> Optional<R>
    findOnlyElements(Collection<T> collection, MapFrom7<? super T, ? extends R> found)
    If collection has exactly 7 elements, passes the 6 elements to found function and returns the non-null result wrapped in an Optional, or else returns Optional.empty().
    static <T,R> Optional<R>
    findOnlyElements(Collection<T> collection, MapFrom8<? super T, ? extends R> found)
    If collection has exactly 8 elements, passes the 6 elements to found function and returns the non-null result wrapped in an Optional, or else returns Optional.empty().
    static <T,R> Optional<R>
    findOnlyElements(Collection<T> collection, BiFunction<? super T, ? super T, ? extends R> found)
    If collection has exactly two elements, passes the two elements to found function and returns the non-null result wrapped in an Optional, or else returns Optional.empty().

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Method Details

    • findFirstElements

      public static <T,R> Optional<R> findFirstElements(Collection<T> collection, BiFunction<? super T, ? super T, ? extends R> found)
      If collection has at least two elements, passes the first two elements to found function and returns the non-null result wrapped in an Optional, or else returns Optional.empty().
      Throws:
      NullPointerException - if collection or found function is null, or if found function returns null.

    • findFirstElements

      public static <T,R> Optional<R> findFirstElements(Collection<T> collection, MapFrom3<? super T, ? extends R> found)
      If collection has at least 3 elements, passes the first 3 elements to found function and returns the non-null result wrapped in an Optional, or else returns Optional.empty().
      Throws:
      NullPointerException - if collection or found function is null, or if found function returns null.

    • findFirstElements

      public static <T,R> Optional<R> findFirstElements(Collection<T> collection, MapFrom4<? super T, ? extends R> found)
      If collection has at least 4 elements, passes the first 4 elements to found function and returns the non-null result wrapped in an Optional, or else returns Optional.empty().
      Throws:
      NullPointerException - if collection or found function is null, or if found function returns null.

    • findFirstElements

      public static <T,R> Optional<R> findFirstElements(Collection<T> collection, MapFrom5<? super T, ? extends R> found)
      If collection has at least 5 elements, passes the first 5 elements to found function and returns the non-null result wrapped in an Optional, or else returns Optional.empty().
      Throws:
      NullPointerException - if collection or found function is null, or if found function returns null.

    • findFirstElements

      public static <T,R> Optional<R> findFirstElements(Collection<T> collection, MapFrom6<? super T, ? extends R> found)
      If collection has at least 6 elements, passes the first 6 elements to found function and returns the non-null result wrapped in an Optional, or else returns Optional.empty().
      Throws:
      NullPointerException - if collection or found function is null, or if found function returns null.

    • findFirstElements

      public static <T,R> Optional<R> findFirstElements(Collection<T> collection, MapFrom7<? super T, ? extends R> found)
      If collection has at least 7 elements, passes the first 6 elements to found function and returns the non-null result wrapped in an Optional, or else returns Optional.empty().
      Throws:
      NullPointerException - if collection or found function is null, or if found function returns null.
      Since:
      7.2

    • findFirstElements

      public static <T,R> Optional<R> findFirstElements(Collection<T> collection, MapFrom8<? super T, ? extends R> found)
      If collection has at least 8 elements, passes the first 6 elements to found function and returns the non-null result wrapped in an Optional, or else returns Optional.empty().
      Throws:
      NullPointerException - if collection or found function is null, or if found function returns null.
      Since:
      7.2

    • findOnlyElements

      public static <T,R> Optional<R> findOnlyElements(Collection<T> collection, BiFunction<? super T, ? super T, ? extends R> found)
      If collection has exactly two elements, passes the two elements to found function and returns the non-null result wrapped in an Optional, or else returns Optional.empty().
      Throws:
      NullPointerException - if collection or found function is null, or if found function returns null.

    • findOnlyElements

      public static <T,R> Optional<R> findOnlyElements(Collection<T> collection, MapFrom3<? super T, ? extends R> found)
      If collection has exactly 3 elements, passes the 3 elements to found function and returns the non-null result wrapped in an Optional, or else returns Optional.empty().
      Throws:
      NullPointerException - if collection or found function is null, or if found function returns null.

    • findOnlyElements

      public static <T,R> Optional<R> findOnlyElements(Collection<T> collection, MapFrom4<? super T, ? extends R> found)
      If collection has exactly 4 elements, passes the 4 elements to found function and returns the non-null result wrapped in an Optional, or else returns Optional.empty().
      Throws:
      NullPointerException - if collection or found function is null, or if found function returns null.

    • findOnlyElements

      public static <T,R> Optional<R> findOnlyElements(Collection<T> collection, MapFrom5<? super T, ? extends R> found)
      If collection has exactly 5 elements, passes the 5 elements to found function and returns the non-null result wrapped in an Optional, or else returns Optional.empty().
      Throws:
      NullPointerException - if collection or found function is null, or if found function returns null.

    • findOnlyElements

      public static <T,R> Optional<R> findOnlyElements(Collection<T> collection, MapFrom6<? super T, ? extends R> found)
      If collection has exactly 6 elements, passes the 6 elements to found function and returns the non-null result wrapped in an Optional, or else returns Optional.empty().
      Throws:
      NullPointerException - if collection or found function is null, or if found function returns null.

    • findOnlyElements

      public static <T,R> Optional<R> findOnlyElements(Collection<T> collection, MapFrom7<? super T, ? extends R> found)
      If collection has exactly 7 elements, passes the 6 elements to found function and returns the non-null result wrapped in an Optional, or else returns Optional.empty().
      Throws:
      NullPointerException - if collection or found function is null, or if found function returns null.
      Since:
      7.2

    • findOnlyElements

      public static <T,R> Optional<R> findOnlyElements(Collection<T> collection, MapFrom8<? super T, ? extends R> found)
      If collection has exactly 8 elements, passes the 6 elements to found function and returns the non-null result wrapped in an Optional, or else returns Optional.empty().
      Throws:
      NullPointerException - if collection or found function is null, or if found function returns null.
      Since:
      7.2

    • filter

      public static <T> List<T> filter(List<T> list, Predicate<? super T> predicate)
      Returns a list containing the elements of the given list that match the given predicate.

      This method optimizes for small lists: Java stream performs well for medium and large lists but for small lists (in reality, lists with size() <= 64 happen pretty frequently), the streaming overhead often dominates the cost of smallList.filter(...).toList(). So if you have a small list to filter, consider using this method to significantly optimize for the common case.

      • For empty lists (n = 0), returns the original list with zero allocation.
      • For size <= 64, if all elements match, returns the original list directly (zero allocation).
      • If only one element matches (or none match), returns a singleton list or empty list (extremely low allocation).
      • If only some elements match, returns an unmodifiable list constructed without stream overhead.

      Benchmark results (JVM: JDK 24.0.1, Throughput in ops/sec): 

      
   Size | Match Rate | MoreCollections.filter | stream().toList() | Speedup
   -----+------------+------------------------+-------------------+--------
      0 |       0%   |         1,806,612,304  |       59,190,909  |  30.5x
      1 |       0%   |           566,995,008  |       54,823,907  |  10.3x
      1 |     100%   |           495,301,391  |       39,685,261  |  12.5x
      2 |       0%   |           505,644,734  |       53,630,247  |   9.4x
      2 |      50%   |           283,244,290  |       39,977,345  |   7.1x
      2 |     100%   |           442,565,514  |       39,739,454  |  11.1x
      3 |       0%   |           387,272,751  |       51,906,625  |   7.5x
      3 |      67%   |           109,216,394  |       39,212,813  |   2.8x
      3 |     100%   |           360,620,020  |       38,529,116  |   9.4x
      5 |      60%   |            90,403,444  |       37,834,798  |   2.4x
      5 |     100%   |           302,455,379  |       35,991,628  |   8.4x
     10 |      50%   |            67,698,128  |       32,944,167  |   2.1x
     10 |     100%   |           214,023,158  |       31,440,482  |   6.8x
     32 |      25%   |            32,202,952  |       21,422,676  |   1.5x
     32 |      50%   |            24,473,961  |       20,212,588  |   1.2x
     32 |     100%   |            95,754,817  |        7,102,417  |  13.5x
     64 |      25%   |            17,305,317  |       13,270,806  |   1.3x
     64 |      50%   |            10,408,078  |        5,498,968  |   1.9x
     64 |     100%   |            53,600,935  |        3,990,547  |  13.4x
   -----+------------+------------------------+-------------------+--------
     70 |      25%   |             9,052,802  |        8,118,966  |  1.11x
     70 |      50%   |             6,929,459  |        3,924,459  |  1.76x
     70 |     100%   |             4,994,682  |        3,949,838  |  1.26x
     80 |      25%   |             8,485,679  |        8,046,057  |  1.05x
     80 |      50%   |             6,346,297  |        3,569,342  |  1.77x
     80 |     100%   |             4,481,216  |        3,506,878  |  1.27x
    100 |      25%   |             6,868,235  |        7,036,688  |  0.98x
    100 |      50%   |             5,238,215  |        3,114,895  |  1.68x
    100 |     100%   |             3,449,274  |        2,909,303  |  1.18x

      Note: If the input list is mutated concurrently while being filtered, the behavior of this method is unspecified.

      Since:
      10.7