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: You should almost always pass immutable list as the parameter because for max efficiency this method will attempt to return the list instance as is when all elements match the predicate, making it an accidental "view"; but if you later change list's content, it may break expectations from your code that all elements in the filter()'ed list shall match the predicate.

      Since:
      10.7