Quantiles javadoc: name the exception each sketch throws when empty

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; }
 

src/main/java/org/apache/datasketches/quantilescommon/PartitioningFeature.java

@@ -52,6 +52,7 @@ public interface PartitioningFeature<T> {
    * </ul>
    *
    * @return an instance of {@link GenericPartitionBoundaries GenericPartitionBoundaries}.
+   * @throws IllegalArgumentException if sketch is empty.
    */
   default GenericPartitionBoundaries<T> getPartitionBoundariesFromNumParts(final int numEquallySizedParts) {
     return getPartitionBoundariesFromNumParts(numEquallySizedParts, INCLUSIVE);
@@ -83,6 +84,7 @@ default GenericPartitionBoundaries<T> 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<T> getPartitionBoundariesFromNumParts(
       int numEquallySizedParts, QuantileSearchCriteria searchCrit);
@@ -105,6 +107,7 @@ GenericPartitionBoundaries<T> getPartitionBoundariesFromNumParts(
    * {@link SketchPartitionLimits#getMinPartitionSizeItems() getMinPartitionSizeItems()}
    *
    * @return an instance of {@link GenericPartitionBoundaries GenericPartitionBoundaries}.
+   * @throws IllegalArgumentException if sketch is empty.
    */
   default GenericPartitionBoundaries<T> getPartitionBoundariesFromPartSize(final long nominalPartSizeItems) {
     return getPartitionBoundariesFromPartSize(nominalPartSizeItems, INCLUSIVE);
@@ -129,6 +132,7 @@ default GenericPartitionBoundaries<T> 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<T> getPartitionBoundariesFromPartSize(
       long nominalPartSizeItems, QuantileSearchCriteria searchCrit);

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 <i>double</i>.
  * @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 <i>m</i> 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) {
    * </blockquote>
    * @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 <i>getQuantile(1.0)</i>.
    *
    * @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,15 +93,17 @@ default double[] getCDF(final double[] splitPoints) {
    * item returned by <i>getQuantile(0.0)</i>.
    *
    * @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();
 
   /**
    * This is equivalent to {@link #getPMF(double[], QuantileSearchCriteria) getPMF(splitPoints, INCLUSIVE)}
    * @param splitPoints an array of <i>m</i> 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,15 +147,17 @@ default double[] getPMF(final double[] splitPoints) {
    * </blockquote>
    * @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);
 
   /**
    * 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 &lt;
    * 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 &le;
    * 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);