From e487af4d8251fa578a0aa64838cc2702b9c11f0c Mon Sep 17 00:00:00 2001 From: Lee Rhodes Date: Sun, 1 Nov 2026 12:44:13 -0800 Subject: [PATCH] Quantiles javadoc: name the exception each sketch throws when empty The quantiles API interfaces said every query on an empty sketch throws IllegalArgumentException. Only some implementations do: - KLL (doubles, floats, longs, items) throws SketchesArgumentException, which extends RuntimeException, not IllegalArgumentException. - QuantilesDoublesSketch, QuantilesItemsSketch and ReqSketch throw IllegalArgumentException. Each @throws tag in QuantilesDoublesAPI, QuantilesFloatsAPI and QuantilesGenericAPI now names both cases. QuantilesLongsAPI, which only KLL implements, names SketchesArgumentException. PartitioningFeature now documents the IllegalArgumentException its implementations throw for an empty sketch. GenericPartitionBoundaries getMinItem() and getMaxItem() lose a @throws tag: they return a stored field and never throw. No behavior changes. Checked by calling every documented method on an empty instance of each implementation, including the heapify, wrap and compact forms. Co-Authored-By: Claude Opus 5.5 --- .../GenericPartitionBoundaries.java | 2 - .../quantilescommon/PartitioningFeature.java | 4 ++ .../quantilescommon/QuantilesDoublesAPI.java | 50 +++++++++++++------ .../quantilescommon/QuantilesFloatsAPI.java | 50 +++++++++++++------ .../quantilescommon/QuantilesGenericAPI.java | 50 +++++++++++++------ .../quantilescommon/QuantilesLongsAPI.java | 34 +++++++------ 6 files changed, 124 insertions(+), 66 deletions(-) diff --git a/src/main/java/org/apache/datasketches/quantilescommon/GenericPartitionBoundaries.java b/src/main/java/org/apache/datasketches/quantilescommon/GenericPartitionBoundaries.java index 0eb44f3e7..f01d136a6 100644 --- a/src/main/java/org/apache/datasketches/quantilescommon/GenericPartitionBoundaries.java +++ b/src/main/java/org/apache/datasketches/quantilescommon/GenericPartitionBoundaries.java @@ -148,7 +148,6 @@ public GenericPartitionBoundaries( * sketch algorithm. * * @return the maximum item of the stream - * @throws IllegalArgumentException if sketch is empty. */ public T getMaxItem() { return maxItem; } @@ -157,7 +156,6 @@ public GenericPartitionBoundaries( * sketch algorithm. * * @return the minimum item of the stream - * @throws IllegalArgumentException if sketch is empty. */ public T getMinItem() { return minItem; } diff --git a/src/main/java/org/apache/datasketches/quantilescommon/PartitioningFeature.java b/src/main/java/org/apache/datasketches/quantilescommon/PartitioningFeature.java index 82b293b3a..75f6fb546 100644 --- a/src/main/java/org/apache/datasketches/quantilescommon/PartitioningFeature.java +++ b/src/main/java/org/apache/datasketches/quantilescommon/PartitioningFeature.java @@ -52,6 +52,7 @@ public interface PartitioningFeature { * * * @return an instance of {@link GenericPartitionBoundaries GenericPartitionBoundaries}. + * @throws IllegalArgumentException if sketch is empty. */ default GenericPartitionBoundaries getPartitionBoundariesFromNumParts(final int numEquallySizedParts) { return getPartitionBoundariesFromNumParts(numEquallySizedParts, INCLUSIVE); @@ -83,6 +84,7 @@ default GenericPartitionBoundaries getPartitionBoundariesFromNumParts(final i * with the exception of the highest returned quantile, which is the upper boundary of the highest ranked partition. * * @return an instance of {@link GenericPartitionBoundaries GenericPartitionBoundaries}. + * @throws IllegalArgumentException if sketch is empty. */ GenericPartitionBoundaries getPartitionBoundariesFromNumParts( int numEquallySizedParts, QuantileSearchCriteria searchCrit); @@ -105,6 +107,7 @@ GenericPartitionBoundaries getPartitionBoundariesFromNumParts( * {@link SketchPartitionLimits#getMinPartitionSizeItems() getMinPartitionSizeItems()} * * @return an instance of {@link GenericPartitionBoundaries GenericPartitionBoundaries}. + * @throws IllegalArgumentException if sketch is empty. */ default GenericPartitionBoundaries getPartitionBoundariesFromPartSize(final long nominalPartSizeItems) { return getPartitionBoundariesFromPartSize(nominalPartSizeItems, INCLUSIVE); @@ -129,6 +132,7 @@ default GenericPartitionBoundaries getPartitionBoundariesFromPartSize(final l * with the exception of the highest returned quantile, which is the upper boundary of the highest ranked partition. * * @return an instance of {@link GenericPartitionBoundaries GenericPartitionBoundaries}. + * @throws IllegalArgumentException if sketch is empty. */ GenericPartitionBoundaries getPartitionBoundariesFromPartSize( long nominalPartSizeItems, QuantileSearchCriteria searchCrit); diff --git a/src/main/java/org/apache/datasketches/quantilescommon/QuantilesDoublesAPI.java b/src/main/java/org/apache/datasketches/quantilescommon/QuantilesDoublesAPI.java index 63ec15284..3b48c2fbe 100644 --- a/src/main/java/org/apache/datasketches/quantilescommon/QuantilesDoublesAPI.java +++ b/src/main/java/org/apache/datasketches/quantilescommon/QuantilesDoublesAPI.java @@ -21,6 +21,8 @@ import static org.apache.datasketches.quantilescommon.QuantileSearchCriteria.INCLUSIVE; +import org.apache.datasketches.common.SketchesArgumentException; + /** * The Quantiles API for item type double. * @see QuantilesAPI @@ -33,7 +35,8 @@ public interface QuantilesDoublesAPI extends QuantilesAPI { * This is equivalent to {@link #getCDF(double[], QuantileSearchCriteria) getCDF(splitPoints, INCLUSIVE)} * @param splitPoints an array of m unique, monotonically increasing items. * @return a discrete CDF array of m+1 double ranks (or cumulative probabilities) on the interval [0.0, 1.0]. - * @throws IllegalArgumentException if sketch is empty. + * @throws SketchesArgumentException if sketch is empty and is a KllDoublesSketch. + * @throws IllegalArgumentException if sketch is empty and is a QuantilesDoublesSketch. */ default double[] getCDF(final double[] splitPoints) { return getCDF(splitPoints, INCLUSIVE); @@ -70,7 +73,8 @@ default double[] getCDF(final double[] splitPoints) { * * @param searchCrit the desired search criteria. * @return a discrete CDF array of m+1 double ranks (or cumulative probabilities) on the interval [0.0, 1.0]. - * @throws IllegalArgumentException if sketch is empty. + * @throws SketchesArgumentException if sketch is empty and is a KllDoublesSketch. + * @throws IllegalArgumentException if sketch is empty and is a QuantilesDoublesSketch. */ double[] getCDF(double[] splitPoints, QuantileSearchCriteria searchCrit); @@ -79,7 +83,8 @@ default double[] getCDF(final double[] splitPoints) { * item returned by getQuantile(1.0). * * @return the maximum item of the stream - * @throws IllegalArgumentException if sketch is empty. + * @throws SketchesArgumentException if sketch is empty and is a KllDoublesSketch. + * @throws IllegalArgumentException if sketch is empty and is a QuantilesDoublesSketch. */ double getMaxItem(); @@ -88,7 +93,8 @@ default double[] getCDF(final double[] splitPoints) { * item returned by getQuantile(0.0). * * @return the minimum item of the stream - * @throws IllegalArgumentException if sketch is empty. + * @throws SketchesArgumentException if sketch is empty and is a KllDoublesSketch. + * @throws IllegalArgumentException if sketch is empty and is a QuantilesDoublesSketch. */ double getMinItem(); @@ -96,7 +102,8 @@ default double[] getCDF(final double[] splitPoints) { * This is equivalent to {@link #getPMF(double[], QuantileSearchCriteria) getPMF(splitPoints, INCLUSIVE)} * @param splitPoints an array of m unique, monotonically increasing items. * @return a PMF array of m+1 probability masses as doubles on the interval [0.0, 1.0]. - * @throws IllegalArgumentException if sketch is empty. + * @throws SketchesArgumentException if sketch is empty and is a KllDoublesSketch. + * @throws IllegalArgumentException if sketch is empty and is a QuantilesDoublesSketch. */ default double[] getPMF(final double[] splitPoints) { return getPMF(splitPoints, INCLUSIVE); @@ -140,7 +147,8 @@ default double[] getPMF(final double[] splitPoints) { * * @param searchCrit the desired search criteria. * @return a PMF array of m+1 probability masses as doubles on the interval [0.0, 1.0]. - * @throws IllegalArgumentException if sketch is empty. + * @throws SketchesArgumentException if sketch is empty and is a KllDoublesSketch. + * @throws IllegalArgumentException if sketch is empty and is a QuantilesDoublesSketch. */ double[] getPMF(double[] splitPoints, QuantileSearchCriteria searchCrit); @@ -148,7 +156,8 @@ default double[] getPMF(final double[] splitPoints) { * This is equivalent to {@link #getQuantile(double, QuantileSearchCriteria) getQuantile(rank, INCLUSIVE)} * @param rank the given normalized rank, a double in the range [0.0, 1.0]. * @return the approximate quantile given the normalized rank. - * @throws IllegalArgumentException if sketch is empty. + * @throws SketchesArgumentException if sketch is empty and is a KllDoublesSketch. + * @throws IllegalArgumentException if sketch is empty and is a QuantilesDoublesSketch. */ default double getQuantile(final double rank) { return getQuantile(rank, INCLUSIVE); @@ -163,7 +172,8 @@ default double getQuantile(final double rank) { * If EXCLUSIVE, he given rank includes all quantiles < * the quantile directly corresponding to the given rank. * @return the approximate quantile given the normalized rank. - * @throws IllegalArgumentException if sketch is empty. + * @throws SketchesArgumentException if sketch is empty and is a KllDoublesSketch. + * @throws IllegalArgumentException if sketch is empty and is a QuantilesDoublesSketch. * @see org.apache.datasketches.quantilescommon.QuantileSearchCriteria */ double getQuantile(double rank, QuantileSearchCriteria searchCrit); @@ -180,7 +190,8 @@ default double getQuantile(final double rank) { * @param rank the given normalized rank * @return the lower bound of the quantile confidence interval in which the quantile of the * given rank exists. - * @throws IllegalArgumentException if sketch is empty. + * @throws SketchesArgumentException if sketch is empty and is a KllDoublesSketch. + * @throws IllegalArgumentException if sketch is empty and is a QuantilesDoublesSketch. */ double getQuantileLowerBound(double rank); @@ -196,7 +207,8 @@ default double getQuantile(final double rank) { * @param rank the given normalized rank * @return the upper bound of the quantile confidence interval in which the true quantile of the * given rank exists. - * @throws IllegalArgumentException if sketch is empty. + * @throws SketchesArgumentException if sketch is empty and is a KllDoublesSketch. + * @throws IllegalArgumentException if sketch is empty and is a QuantilesDoublesSketch. */ double getQuantileUpperBound(double rank); @@ -205,7 +217,8 @@ default double getQuantile(final double rank) { * @param ranks the given array of normalized ranks, each of which must be * in the interval [0.0,1.0]. * @return an array of quantiles corresponding to the given array of normalized ranks. - * @throws IllegalArgumentException if sketch is empty. + * @throws SketchesArgumentException if sketch is empty and is a KllDoublesSketch. + * @throws IllegalArgumentException if sketch is empty and is a QuantilesDoublesSketch. */ default double[] getQuantiles(final double[] ranks) { return getQuantiles(ranks, INCLUSIVE); @@ -219,7 +232,8 @@ default double[] getQuantiles(final double[] ranks) { * @param searchCrit if INCLUSIVE, the given ranks include all quantiles ≤ * the quantile directly corresponding to each rank. * @return an array of quantiles corresponding to the given array of normalized ranks. - * @throws IllegalArgumentException if sketch is empty. + * @throws SketchesArgumentException if sketch is empty and is a KllDoublesSketch. + * @throws IllegalArgumentException if sketch is empty and is a QuantilesDoublesSketch. * @see org.apache.datasketches.quantilescommon.QuantileSearchCriteria */ double[] getQuantiles(double[] ranks, QuantileSearchCriteria searchCrit); @@ -228,7 +242,8 @@ default double[] getQuantiles(final double[] ranks) { * This is equivalent to {@link #getRank(double, QuantileSearchCriteria) getRank(quantile, INCLUSIVE)} * @param quantile the given quantile * @return the normalized rank corresponding to the given quantile - * @throws IllegalArgumentException if sketch is empty. + * @throws SketchesArgumentException if sketch is empty and is a KllDoublesSketch. + * @throws IllegalArgumentException if sketch is empty and is a QuantilesDoublesSketch. */ default double getRank(final double quantile) { return getRank(quantile, INCLUSIVE); @@ -240,7 +255,8 @@ default double getRank(final double quantile) { * @param quantile the given quantile * @param searchCrit if INCLUSIVE the given quantile is included into the rank. * @return the normalized rank corresponding to the given quantile - * @throws IllegalArgumentException if sketch is empty. + * @throws SketchesArgumentException if sketch is empty and is a KllDoublesSketch. + * @throws IllegalArgumentException if sketch is empty and is a QuantilesDoublesSketch. * @see org.apache.datasketches.quantilescommon.QuantileSearchCriteria */ double getRank(double quantile, QuantileSearchCriteria searchCrit); @@ -249,7 +265,8 @@ default double getRank(final double quantile) { * This is equivalent to {@link #getRanks(double[], QuantileSearchCriteria) getRanks(quantiles, INCLUSIVE)} * @param quantiles the given array of quantiles * @return an array of normalized ranks corresponding to the given array of quantiles. - * @throws IllegalArgumentException if sketch is empty. + * @throws SketchesArgumentException if sketch is empty and is a KllDoublesSketch. + * @throws IllegalArgumentException if sketch is empty and is a QuantilesDoublesSketch. */ default double[] getRanks(final double[] quantiles) { return getRanks(quantiles, INCLUSIVE); @@ -262,7 +279,8 @@ default double[] getRanks(final double[] quantiles) { * @param quantiles the given array of quantiles * @param searchCrit if INCLUSIVE, the given quantiles include the rank directly corresponding to each quantile. * @return an array of normalized ranks corresponding to the given array of quantiles. - * @throws IllegalArgumentException if sketch is empty. + * @throws SketchesArgumentException if sketch is empty and is a KllDoublesSketch. + * @throws IllegalArgumentException if sketch is empty and is a QuantilesDoublesSketch. * @see org.apache.datasketches.quantilescommon.QuantileSearchCriteria */ double[] getRanks(double[] quantiles, QuantileSearchCriteria searchCrit); diff --git a/src/main/java/org/apache/datasketches/quantilescommon/QuantilesFloatsAPI.java b/src/main/java/org/apache/datasketches/quantilescommon/QuantilesFloatsAPI.java index 2713e1b02..3b8db77d2 100644 --- a/src/main/java/org/apache/datasketches/quantilescommon/QuantilesFloatsAPI.java +++ b/src/main/java/org/apache/datasketches/quantilescommon/QuantilesFloatsAPI.java @@ -21,6 +21,8 @@ import static org.apache.datasketches.quantilescommon.QuantileSearchCriteria.INCLUSIVE; +import org.apache.datasketches.common.SketchesArgumentException; + /** * The Quantiles API for item type float. * @see QuantilesAPI @@ -32,7 +34,8 @@ public interface QuantilesFloatsAPI extends QuantilesAPI { * This is equivalent to {@link #getCDF(float[], QuantileSearchCriteria) getCDF(splitPoints, INCLUSIVE)} * @param splitPoints an array of m unique, monotonically increasing items. * @return a discrete CDF array of m+1 double ranks (or cumulative probabilities) on the interval [0.0, 1.0]. - * @throws IllegalArgumentException if sketch is empty. + * @throws SketchesArgumentException if sketch is empty and is a KllFloatsSketch. + * @throws IllegalArgumentException if sketch is empty and is a ReqSketch. */ default double[] getCDF(final float[] splitPoints) { return getCDF(splitPoints, INCLUSIVE); @@ -69,7 +72,8 @@ default double[] getCDF(final float[] splitPoints) { * * @param searchCrit the desired search criteria. * @return a discrete CDF array of m+1 double ranks (or cumulative probabilities) on the interval [0.0, 1.0]. - * @throws IllegalArgumentException if sketch is empty. + * @throws SketchesArgumentException if sketch is empty and is a KllFloatsSketch. + * @throws IllegalArgumentException if sketch is empty and is a ReqSketch. */ double[] getCDF(float[] splitPoints, QuantileSearchCriteria searchCrit); @@ -78,7 +82,8 @@ default double[] getCDF(final float[] splitPoints) { * item retained by the sketch algorithm. * * @return the maximum item of the stream - * @throws IllegalArgumentException if sketch is empty. + * @throws SketchesArgumentException if sketch is empty and is a KllFloatsSketch. + * @throws IllegalArgumentException if sketch is empty and is a ReqSketch. */ float getMaxItem(); @@ -87,7 +92,8 @@ default double[] getCDF(final float[] splitPoints) { * item retained by the sketch algorithm. * * @return the minimum item of the stream - * @throws IllegalArgumentException if sketch is empty. + * @throws SketchesArgumentException if sketch is empty and is a KllFloatsSketch. + * @throws IllegalArgumentException if sketch is empty and is a ReqSketch. */ float getMinItem(); @@ -95,7 +101,8 @@ default double[] getCDF(final float[] splitPoints) { * This is equivalent to {@link #getPMF(float[], QuantileSearchCriteria) getPMF(splitPoints, INCLUSIVE)} * @param splitPoints an array of m unique, monotonically increasing items. * @return a PMF array of m+1 probability masses as doubles on the interval [0.0, 1.0]. - * @throws IllegalArgumentException if sketch is empty. + * @throws SketchesArgumentException if sketch is empty and is a KllFloatsSketch. + * @throws IllegalArgumentException if sketch is empty and is a ReqSketch. */ default double[] getPMF(final float[] splitPoints) { return getPMF(splitPoints, INCLUSIVE); @@ -139,7 +146,8 @@ default double[] getPMF(final float[] splitPoints) { * * @param searchCrit the desired search criteria. * @return a PMF array of m+1 probability masses as doubles on the interval [0.0, 1.0]. - * @throws IllegalArgumentException if sketch is empty. + * @throws SketchesArgumentException if sketch is empty and is a KllFloatsSketch. + * @throws IllegalArgumentException if sketch is empty and is a ReqSketch. */ double[] getPMF(float[] splitPoints, QuantileSearchCriteria searchCrit); @@ -147,7 +155,8 @@ default double[] getPMF(final float[] splitPoints) { * This is equivalent to {@link #getQuantile(double, QuantileSearchCriteria) getQuantile(rank, INCLUSIVE)} * @param rank the given normalized rank, a double in the range [0.0, 1.0]. * @return the approximate quantile given the normalized rank. - * @throws IllegalArgumentException if sketch is empty. + * @throws SketchesArgumentException if sketch is empty and is a KllFloatsSketch. + * @throws IllegalArgumentException if sketch is empty and is a ReqSketch. */ default float getQuantile(final double rank) { return getQuantile(rank, INCLUSIVE); @@ -162,7 +171,8 @@ default float getQuantile(final double rank) { * If EXCLUSIVE, he given rank includes all quantiles < * the quantile directly corresponding to the given rank. * @return the approximate quantile given the normalized rank. - * @throws IllegalArgumentException if sketch is empty. + * @throws SketchesArgumentException if sketch is empty and is a KllFloatsSketch. + * @throws IllegalArgumentException if sketch is empty and is a ReqSketch. * @see org.apache.datasketches.quantilescommon.QuantileSearchCriteria */ float getQuantile(double rank, QuantileSearchCriteria searchCrit); @@ -179,7 +189,8 @@ default float getQuantile(final double rank) { * @param rank the given normalized rank * @return the lower bound of the quantile confidence interval in which the quantile of the * given rank exists. - * @throws IllegalArgumentException if sketch is empty. + * @throws SketchesArgumentException if sketch is empty and is a KllFloatsSketch. + * @throws IllegalArgumentException if sketch is empty and is a ReqSketch. */ float getQuantileLowerBound(double rank); @@ -195,7 +206,8 @@ default float getQuantile(final double rank) { * @param rank the given normalized rank * @return the upper bound of the quantile confidence interval in which the true quantile of the * given rank exists. - * @throws IllegalArgumentException if sketch is empty. + * @throws SketchesArgumentException if sketch is empty and is a KllFloatsSketch. + * @throws IllegalArgumentException if sketch is empty and is a ReqSketch. */ float getQuantileUpperBound(double rank); @@ -204,7 +216,8 @@ default float getQuantile(final double rank) { * @param ranks the given array of normalized ranks, each of which must be * in the interval [0.0,1.0]. * @return an array of quantiles corresponding to the given array of normalized ranks. - * @throws IllegalArgumentException if sketch is empty. + * @throws SketchesArgumentException if sketch is empty and is a KllFloatsSketch. + * @throws IllegalArgumentException if sketch is empty and is a ReqSketch. */ default float[] getQuantiles(final double[] ranks) { return getQuantiles(ranks, INCLUSIVE); @@ -218,7 +231,8 @@ default float[] getQuantiles(final double[] ranks) { * @param searchCrit if INCLUSIVE, the given ranks include all quantiles ≤ * the quantile directly corresponding to each rank. * @return an array of quantiles corresponding to the given array of normalized ranks. - * @throws IllegalArgumentException if sketch is empty. + * @throws SketchesArgumentException if sketch is empty and is a KllFloatsSketch. + * @throws IllegalArgumentException if sketch is empty and is a ReqSketch. * @see org.apache.datasketches.quantilescommon.QuantileSearchCriteria */ float[] getQuantiles(double[] ranks, QuantileSearchCriteria searchCrit); @@ -227,7 +241,8 @@ default float[] getQuantiles(final double[] ranks) { * This is equivalent to {@link #getRank(float, QuantileSearchCriteria) getRank(quantile, INCLUSIVE)} * @param quantile the given quantile * @return the normalized rank corresponding to the given quantile. - * @throws IllegalArgumentException if sketch is empty. + * @throws SketchesArgumentException if sketch is empty and is a KllFloatsSketch. + * @throws IllegalArgumentException if sketch is empty and is a ReqSketch. */ default double getRank(final float quantile) { return getRank(quantile, INCLUSIVE); @@ -239,7 +254,8 @@ default double getRank(final float quantile) { * @param quantile the given quantile * @param searchCrit if INCLUSIVE the given quantile is included into the rank. * @return the normalized rank corresponding to the given quantile. - * @throws IllegalArgumentException if sketch is empty. + * @throws SketchesArgumentException if sketch is empty and is a KllFloatsSketch. + * @throws IllegalArgumentException if sketch is empty and is a ReqSketch. * @see org.apache.datasketches.quantilescommon.QuantileSearchCriteria */ double getRank(float quantile, QuantileSearchCriteria searchCrit); @@ -248,7 +264,8 @@ default double getRank(final float quantile) { * This is equivalent to {@link #getRanks(float[], QuantileSearchCriteria) getRanks(quantiles, INCLUSIVE)} * @param quantiles the given array of quantiles * @return an array of normalized ranks corresponding to the given array of quantiles. - * @throws IllegalArgumentException if sketch is empty. + * @throws SketchesArgumentException if sketch is empty and is a KllFloatsSketch. + * @throws IllegalArgumentException if sketch is empty and is a ReqSketch. */ default double[] getRanks(final float[] quantiles) { return getRanks(quantiles, INCLUSIVE); @@ -261,7 +278,8 @@ default double[] getRanks(final float[] quantiles) { * @param quantiles the given array of quantiles * @param searchCrit if INCLUSIVE, the given quantiles include the rank directly corresponding to each quantile. * @return an array of normalized ranks corresponding to the given array of quantiles. - * @throws IllegalArgumentException if sketch is empty. + * @throws SketchesArgumentException if sketch is empty and is a KllFloatsSketch. + * @throws IllegalArgumentException if sketch is empty and is a ReqSketch. * @see org.apache.datasketches.quantilescommon.QuantileSearchCriteria */ double[] getRanks(float[] quantiles, QuantileSearchCriteria searchCrit); diff --git a/src/main/java/org/apache/datasketches/quantilescommon/QuantilesGenericAPI.java b/src/main/java/org/apache/datasketches/quantilescommon/QuantilesGenericAPI.java index 6251a9596..3efd04b9a 100644 --- a/src/main/java/org/apache/datasketches/quantilescommon/QuantilesGenericAPI.java +++ b/src/main/java/org/apache/datasketches/quantilescommon/QuantilesGenericAPI.java @@ -24,6 +24,8 @@ import java.util.Comparator; +import org.apache.datasketches.common.SketchesArgumentException; + /** * The Quantiles API for item type generic. * @see QuantilesAPI @@ -36,7 +38,8 @@ public interface QuantilesGenericAPI extends QuantilesAPI, PartitioningFeatur * This is equivalent to {@link #getCDF(Object[], QuantileSearchCriteria) getCDF(splitPoints, INCLUSIVE)} * @param splitPoints an array of m unique, monotonically increasing items. * @return a discrete CDF array of m+1 double ranks (or cumulative probabilities) on the interval [0.0, 1.0]. - * @throws IllegalArgumentException if sketch is empty. + * @throws SketchesArgumentException if sketch is empty and is a KllItemsSketch. + * @throws IllegalArgumentException if sketch is empty and is a QuantilesItemsSketch. */ default double[] getCDF(final T[] splitPoints) { return getCDF(splitPoints, INCLUSIVE); @@ -73,7 +76,8 @@ default double[] getCDF(final T[] splitPoints) { * * @param searchCrit the desired search criteria. * @return a discrete CDF array of m+1 double ranks (or cumulative probabilities) on the interval [0.0, 1.0]. - * @throws IllegalArgumentException if sketch is empty. + * @throws SketchesArgumentException if sketch is empty and is a KllItemsSketch. + * @throws IllegalArgumentException if sketch is empty and is a QuantilesItemsSketch. */ double[] getCDF(T[] splitPoints, QuantileSearchCriteria searchCrit); @@ -94,7 +98,8 @@ default double[] getCDF(final T[] splitPoints) { * sketch algorithm. * * @return the maximum item of the stream - * @throws IllegalArgumentException if sketch is empty. + * @throws SketchesArgumentException if sketch is empty and is a KllItemsSketch. + * @throws IllegalArgumentException if sketch is empty and is a QuantilesItemsSketch. */ T getMaxItem(); @@ -108,7 +113,8 @@ default int getMaxPartitions() { * sketch algorithm. * * @return the minimum item of the stream - * @throws IllegalArgumentException if sketch is empty. + * @throws SketchesArgumentException if sketch is empty and is a KllItemsSketch. + * @throws IllegalArgumentException if sketch is empty and is a QuantilesItemsSketch. */ T getMinItem(); @@ -116,7 +122,8 @@ default int getMaxPartitions() { * This is equivalent to {@link #getPMF(Object[], QuantileSearchCriteria) getPMF(splitPoints, INCLUSIVE)} * @param splitPoints an array of m unique, monotonically increasing items. * @return a PMF array of m+1 probability masses as doubles on the interval [0.0, 1.0]. - * @throws IllegalArgumentException if sketch is empty. + * @throws SketchesArgumentException if sketch is empty and is a KllItemsSketch. + * @throws IllegalArgumentException if sketch is empty and is a QuantilesItemsSketch. */ default double[] getPMF(final T[] splitPoints) { return getPMF(splitPoints, INCLUSIVE); @@ -160,7 +167,8 @@ default double[] getPMF(final T[] splitPoints) { * * @param searchCrit the desired search criteria. * @return a PMF array of m+1 probability masses as doubles on the interval [0.0, 1.0]. - * @throws IllegalArgumentException if sketch is empty. + * @throws SketchesArgumentException if sketch is empty and is a KllItemsSketch. + * @throws IllegalArgumentException if sketch is empty and is a QuantilesItemsSketch. */ double[] getPMF(T[] splitPoints, QuantileSearchCriteria searchCrit); @@ -168,7 +176,8 @@ default double[] getPMF(final T[] splitPoints) { * This is equivalent to {@link #getQuantile(double, QuantileSearchCriteria) getQuantile(rank, INCLUSIVE)} * @param rank the given normalized rank, a double in the range [0.0, 1.0]. * @return the approximate quantile given the normalized rank. - * @throws IllegalArgumentException if sketch is empty. + * @throws SketchesArgumentException if sketch is empty and is a KllItemsSketch. + * @throws IllegalArgumentException if sketch is empty and is a QuantilesItemsSketch. */ default T getQuantile(final double rank) { return getQuantile(rank, INCLUSIVE); @@ -183,7 +192,8 @@ default T getQuantile(final double rank) { * If EXCLUSIVE, he given rank includes all quantiles < * the quantile directly corresponding to the given rank. * @return the approximate quantile given the normalized rank. - * @throws IllegalArgumentException if sketch is empty. + * @throws SketchesArgumentException if sketch is empty and is a KllItemsSketch. + * @throws IllegalArgumentException if sketch is empty and is a QuantilesItemsSketch. * @see org.apache.datasketches.quantilescommon.QuantileSearchCriteria */ T getQuantile(double rank, QuantileSearchCriteria searchCrit); @@ -200,7 +210,8 @@ default T getQuantile(final double rank) { * @param rank the given normalized rank * @return the lower bound of the quantile confidence interval in which the quantile of the * given rank exists. - * @throws IllegalArgumentException if sketch is empty. + * @throws SketchesArgumentException if sketch is empty and is a KllItemsSketch. + * @throws IllegalArgumentException if sketch is empty and is a QuantilesItemsSketch. */ T getQuantileLowerBound(double rank); @@ -216,7 +227,8 @@ default T getQuantile(final double rank) { * @param rank the given normalized rank * @return the upper bound of the quantile confidence interval in which the true quantile of the * given rank exists. - * @throws IllegalArgumentException if sketch is empty. + * @throws SketchesArgumentException if sketch is empty and is a KllItemsSketch. + * @throws IllegalArgumentException if sketch is empty and is a QuantilesItemsSketch. */ T getQuantileUpperBound(double rank); @@ -225,7 +237,8 @@ default T getQuantile(final double rank) { * @param ranks the given array of normalized ranks, each of which must be * in the interval [0.0,1.0]. * @return an array of quantiles corresponding to the given array of normalized ranks. - * @throws IllegalArgumentException if sketch is empty. + * @throws SketchesArgumentException if sketch is empty and is a KllItemsSketch. + * @throws IllegalArgumentException if sketch is empty and is a QuantilesItemsSketch. */ default T[] getQuantiles(final double[] ranks) { return getQuantiles(ranks, INCLUSIVE); @@ -239,7 +252,8 @@ default T[] getQuantiles(final double[] ranks) { * @param searchCrit if INCLUSIVE, the given ranks include all quantiles ≤ * the quantile directly corresponding to each rank. * @return an array of quantiles corresponding to the given array of normalized ranks. - * @throws IllegalArgumentException if sketch is empty. + * @throws SketchesArgumentException if sketch is empty and is a KllItemsSketch. + * @throws IllegalArgumentException if sketch is empty and is a QuantilesItemsSketch. * @see org.apache.datasketches.quantilescommon.QuantileSearchCriteria */ T[] getQuantiles(double[] ranks, QuantileSearchCriteria searchCrit); @@ -248,7 +262,8 @@ default T[] getQuantiles(final double[] ranks) { * This is equivalent to {@link #getRank(Object, QuantileSearchCriteria) getRank(T quantile, INCLUSIVE)} * @param quantile the given quantile * @return the normalized rank corresponding to the given quantile. - * @throws IllegalArgumentException if sketch is empty. + * @throws SketchesArgumentException if sketch is empty and is a KllItemsSketch. + * @throws IllegalArgumentException if sketch is empty and is a QuantilesItemsSketch. */ default double getRank(final T quantile) { return getRank(quantile, INCLUSIVE); @@ -260,7 +275,8 @@ default double getRank(final T quantile) { * @param quantile the given quantile * @param searchCrit if INCLUSIVE the given quantile is included into the rank. * @return the normalized rank corresponding to the given quantile. - * @throws IllegalArgumentException if sketch is empty. + * @throws SketchesArgumentException if sketch is empty and is a KllItemsSketch. + * @throws IllegalArgumentException if sketch is empty and is a QuantilesItemsSketch. * @see org.apache.datasketches.quantilescommon.QuantileSearchCriteria */ double getRank(T quantile, QuantileSearchCriteria searchCrit); @@ -269,7 +285,8 @@ default double getRank(final T quantile) { * This is equivalent to {@link #getRanks(Object[], QuantileSearchCriteria) getRanks(quantiles, INCLUSIVE)} * @param quantiles the given array of quantiles * @return an array of normalized ranks corresponding to the given array of quantiles. - * @throws IllegalArgumentException if sketch is empty. + * @throws SketchesArgumentException if sketch is empty and is a KllItemsSketch. + * @throws IllegalArgumentException if sketch is empty and is a QuantilesItemsSketch. */ default double[] getRanks(final T[] quantiles) { return getRanks(quantiles, INCLUSIVE); @@ -282,7 +299,8 @@ default double[] getRanks(final T[] quantiles) { * @param quantiles the given array of quantiles * @param searchCrit if INCLUSIVE, the given quantiles include the rank directly corresponding to each quantile. * @return an array of normalized ranks corresponding to the given array of quantiles. - * @throws IllegalArgumentException if sketch is empty. + * @throws SketchesArgumentException if sketch is empty and is a KllItemsSketch. + * @throws IllegalArgumentException if sketch is empty and is a QuantilesItemsSketch. * @see org.apache.datasketches.quantilescommon.QuantileSearchCriteria */ double[] getRanks(T[] quantiles, QuantileSearchCriteria searchCrit); diff --git a/src/main/java/org/apache/datasketches/quantilescommon/QuantilesLongsAPI.java b/src/main/java/org/apache/datasketches/quantilescommon/QuantilesLongsAPI.java index 51802df71..8edc4bc55 100644 --- a/src/main/java/org/apache/datasketches/quantilescommon/QuantilesLongsAPI.java +++ b/src/main/java/org/apache/datasketches/quantilescommon/QuantilesLongsAPI.java @@ -21,6 +21,8 @@ import static org.apache.datasketches.quantilescommon.QuantileSearchCriteria.INCLUSIVE; +import org.apache.datasketches.common.SketchesArgumentException; + /** * The Quantiles API for item type long. * @see QuantilesAPI @@ -33,7 +35,7 @@ public interface QuantilesLongsAPI extends QuantilesAPI { * This is equivalent to {@link #getCDF(long[], QuantileSearchCriteria) getCDF(splitPoints, INCLUSIVE)} * @param splitPoints an array of m unique, monotonically increasing items. * @return a discrete CDF array of m+1 double ranks (or cumulative probabilities) on the interval [0.0, 1.0]. - * @throws IllegalArgumentException if sketch is empty. + * @throws SketchesArgumentException if sketch is empty. */ default double[] getCDF(final long[] splitPoints) { return getCDF(splitPoints, INCLUSIVE); @@ -70,7 +72,7 @@ default double[] getCDF(final long[] splitPoints) { * * @param searchCrit the desired search criteria. * @return a discrete CDF array of m+1 double ranks (or cumulative probabilities) on the interval [0.0, 1.0]. - * @throws IllegalArgumentException if sketch is empty. + * @throws SketchesArgumentException if sketch is empty. */ double[] getCDF(long[] splitPoints, QuantileSearchCriteria searchCrit); @@ -79,7 +81,7 @@ default double[] getCDF(final long[] splitPoints) { * item returned by getQuantile(1.0). * * @return the maximum item of the stream - * @throws IllegalArgumentException if sketch is empty. + * @throws SketchesArgumentException if sketch is empty. */ long getMaxItem(); @@ -88,7 +90,7 @@ default double[] getCDF(final long[] splitPoints) { * item returned by getQuantile(0.0). * * @return the minimum item of the stream - * @throws IllegalArgumentException if sketch is empty. + * @throws SketchesArgumentException if sketch is empty. */ long getMinItem(); @@ -96,7 +98,7 @@ default double[] getCDF(final long[] splitPoints) { * This is equivalent to {@link #getPMF(long[], QuantileSearchCriteria) getPMF(splitPoints, INCLUSIVE)} * @param splitPoints an array of m unique, monotonically increasing items. * @return a PMF array of m+1 probability masses as doubles on the interval [0.0, 1.0]. - * @throws IllegalArgumentException if sketch is empty. + * @throws SketchesArgumentException if sketch is empty. */ default double[] getPMF(final long[] splitPoints) { return getPMF(splitPoints, INCLUSIVE); @@ -140,7 +142,7 @@ default double[] getPMF(final long[] splitPoints) { * * @param searchCrit the desired search criteria. * @return a PMF array of m+1 probability masses as doubles on the interval [0.0, 1.0]. - * @throws IllegalArgumentException if sketch is empty. + * @throws SketchesArgumentException if sketch is empty. */ double[] getPMF(long[] splitPoints, QuantileSearchCriteria searchCrit); @@ -148,7 +150,7 @@ default double[] getPMF(final long[] splitPoints) { * This is equivalent to {@link #getQuantile(double, QuantileSearchCriteria) getQuantile(rank, INCLUSIVE)} * @param rank the given normalized rank, a double in the range [0.0, 1.0]. * @return the approximate quantile given the normalized rank. - * @throws IllegalArgumentException if sketch is empty. + * @throws SketchesArgumentException if sketch is empty. */ default long getQuantile(final double rank) { return getQuantile(rank, INCLUSIVE); @@ -163,7 +165,7 @@ default long getQuantile(final double rank) { * If EXCLUSIVE, he given rank includes all quantiles < * the quantile directly corresponding to the given rank. * @return the approximate quantile given the normalized rank. - * @throws IllegalArgumentException if sketch is empty. + * @throws SketchesArgumentException if sketch is empty. * @see org.apache.datasketches.quantilescommon.QuantileSearchCriteria */ long getQuantile(double rank, QuantileSearchCriteria searchCrit); @@ -180,7 +182,7 @@ default long getQuantile(final double rank) { * @param rank the given normalized rank * @return the lower bound of the quantile confidence interval in which the quantile of the * given rank exists. - * @throws IllegalArgumentException if sketch is empty. + * @throws SketchesArgumentException if sketch is empty. */ long getQuantileLowerBound(double rank); @@ -196,7 +198,7 @@ default long getQuantile(final double rank) { * @param rank the given normalized rank * @return the upper bound of the quantile confidence interval in which the true quantile of the * given rank exists. - * @throws IllegalArgumentException if sketch is empty. + * @throws SketchesArgumentException if sketch is empty. */ long getQuantileUpperBound(double rank); @@ -205,7 +207,7 @@ default long getQuantile(final double rank) { * @param ranks the given array of normalized ranks, each of which must be * in the interval [0.0,1.0]. * @return an array of quantiles corresponding to the given array of normalized ranks. - * @throws IllegalArgumentException if sketch is empty. + * @throws SketchesArgumentException if sketch is empty. */ default long[] getQuantiles(final double[] ranks) { return getQuantiles(ranks, INCLUSIVE); @@ -219,7 +221,7 @@ default long[] getQuantiles(final double[] ranks) { * @param searchCrit if INCLUSIVE, the given ranks include all quantiles ≤ * the quantile directly corresponding to each rank. * @return an array of quantiles corresponding to the given array of normalized ranks. - * @throws IllegalArgumentException if sketch is empty. + * @throws SketchesArgumentException if sketch is empty. * @see org.apache.datasketches.quantilescommon.QuantileSearchCriteria */ long[] getQuantiles(double[] ranks, QuantileSearchCriteria searchCrit); @@ -228,7 +230,7 @@ default long[] getQuantiles(final double[] ranks) { * This is equivalent to {@link #getRank(long, QuantileSearchCriteria) getRank(quantile, INCLUSIVE)} * @param quantile the given quantile * @return the normalized rank corresponding to the given quantile - * @throws IllegalArgumentException if sketch is empty. + * @throws SketchesArgumentException if sketch is empty. */ default double getRank(final long quantile) { return getRank(quantile, INCLUSIVE); @@ -240,7 +242,7 @@ default double getRank(final long quantile) { * @param quantile the given quantile * @param searchCrit if INCLUSIVE the given quantile is included into the rank. * @return the normalized rank corresponding to the given quantile - * @throws IllegalArgumentException if sketch is empty. + * @throws SketchesArgumentException if sketch is empty. * @see org.apache.datasketches.quantilescommon.QuantileSearchCriteria */ double getRank(long quantile, QuantileSearchCriteria searchCrit); @@ -249,7 +251,7 @@ default double getRank(final long quantile) { * This is equivalent to {@link #getRanks(long[], QuantileSearchCriteria) getRanks(quantiles, INCLUSIVE)} * @param quantiles the given array of quantiles * @return an array of normalized ranks corresponding to the given array of quantiles. - * @throws IllegalArgumentException if sketch is empty. + * @throws SketchesArgumentException if sketch is empty. */ default double[] getRanks(final long[] quantiles) { return getRanks(quantiles, INCLUSIVE); @@ -262,7 +264,7 @@ default double[] getRanks(final long[] quantiles) { * @param quantiles the given array of quantiles * @param searchCrit if INCLUSIVE, the given quantiles include the rank directly corresponding to each quantile. * @return an array of normalized ranks corresponding to the given array of quantiles. - * @throws IllegalArgumentException if sketch is empty. + * @throws SketchesArgumentException if sketch is empty. * @see org.apache.datasketches.quantilescommon.QuantileSearchCriteria */ double[] getRanks(long[] quantiles, QuantileSearchCriteria searchCrit);