graph-builder

import { Comparator } from "./Comparator"; /** * A comparator, with additional methods to support common operations. This is an "enriched" version * of `Comparator` for pre-Java-8 users, in the same sense that {@link FluentIterable} is an * enriched {@link Iterable} for pre-Java-8 users. * * @remarks * * **Three types of methods** * * Like other fluent types, there are three types of methods present: methods for acquiring, * chaining, and using. * * <h4>Acquiring</h4> * * The common ways to get an instance of `Ordering` are: * * <ul> * <li>Subclass it and implement {@link compare} instead of implementing {@link Comparator} * directly * <li>Pass a pre-existing {@link Comparator} instance to {@link from} * <li>Use the natural ordering, {@link Ordering.natural} * </ul> * * <h4>Chaining</h4> * * Then you can use the chaining methods to get an altered version of that * `Ordering`, including: * * <ul> * <li>{@link reverse} * <li>{@link compound} * <li>{@link onResultOf} * <li>{@link nullsFirst} / {@link nullsLast} * </ul> * * <h4>Using</h4> * * Finally, use the resulting `Ordering` anywhere a {@link Comparator} is required, or use * any of its special operations, such as: * * <ul> * <li>{@link immutableSortedCopy} * <li>{@link isOrdered} / {@link isStrictlyOrdered} * <li>{@link min} / {@link max} * </ul> * * **Understanding complex orderings** * * Complex chained orderings like the following example can be challenging to understand. * * ```typescript * Ordering<Foo> ordering = * Ordering.natural() * .nullsFirst() * .onResultOf(getBarFunction) * .nullsLast(); * ``` * * Note that each chaining method returns a new ordering instance which is backed by the previous * instance, but has the chance to act on values before handing off to that backing instance. * As a result, it usually helps to read chained ordering expressions backwards. For example, * when `compare` is called on the above ordering: * * <ol> * <li>First, if only one `Foo` is null, that null value is treated as greater * <li>Next, non-null `Foo` values are passed to `getBarFunction` (we will be * comparing `Bar` values from now on) * <li>Next, if only one `Bar` is null, that null value is treated as lesser * <li>Finally, natural ordering is used (i.e. the result of `Bar.compareTo(Bar)` is * returned) * </ol> * * Alas, {@link reverse} is a little different. As you read backwards through a chain and * encounter a call to `reverse`, continue working backwards until a result is determined, and * then reverse that result. * * **Additional notes** * * Except as noted, the orderings returned by the factory methods of this class are serializable * if and only if the provided instances that back them are. For example, if `ordering` and * `function` can themselves be serialized, then `ordering.onResultOf(function)` can as * well. * * **For Java 8 users** * * If you are using Java 8, this class is now obsolete. Most of its functionality is now provided * by {@link java.util.stream.Stream Stream} and by {@link Comparator} itself, and the rest can now * be found as static methods in our new {@link Comparators} class. See each method below for * further instructions. Whenever possible, you should change any references of type * `Ordering` to be of type `Comparator` instead. However, at this time we have no plan to * deprecate this class. * * Many replacements involve adopting `Stream`, and these changes can sometimes make your * code verbose. Whenever following this advice, you should check whether `Stream` could be * adopted more comprehensively in your code; the end result may be quite a bit simpler. * * **See also** * * See the Guava User Guide article on <a href= * "https://github.com/google/guava/wiki/OrderingExplained">`Ordering`</a>. */ export declare abstract class Ordering<T> implements Comparator<T> { abstract compare(left: T, right: T): number; /** * Returns the least of the specified values according to this ordering. If there are multiple * least values, the first of those is returned. The iterator will be left exhausted: its * `hasNext` method will return `false`. * * Java 8 users: Continue to use this method for now. After the next release of Guava, * use `Streams.stream(iterator).min(thisComparator).get()` instead (but note that it does * not guarantee which tied minimum element is returned). * * @param iterator the iterator whose minimum element is to be determined * throws NoSuchElementException if `iterator` is empty * throws ClassCastException if the parameters are not mutually comparable under this * ordering. */ min<E extends T>(iterator: Iterator<E>): E; /** * Returns the lesser of the two values according to this ordering. If the values compare as 0, * the first is returned. * * Implementation note: this method is invoked by the default implementations of the * other `min` overloads, so overriding it will affect their behavior. * * Java 8 users: Use `Collections.min(Arrays.asList(a, b), thisComparator)` * instead (but note that it does not guarantee which tied minimum element is returned). * * @param a value to compare, returned if less than or equal to b. * @param b value to compare. * throws ClassCastException if the parameters are not mutually comparable under this * ordering. */ minOf<E extends T>(a: E, b: E): E; /** * Returns the greatest of the specified values according to this ordering. If there are multiple * greatest values, the first of those is returned. The iterator will be left exhausted: its * `hasNext()` method will return `false`. * * Java 8 users: Continue to use this method for now. After the next release of Guava, * use `Streams.stream(iterator).max(thisComparator).get()` instead (but note that it does * not guarantee which tied maximum element is returned). * * @param iterator the iterator whose maximum element is to be determined * throws NoSuchElementException if `iterator` is empty * throws ClassCastException if the parameters are not mutually comparable under this * ordering. */ max<E extends T>(iterator: Iterator<E>): E; /** * Returns the greater of the two values according to this ordering. If the values compare as 0, * the first is returned. * * Implementation note: this method is invoked by the default implementations of the * other `max` overloads, so overriding it will affect their behavior. * * Java 8 users: Use `Collections.max(Arrays.asList(a, b), thisComparator)` * instead (but note that it does not guarantee which tied maximum element is returned). * * @param a value to compare, returned if greater than or equal to b. * @param b value to compare. * throws ClassCastException if the parameters are not mutually comparable under this * ordering. */ maxOf<E extends T>(a: E, b: E): E; /** * Returns the `k` least elements from the given iterator according to this ordering, in * order from least to greatest. If there are fewer than `k` elements present, all will be * included. * * The implementation does not necessarily use a stable sorting algorithm; when multiple * elements are equivalent, it is undefined which will come first. * * Java 8 users: Continue to use this method for now. After the next release of Guava, * use `Streams.stream(iterator).collect(Comparators.least(k, thisComparator))` instead. * * @returns an immutable `RandomAccess` list of the `k` least elements in ascending * order * throws IllegalArgumentException if `k` is negative */ /** * Returns the `k` greatest elements of the given iterable according to this ordering, in * order from greatest to least. If there are fewer than `k` elements present, all will be * included. * * The implementation does not necessarily use a stable sorting algorithm; when multiple * elements are equivalent, it is undefined which will come first. * * @returns an immutable `RandomAccess` list of the `k` greatest elements in * descending order * throws IllegalArgumentException if `k` is negative */ /** * Returns the `k` greatest elements from the given iterator according to this ordering, in * order from greatest to least. If there are fewer than `k` elements present, all will be * included. * * The implementation does not necessarily use a stable sorting algorithm; when multiple * elements are equivalent, it is undefined which will come first. * * Java 8 users: Continue to use this method for now. After the next release of Guava, * use `Streams.stream(iterator).collect(Comparators.greatest(k, thisComparator))` instead. * * @returns an immutable `RandomAccess` list of the `k` greatest elements in * descending order * throws IllegalArgumentException if `k` is negative */ /** * Returns a mutable list containing `elements` sorted by this ordering; use this * only when the resulting list may need further modification, or may contain `null`. The * input is not modified. The returned list is serializable and has random access. * * Unlike {@link Sets.newTreeSet}, this method does not discard elements that are * duplicates according to the comparator. The sort performed is stable, meaning that such * elements will appear in the returned list in the same order they appeared in `elements`. * * Performance note: According to our * benchmarking * on Open JDK 7, {@link immutableSortedCopy} generally performs better (in both time and space) * than this method, and this method in turn generally performs better than copying the list and * calling {@link Collections.sort}. */ /** * Returns an immutable list containing `elements` sorted by this ordering. The input * is not modified. * * Unlike {@link Sets.newTreeSet}, this method does not discard elements that are * duplicates according to the comparator. The sort performed is stable, meaning that such * elements will appear in the returned list in the same order they appeared in `elements`. * * Performance note: According to our * benchmarking * on Open JDK 7, this method is the most efficient way to make a sorted copy of a collection. * * throws NullPointerException if any element of `elements` is `null` */ /** * Returns `true` if each element in `iterable` after the first is greater than or * equal to the element that preceded it, according to this ordering. Note that this is always * true when the iterable has fewer than two elements. * * Java 8 users: Use the equivalent {@link Comparators.isInOrder} * instead, since the rest of `Ordering` is mostly obsolete (as explained in the class * documentation). */ isOrdered(iterator: Iterator<T>): boolean; /** * Returns `true` if each element in `iterable` after the first is strictly * greater than the element that preceded it, according to this ordering. Note that this is always * true when the iterable has fewer than two elements. * * Java 8 users: Use the equivalent {@link Comparators.isInStrictOrder(Iterable, * Comparator)} instead, since the rest of `Ordering` is mostly obsolete (as explained in * the class documentation). */ isStrictlyOrdered(iterator: Iterator<T>): boolean; }