Package com.google.mu.collect

Class InsertionPoint<C extends Comparable<C>>

java.lang.Object
com.google.mu.collect.InsertionPoint<C>
Type Parameters:
C - the domain type
All Implemented Interfaces:
Comparable<InsertionPoint<C>>
@RequiresGuava @Immutable(containerOf="C") @CheckReturnValue public final class InsertionPoint<C extends Comparable<C>> extends Object implements Comparable<InsertionPoint<C>>
Represents a result of BinarySearch. An insertion point in a sequence of elements (normally of indexes) is either an exact element, or in between two adjacent elements in a discrete domain, or before or after all elements of the discrete domain.

If representing an exact point, exact(), floor() and ceiling() all return the element.

If it's between two elements, exact() will return empty, and floor() and ceiling() will return the two adjacent elements respectively.

If it's below all possible elements, isBelowAll() will return true and floor() will throw. The ceiling() method will return the min element of the domain (if present).

If it's above all possible elements, isAboveAll() will return true and ceiling() will throw. The floor() method will return the max element of the domain (if present).

Over a discrete domain with N discrete elements, there are 2 * N + 1 distinct insertion points, including all the elements, the points between each two adjacent elements, the point before all elements and the point after all elements.

Since:
8.0

  • Method Summary

    Modifier and Type
    Method
    Description
    static InsertionPoint<Double>
    after(double floor)
    Returns an insertion point immediately after floor.
    static InsertionPoint<Integer>
    after(int floor)
    Returns an insertion point immediately after the given floor and before the next integer (if ceiling isn't Integer.MAX_VALUE).
    static InsertionPoint<Long>
    after(long floor)
    Returns an insertion point immediately after the given floor and before the next integer (if ceiling isn't Long.MAX_VALUE).
    static <C extends Comparable<C>>
    InsertionPoint<C>
    after(C floor, com.google.common.collect.DiscreteDomain<C> domain)
    Returns an insertion point immediately after the given floor and before the next element in the given discrete domain (if a next element exists).
    static <C extends Comparable<C>>
    InsertionPoint<C>
    at(C element)
    Returns an insertion point exactly at element such that exact(), floor and ceiling all return the same element.
    static InsertionPoint<Double>
    before(double ceiling)
    Returns an insertion point immediately before ceiling.
    static InsertionPoint<Integer>
    before(int ceiling)
    Returns an insertion point immediately before the given ceiling and after the previous integer (if ceiling isn't Integer.MIN_VALUE).
    static InsertionPoint<Long>
    before(long ceiling)
    Returns an insertion point immediately before the given ceiling and after the previous integer (if ceiling isn't Long.MIN_VALUE).
    static <C extends Comparable<C>>
    InsertionPoint<C>
    before(C ceiling, com.google.common.collect.DiscreteDomain<C> domain)
    Returns an insertion point immediately before the given ceiling and after the previous element in the given discrete domain (if a previous element exists).
    static InsertionPoint<Double>
    between(double floor, double ceiling)
    Returns an insertion point in the open range of (floor, ceiling).
    C
    ceiling()
    Returns the ceiling element such that this insertion point is immediately <= the ceiling.
    int
    compareTo(InsertionPoint<C> that)
     
    boolean
    equals(Object obj)
     
    Optional<C>
    exact()
    If this represents an exact point (not between two adjacent values), returns the element at the point; else returns empty.
    C
    floor()
    Returns the floor element such that this insertion point is immediately >= the floor.
    int
    hashCode()
     
    boolean
    isAboveAll()
    Returns true if this is a point above the max possible element in the domain.
    boolean
    isBelowAll()
    Returns true if this is a point below the min possible element in the domain.
    String
    toString()
    Returns a human-readable string representation of this insertion point.

    Methods inherited from class java.lang.Object

    clone, finalize, getClass, notify, notifyAll, wait, wait, wait

  • Method Details

    • at

      public static <C extends Comparable<C>> InsertionPoint<C> at(C element)
      Returns an insertion point exactly at element such that exact(), floor and ceiling all return the same element.

    • before

      public static InsertionPoint<Integer> before(int ceiling)
      Returns an insertion point immediately before the given ceiling and after the previous integer (if ceiling isn't Integer.MIN_VALUE).

    • before

      public static InsertionPoint<Long> before(long ceiling)
      Returns an insertion point immediately before the given ceiling and after the previous integer (if ceiling isn't Long.MIN_VALUE).

    • before

      public static InsertionPoint<Double> before(double ceiling)
      Returns an insertion point immediately before ceiling.

    • before

      public static <C extends Comparable<C>> InsertionPoint<C> before(C ceiling, com.google.common.collect.DiscreteDomain<C> domain)
      Returns an insertion point immediately before the given ceiling and after the previous element in the given discrete domain (if a previous element exists).

    • after

      public static InsertionPoint<Integer> after(int floor)
      Returns an insertion point immediately after the given floor and before the next integer (if ceiling isn't Integer.MAX_VALUE).

    • after

      public static InsertionPoint<Long> after(long floor)
      Returns an insertion point immediately after the given floor and before the next integer (if ceiling isn't Long.MAX_VALUE).

    • after

      public static InsertionPoint<Double> after(double floor)
      Returns an insertion point immediately after floor.

    • after

      public static <C extends Comparable<C>> InsertionPoint<C> after(C floor, com.google.common.collect.DiscreteDomain<C> domain)
      Returns an insertion point immediately after the given floor and before the next element in the given discrete domain (if a next element exists).

    • between

      public static InsertionPoint<Double> between(double floor, double ceiling)
      Returns an insertion point in the open range of (floor, ceiling).

    • exact

      public Optional<C> exact()
      If this represents an exact point (not between two adjacent values), returns the element at the point; else returns empty.

    • floor

      public C floor()
      Returns the floor element such that this insertion point is immediately >= the floor.
      Throws:
      NoSuchElementException - if this represents a point below all possible values in the discrete domain. Users can use isBelowAll() to guard this condition.

    • ceiling

      public C ceiling()
      Returns the ceiling element such that this insertion point is immediately <= the ceiling.
      Throws:
      NoSuchElementException - if this represents a point above all possible values in the discrete domain. Users can use isAboveAll() to guard this condition.

    • isAboveAll

      public boolean isAboveAll()
      Returns true if this is a point above the max possible element in the domain.

    • isBelowAll

      public boolean isBelowAll()
      Returns true if this is a point below the min possible element in the domain.

    • compareTo

      public int compareTo(InsertionPoint<C> that)
      Specified by:
      compareTo in interface Comparable<C extends Comparable<C>>

    • hashCode

      public int hashCode()
      Overrides:
      hashCode in class Object

    • equals

      public boolean equals(Object obj)
      Overrides:
      equals in class Object

    • toString

      public String toString()
      Returns a human-readable string representation of this insertion point.
      Overrides:
      toString in class Object