leerho commented on a change in pull request #324:
URL:
https://github.com/apache/incubator-datasketches-java/pull/324#discussion_r455409724
##########
File path: src/main/java/org/apache/datasketches/theta/AnotB.java
##########
@@ -47,55 +62,174 @@ public Family getFamily() {
}
/**
- * Gets the result of this operation as an ordered CompactSketch on the Java
heap
- * @return the result of this operation as an ordered CompactSketch on the
Java heap
+ * This is part of a multistep, stateful AnotB operation and sets the given
Tuple sketch as the
+ * first argument <i>A</i> of <i>A-AND-NOT-B</i>. This overwrites the
internal state of this
+ * AnotB operator with the contents of the given sketch.
+ * This sets the stage for multiple following <i>notB</i> steps.
+ *
+ * <p>An input argument of null will throw an exception.</p>
+ *
+ * <p>Rationale: In mathematics a "null set" is a set with no members, which
we call an empty set.
+ * That is distinctly different from the java <i>null</i>, which represents
a nonexistant object.
+ * In most cases it is a programming error due to some object that was not
properly initialized.
+ * With a null as the first argument, we cannot know what the user's intent
is.
+ * Since it is very likely that a <i>null</i> is a programming error, we
throw a an exception.</p>
+ *
+ * <p>An enpty input argument will set the internal state to empty.</p>
+ *
+ * <p>Rationale: An empty set is a mathematically legal concept. Although it
makes any subsequent,
+ * valid argument for B irrelvant, we must allow this and assume the user
knows what they are
+ * doing.</p>
+ *
+ * <p>Performing {@link #getResult(boolean)} just after this step will
return a compact form of
+ * the given argument.</p>
+ *
+ * @param skA The incoming sketch for the first argument, <i>A</i>.
*/
- public abstract CompactSketch getResult();
+ public abstract void setA(Sketch skA);
/**
- * Gets the result of this set operation as a CompactSketch of the chosen
form
- * @param dstOrdered
- * <a href="{@docRoot}/resources/dictionary.html#dstOrdered">See Destination
Ordered</a>.
+ * This is part of a multistep, stateful AnotB operation and sets the given
Tuple sketch as the
+ * second (or <i>n+1</i>th) argument <i>B</i> of <i>A-AND-NOT-B</i>.
+ * Performs an <i>AND NOT</i> operation with the existing internal state of
this AnotB operator.
*
- * @param dstMem
- * <a href="{@docRoot}/resources/dictionary.html#dstMem">See Destination
Memory</a>.
+ * <p>An input argument of null or empty is ignored.</p>
+ *
+ * <p>Rationale: A <i>null</i> for the second or following arguments is more
tollerable because
+ * <i>A NOT null</i> is still <i>A</i> even if we don't know exactly what
the null represents. It
+ * clearly does not have any content that overlaps with <i>A</i>. Also,
because this can be part of
+ * a multistep operation with multiple <i>notB</i> steps. Other following
steps can still produce
+ * a valid result.</p>
+ *
+ * <p>Use {@link #getResult(boolean)} to obtain the result.</p>
*
- * @return the result of this set operation as a CompactSketch of the chosen
form
+ * @param skB The incoming Tuple sketch for the second (or following)
argument <i>B</i>.
*/
- public abstract CompactSketch getResult(boolean dstOrdered, WritableMemory
dstMem);
+ public abstract void notB(Sketch skB);
Review comment:
Good catch. This is a copy/paste error. Thank you!
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
[email protected]
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
