Package org.apache.datasketches.quantiles

Class DoublesUnion

java.lang.Object
org.apache.datasketches.quantiles.DoublesUnion
public abstract class DoublesUnion extends Object
The API for Union operations for quantiles DoublesSketches
Author:
Lee Rhodes

  • Constructor Summary

    Constructors
    Constructor
    Description
    DoublesUnion()
     

  • Method Summary

    Modifier and Type
    Method
    Description
    static DoublesUnionBuilder
    builder()
    Returns a new UnionBuilder
    abstract int
    getEffectiveK()
    Returns the effective k of this Union.
    abstract int
    getMaxK()
    Returns the configured maxK of this Union.
    abstract UpdateDoublesSketch
    getResult()
    Gets the result of this Union as an UpdateDoublesSketch, which enables further update operations on the resulting sketch.
    abstract UpdateDoublesSketch
    getResult(org.apache.datasketches.memory.WritableMemory dstMem)
    Places the result of this Union into the provided memory as an UpdateDoublesSketch, which enables further update operations on the resulting sketch.
    abstract UpdateDoublesSketch
    getResultAndReset()
    Gets the result of this Union as an UpdateDoublesSketch, which enables further update operations on the resulting sketch.
    abstract boolean
    hasMemory()
    Returns true if this union's data structure is backed by Memory or WritableMemory.
    static DoublesUnion
    heapify(org.apache.datasketches.memory.Memory srcMem)
    Returns a Heap Union object that has been initialized with the data from the given memory image of a sketch.
    static DoublesUnion
    heapify(DoublesSketch sketch)
    Returns a Heap Union object that has been initialized with the data from the given sketch.
    abstract boolean
    isDirect()
    Returns true if this union is off-heap (direct)
    abstract boolean
    isEmpty()
    Returns true if this union is empty
    abstract boolean
    isSameResource(org.apache.datasketches.memory.Memory that)
    Returns true if the backing resource of this is identical with the backing resource of that.
    abstract void
    reset()
    Resets this Union to a virgin state.
    abstract byte[]
    toByteArray()
    Serialize this union to a byte array.
    abstract String
    toString()
    Returns summary information about the backing sketch.
    abstract String
    toString(boolean sketchSummary, boolean dataDetail)
    Returns summary information about the backing sketch.
    abstract void
    union(org.apache.datasketches.memory.Memory mem)
    Iterative union operation, which means this method can be repeatedly called.
    abstract void
    union(DoublesSketch sketchIn)
    Iterative union operation, which means this method can be repeatedly called.
    abstract void
    update(double dataItem)
    Update this union with the given double (or float) data Item.
    static DoublesUnion
    wrap(org.apache.datasketches.memory.Memory mem)
    Returns a read-only Union object that wraps off-heap data of the given memory image of a sketch.
    static DoublesUnion
    wrap(org.apache.datasketches.memory.WritableMemory mem)
    Returns an updatable Union object that wraps off-heap data of the given memory image of a sketch.

    Methods inherited from class java.lang.Object

    equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

  • Constructor Details

    • DoublesUnion

      public DoublesUnion()

  • Method Details

    • builder

      public static DoublesUnionBuilder builder()
      Returns a new UnionBuilder
      Returns:
      a new UnionBuilder

    • heapify

      public static DoublesUnion heapify(DoublesSketch sketch)
      Returns a Heap Union object that has been initialized with the data from the given sketch.
      Parameters:
      sketch - A DoublesSketch to be used as a source of data only and will not be modified.
      Returns:
      a DoublesUnion object

    • heapify

      public static DoublesUnion heapify(org.apache.datasketches.memory.Memory srcMem)
      Returns a Heap Union object that has been initialized with the data from the given memory image of a sketch.
      Parameters:
      srcMem - A memory image of a DoublesSketch to be used as a source of data, but will not be modified.
      Returns:
      a Union object

    • wrap

      public static DoublesUnion wrap(org.apache.datasketches.memory.Memory mem)
      Returns a read-only Union object that wraps off-heap data of the given memory image of a sketch. The data structures of the Union remain off-heap.
      Parameters:
      mem - A memory region to be used as the data structure for the sketch and will be modified.
      Returns:
      a Union object

    • wrap

      public static DoublesUnion wrap(org.apache.datasketches.memory.WritableMemory mem)
      Returns an updatable Union object that wraps off-heap data of the given memory image of a sketch. The data structures of the Union remain off-heap.
      Parameters:
      mem - A memory region to be used as the data structure for the sketch and will be modified.
      Returns:
      a Union object

    • hasMemory

      public abstract boolean hasMemory()
      Returns true if this union's data structure is backed by Memory or WritableMemory.
      Returns:
      true if this union's data structure is backed by Memory or WritableMemory.

    • isDirect

      public abstract boolean isDirect()
      Returns true if this union is off-heap (direct)
      Returns:
      true if this union is off-heap (direct)

    • isEmpty

      public abstract boolean isEmpty()
      Returns true if this union is empty
      Returns:
      true if this union is empty

    • getMaxK

      public abstract int getMaxK()
      Returns the configured maxK of this Union.
      Returns:
      the configured maxK of this Union.

    • getEffectiveK

      public abstract int getEffectiveK()
      Returns the effective k of this Union.
      Returns:
      the effective k of this Union.

    • union

      public abstract void union(DoublesSketch sketchIn)
      Iterative union operation, which means this method can be repeatedly called. Merges the given sketch into this union object. The given sketch is not modified. It is required that the ratio of the two K's be a power of 2. This is easily satisfied if each of the K's are already a power of 2. If the given sketch is null or empty it is ignored.

      It is required that the results of the union operation, which can be obtained at any time, is obtained from getResult().

      Parameters:
      sketchIn - the sketch to be merged into this one.

    • union

      public abstract void union(org.apache.datasketches.memory.Memory mem)
      Iterative union operation, which means this method can be repeatedly called. Merges the given Memory image of a DoublesSketch into this union object. The given Memory object is not modified and a link to it is not retained. It is required that the ratio of the two K's be a power of 2. This is easily satisfied if each of the K's are already a power of 2. If the given sketch is null or empty it is ignored.

      It is required that the results of the union operation, which can be obtained at any time, is obtained from getResult().

      Parameters:
      mem - Memory image of sketch to be merged

    • update

      public abstract void update(double dataItem)
      Update this union with the given double (or float) data Item.
      Parameters:
      dataItem - The given double datum.

    • getResult

      public abstract UpdateDoublesSketch getResult()
      Gets the result of this Union as an UpdateDoublesSketch, which enables further update operations on the resulting sketch. The Union state has not been changed, which allows further union operations.
      Returns:
      the result of this Union operation

    • getResult

      public abstract UpdateDoublesSketch getResult(org.apache.datasketches.memory.WritableMemory dstMem)
      Places the result of this Union into the provided memory as an UpdateDoublesSketch, which enables further update operations on the resulting sketch. The Union state has not been changed, which allows further union operations.
      Parameters:
      dstMem - the destination memory for the result
      Returns:
      the result of this Union operation

    • getResultAndReset

      public abstract UpdateDoublesSketch getResultAndReset()
      Gets the result of this Union as an UpdateDoublesSketch, which enables further update operations on the resulting sketch. The Union is reset to the virgin state.
      Returns:
      the result of this Union operation and reset.

    • reset

      public abstract void reset()
      Resets this Union to a virgin state.

    • toByteArray

      public abstract byte[] toByteArray()
      Serialize this union to a byte array. Result is an UpdateDoublesSketch, serialized in an unordered, non-compact form. The resulting byte[] can be heapified or wrapped as either a sketch or a union.
      Returns:
      byte array of this union

    • toString

      public abstract String toString()
      Returns summary information about the backing sketch.
      Overrides:
      toString in class Object

    • toString

      public abstract String toString(boolean sketchSummary, boolean dataDetail)
      Returns summary information about the backing sketch. Used for debugging.
      Parameters:
      sketchSummary - if true includes sketch summary
      dataDetail - if true includes data detail
      Returns:
      summary information about the sketch.

    • isSameResource

      public abstract boolean isSameResource(org.apache.datasketches.memory.Memory that)
      Returns true if the backing resource of this is identical with the backing resource of that. The capacities must be the same. If this is a region, the region offset must also be the same.
      Parameters:
      that - A different non-null object
      Returns:
      true if the backing resource of this is the same as the backing resource of that.