Class QuantilesDoublesUnion

java.lang.Object
org.apache.datasketches.quantiles.QuantilesDoublesUnion
All Implemented Interfaces:
MemorySegmentStatus
public abstract class QuantilesDoublesUnion extends Object implements MemorySegmentStatus
The API for Union operations for QuantilesDoublesSketches
Author:
Lee Rhodes

  • Constructor Details

    • QuantilesDoublesUnion

      public QuantilesDoublesUnion()
      No argument constructor.

  • Method Details

    • builder

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

    • heapify

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

    • heapify

      public static QuantilesDoublesUnion heapify(MemorySegment srcSeg)
      Returns a Heap Union object that has been initialized with the data from the given MemorySegment that contains an image of a sketch.
      Parameters:
      srcSeg - A MemorySegment image of a QuantilesDoublesSketch to be used as a source of data and will not be modified.
      Returns:
      a Union object

    • wrap

      public static QuantilesDoublesUnion wrap(MemorySegment srcSeg)
      Returns an updatable Union object that wraps the given MemorySegment that contains an image of a QuantilesDoublesSketch.
      Parameters:
      srcSeg - A MemorySegment image of an updatable QuantilesDoublesSketch to be used as the data structure for the union and will be modified.
      Returns:
      a Union object

    • wrap

      public static QuantilesDoublesUnion wrap(MemorySegment srcSeg, MemorySegmentRequest mSegReq)
      Returns an updatable Union object that wraps the given MemorySegment that contains an image of a QuantilesDoublesSketch.
      Parameters:
      srcSeg - A MemorySegment sketch to be used as the data structure for the union and will be modified.
      mSegReq - the MemorySegmentRequest used if the given MemorySegment needs to expand. Otherwise, it can be null and the default MemorySegmentRequest will be used.
      Returns:
      a Union object

    • hasMemorySegment

      public abstract boolean hasMemorySegment()
      Description copied from interface: MemorySegmentStatus
      Returns true if this object's internal data is backed by a MemorySegment, which may be on-heap or off-heap.
      Specified by:
      hasMemorySegment in interface MemorySegmentStatus
      Returns:
      true if this object's internal data is backed by a MemorySegment.

    • isOffHeap

      public abstract boolean isOffHeap()
      Description copied from interface: MemorySegmentStatus
      Returns true if this object's internal data is backed by an off-heap (direct or native)) MemorySegment.
      Specified by:
      isOffHeap in interface MemorySegmentStatus
      Returns:
      true if this object's internal data is backed by an off-heap (direct or native)) MemorySegment.

    • isSameResource

      public abstract boolean isSameResource(MemorySegment that)
      Description copied from interface: MemorySegmentStatus
      Returns true if an internally referenced MemorySegment has the same backing resource as that, or equivalently, if their two memory regions overlap. This applies to both on-heap and off-heap MemorySegments.

      Note: If both segments are on-heap and not read-only, it can be determined if they were derived from the same backing memory (array). However, this is not always possible off-heap. Because of this asymmetry, this definition of "isSameResource" is confined to the existence of an overlap.

      Specified by:
      isSameResource in interface MemorySegmentStatus
      Parameters:
      that - The given MemorySegment.
      Returns:
      true if an internally referenced MemorySegment has the same backing resource as that.

    • 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(QuantilesDoublesSketch 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(MemorySegment seg)
      Iterative union operation, which means this method can be repeatedly called. Merges the given MemorySegment image of a QuantilesDoublesSketch into this union object. The given MemorySegment 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:
      seg - MemorySegment 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 UpdatableQuantilesDoublesSketch getResult()
      Gets the result of this Union as an UpdatableQuantilesDoublesSketch, 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 UpdatableQuantilesDoublesSketch getResult(MemorySegment dstSeg, MemorySegmentRequest mSegReq)
      Places the result of this Union into the provided MemorySegment as an UpdatableQuantilesDoublesSketch, which enables further update operations on the resulting sketch. The Union state has not been changed, which allows further union operations.
      Parameters:
      dstSeg - the destination MemorySegment for the result
      mSegReq - the MemorySegmentRequest used if the given MemorySegment needs to expand. Otherwise, it can be null and the default MemorySegmentRequest will be used.
      Returns:
      the result of this Union operation

    • getResultAndReset

      public abstract UpdatableQuantilesDoublesSketch getResultAndReset()
      Gets the result of this Union as an UpdatableQuantilesDoublesSketch, 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 UpdatableQuantilesDoublesSketch, 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.