An implementation of Java 8's java.util.stream.Collector that collects only elements that tie for the minimum or maximum element. The stream being collected does not need to already be sorted. For example, in an array of {"b", "a", "a"}, both "a" strings will be collected, but not "b".

Supports null values. Maintains stream encounter order.

For instructions on how to include this library using Maven or Gradle visit https://jitpack.io/#davidleston/FirstRankCollector/v3.0.1

FirstRankCollector.multiMin collects elements that tie for the minimum element.

FirstRankCollector.multiMax collects elements that tie for the maximum element.

List<T> firstRankedElements = stream.collect(FirstRankCollector.multiMin.byNaturalOrder())

List<T> firstRankedElements
  = stream.collect(FirstRankCollector.multiMin.compareByThenInto(downstreamCollector, comparator))

Given a collection of payments, find the payments that are for the highest amount. The collection of payments are sorted by payment number. Have the payments of the highest amount maintain sort order.

A relatively fast method to do this would be:

maxPaymentAmount = Collections
  .max(payments, Comparator.comparing(payment -> payment.amount))
  .amount;
paymentsOfTheHighestAmount = payments.stream()
  .filter(payment -> payment.amount == maxPaymentAmount)
  .collect(Collectors.toList());

This method requires two iterations through the collection. Using a FirstRankCollector will often be faster as it only requires one iteration through the collection:

paymentsOfTheHighestAmount = payments.stream()
  .collect(FirstRankCollector.create(
    Comparator.reverseOrder(Comparator.comparing(payment -> payment.amount))));  

Given a stream of n elements with m first-ranked elements:

Best case is when all first-ranked elements are at the beginning of the stream. Worst case is when the stream is in reverse order and none of the elements that are not first-ranked are equal.

FirstRankCollector will often be faster than these alternatives.

stream.collect(Collectors.collectingAndThen(
  Collectors.groupingBy(Function.<String>identity()),
  map -> map.get(
    map.keySet()
      .stream()
      .sorted()
      .findFirst()
      .get()
    )
  )
)

T min = Collections.min(collection);
collection.stream()
  .filter(minValue::equals)
  .collect(Collectors.toList());