AlexanderSaydakov commented on a change in pull request #324:
URL:
https://github.com/apache/incubator-datasketches-java/pull/324#discussion_r455458636
##########
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
Theta 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
Theta 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 Theta sketch for the second (or following)
argument <i>B</i>.
*/
- public abstract CompactSketch getResult(boolean dstOrdered, WritableMemory
dstMem);
+ public abstract void notB(Sketch skB);
/**
- * Perform A-and-not-B set operation on the two given sketches.
- * A null sketch is interpreted as an empty sketch.
+ * Gets the result of the mutistep, stateful operation AnotB that have been
executed with calls
+ * to {@link #setA(Sketch)} and ({@link #notB(Sketch)} or
+ * {@link #notB(org.apache.datasketches.theta.Sketch)}).
+ *
+ * @param reset If <i>true</i>, clears this operator to the empty state
after this result is
+ * returned. Set this to <i>false</i> if you wish to obtain an intermediate
result.
+ * @return the result of this operation as an ordered, on-heap {@link
CompactSketch}.
+ */
+ public abstract CompactSketch getResult(boolean reset);
+
+ /**
+ * Gets the result of this stateful set operation as a CompactSketch of the
form based on
+ * the input arguments.
+ * The stateful input operations are {@link #setA(Sketch)} and {@link
#notB(Sketch)}.
+ *
+ * @param dstOrdered If <i>true</i>, the result will be an ordered {@link
CompactSketch}.
+ * <a href="{@docRoot}/resources/dictionary.html#dstOrdered">See Destination
Ordered</a>.
+ *
+ * @param dstMem if not <i>null</i> the given Memory will be the target
location of the result.
+ * <a href="{@docRoot}/resources/dictionary.html#dstMem">See Destination
Memory</a>.
*
- * @param a The incoming sketch for the first argument
- * @param b The incoming sketch for the second argument
+ * @param reset If <i>true</i>, clears this operator to the empty state
after this result is
+ * returned. Set this to <i>false</i> if you wish to obtain an intermediate
result.
+ *
+ * @return the result of this operation as a {@link CompactSketch} of the
chosen form.
*/
- public abstract void update(Sketch a, Sketch b);
+ public abstract CompactSketch getResult(boolean dstOrdered, WritableMemory
dstMem, boolean reset);
/**
* Perform A-and-not-B set operation on the two given sketches and return
the result as an
* ordered CompactSketch on the heap.
- * @param a The incoming sketch for the first argument
- * @param b The incoming sketch for the second argument
+ *
+ * <p>This a stateless operation and has no impact on the internal state of
this operator.
+ * Thus, this is not an accumulating update and does not interact with the
{@link #setA(Sketch)},
+ * {@link #notB(Sketch)}, {@link #getResult(boolean)}, or
+ * {@link #getResult(boolean, WritableMemory, boolean)} methods.</p>
+ *
+ * <p>If either argument is null an exception is thrown.</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.
+ * With a null as the second argument, we can't ignore it as we must return
a result and there is
+ * no following possible viable arguments for the second argument.
+ * Since it is very likely that a <i>null</i> is a programming error, we
throw a an exception.</p>
+ *
+ * @param skA The incoming sketch for the first argument.
+ * @param skB The incoming sketch for the second argument.
* @return an ordered CompactSketch on the heap
*/
- public CompactSketch aNotB(final Sketch a, final Sketch b) {
- return aNotB(a, b, true, null);
+ public CompactSketch aNotB(final Sketch skA, final Sketch skB) {
+ return aNotB(skA, skB, true, null);
}
/**
* Perform A-and-not-B set operation on the two given sketches and return
the result as a
* CompactSketch.
- * @param a The incoming sketch for the first argument
- * @param b The incoming sketch for the second argument
+ *
+ * <p>This a stateless operation and has no impact on the internal state of
this operator.
+ * Thus, this is not an accumulating update and does not interact with the
{@link #setA(Sketch)},
+ * {@link #notB(Sketch)}, {@link #getResult(boolean)}, or
+ * {@link #getResult(boolean, WritableMemory, boolean)} methods.</p>
+ *
+ * <p>If either argument is null an exception is thrown.</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.
Review comment:
nonexistent
----------------------------------------------------------------
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]
