FirstRankCollector

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

Example Usage

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

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

Default to collecting into a list and using natural ordering

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

Specify downstream collector and comparator

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

Example Use Case

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))));

Performance

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

	comparisons	downstream accumulations	downstream accumulators instantiated	iterations
best case	n	m	1	1
worst case	n	n	n - m + 1	1

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.

Slower Alternative: Group by value, sort keys, select group by first-ranked key

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

Slower Alternative: Find min value, filter other values

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