Package com.apple.foundationdb.async.common

Class DistinctTopK<T>

java.lang.Object
com.apple.foundationdb.async.common.DistinctTopK<T>
Type Parameters:
T - the type of element collected
public class DistinctTopK<T> extends Object
A fixed-capacity collector that retains the top k distinct elements offered, as ordered by a Comparator (the k that compare greatest). Duplicate elements are ignored, and once at capacity a new element is kept only if it compares strictly greater than the current worst, which it then evicts. Backed by a TreeSet, giving O(log k) add(Object).

  • Method Details

    • add

      public boolean add(@Nonnull T item)
      Offers an element to this collector. An element that compares equal (by the collector's Comparator, not equals) to one already retained is ignored — so an element tying the current worst counts as a duplicate and is rejected. Otherwise the element is kept if fewer than k elements are held, or if it compares strictly greater than the current worst, which it then evicts.
      Parameters:
      item - the element to offer
      Returns:
      true if the element was retained, false if it was a duplicate or was rejected

    • toSortedList

      public List<T> toSortedList()
      Returns the currently retained distinct elements ordered from greatest to least, as ranked by the comparator.
      Returns:
      the retained elements, sorted from best (greatest) to worst (least)

    • worstElement

      @Nonnull public Optional<T> worstElement()
      Returns the current worst retained element — the next one that would be evicted — or empty if none are held.
      Returns:
      the worst retained element, or Optional.empty() if the collector is empty

    • collect

      @Nonnull public CompletableFuture<List<T>> collect(AsyncIterable<T> iterable, Executor executor)
      Offers every element produced by the given iterable to this collector and returns the retained distinct top-K as a sorted list.
      Parameters:
      iterable - the elements to offer
      executor - the executor to use for asynchronous iteration
      Returns:
      a future completing with the retained distinct top-K elements, sorted from best to worst

    • collectRemaining

      public CompletableFuture<List<T>> collectRemaining(AsyncIterator<T> iterator, Executor executor)
      Exhausts the iterator, offering every element to this distinct top-K collector, and returns the retained distinct top-K elements as a sorted list.
      Parameters:
      iterator - the source of data over which to iterate. This function will exhaust the iterator.
      executor - the Executor to use for asynchronous operations
      Returns:
      a CompletableFuture completing with the retained distinct top-K elements, sorted

    • min

      @Nonnull public static <T> DistinctTopK<T> min(@Nonnull Comparator<T> comparator, int k)
      Creates a collector that retains the k smallest distinct elements offered, as ordered by the given comparator.
      Type Parameters:
      T - the type of element collected
      Parameters:
      comparator - the comparator defining element order
      k - the maximum number of distinct elements to retain; must be positive
      Returns:
      a new collector retaining the k smallest distinct elements
      Throws:
      IllegalArgumentException - if k is not positive

    • max

      @Nonnull public static <T> DistinctTopK<T> max(@Nonnull Comparator<T> comparator, int k)
      Creates a collector that retains the k largest distinct elements offered, as ordered by the given comparator.
      Type Parameters:
      T - the type of element collected
      Parameters:
      comparator - the comparator defining element order
      k - the maximum number of distinct elements to retain; must be positive
      Returns:
      a new collector retaining the k largest distinct elements
      Throws:
      IllegalArgumentException - if k is not positive