S
- Type of Summarypublic final class AnotB<S extends Summary> extends Object
The stateful operation is as follows:
AnotB anotb = new AnotB();
anotb.setA(Sketch skA); //The first argument.
anotb.notB(Sketch skB); //The second (subtraction) argument.
anotb.notB(Sketch skC); // ...any number of additional subtractions...
anotb.getResult(false); //Get an interim result.
anotb.notB(Sketch skD); //Additional subtractions.
anotb.getResult(true); //Final result and resets the AnotB operator.
The stateless operation is as follows:
AnotB anotb = new AnotB();
CompactSketch csk = anotb.aNotB(Sketch skA, Sketch skB);
Calling the setA operation a second time essentially clears the internal state and loads the new sketch.
The stateless and stateful operations are independent of each other.
Constructor and Description |
---|
AnotB() |
Modifier and Type | Method and Description |
---|---|
static <S extends Summary> |
aNotB(Sketch<S> skA,
Sketch skB)
Returns the A-and-not-B set operation on a Tuple sketch and a Theta sketch.
|
static <S extends Summary> |
aNotB(Sketch<S> skA,
Sketch<S> skB)
Returns the A-and-not-B set operation on the two given Tuple sketches.
|
CompactSketch<S> |
getResult(boolean reset)
Gets the result of the multistep, stateful operation AnotB that have been executed with calls
to
setA(Sketch) and (notB(Sketch) or
notB(org.apache.datasketches.theta.Sketch) ). |
void |
notB(Sketch skB)
This is part of a multistep, stateful AnotB operation and sets the given Theta sketch as the
second (or n+1th) argument B of A-AND-NOT-B.
|
void |
notB(Sketch<S> skB)
This is part of a multistep, stateful AnotB operation and sets the given Tuple sketch as the
second (or n+1th) argument B of A-AND-NOT-B.
|
void |
reset()
Resets this operation back to the empty state.
|
void |
setA(Sketch<S> skA)
This is part of a multistep, stateful AnotB operation and sets the given Tuple sketch as the
first argument A of A-AND-NOT-B.
|
public void setA(Sketch<S> skA)
An input argument of null will throw an exception.
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 null, which represents a nonexistent 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 null is a programming error, we throw a an exception.
An empty input argument will set the internal state to empty.
Rationale: An empty set is a mathematically legal concept. Although it makes any subsequent, valid argument for B irrelevant, we must allow this and assume the user knows what they are doing.
Performing getResult(boolean)
just after this step will return a compact form of
the given argument.
skA
- The incoming sketch for the first argument, A.public void notB(Sketch<S> skB)
An input argument of null or empty is ignored.
Rationale: A null for the second or following arguments is more tolerable because A NOT null is still A even if we don't know exactly what the null represents. It clearly does not have any content that overlaps with A. Also, because this can be part of a multistep operation with multiple notB steps. Other following steps can still produce a valid result.
Use getResult(boolean)
to obtain the result.
skB
- The incoming Tuple sketch for the second (or following) argument B.public void notB(Sketch skB)
notB(org.apache.datasketches.theta.Sketch)
.
An input argument of null or empty is ignored.
Rationale: A null for the second or following arguments is more tolerable because A NOT null is still A even if we don't know exactly what the null represents. It clearly does not have any content that overlaps with A. Also, because this can be part of a multistep operation with multiple notB steps. Other following steps can still produce a valid result.
Use getResult(boolean)
to obtain the result.
skB
- The incoming Theta sketch for the second (or following) argument B.public CompactSketch<S> getResult(boolean reset)
setA(Sketch)
and (notB(Sketch)
or
notB(org.apache.datasketches.theta.Sketch)
).reset
- If true, clears this operator to the empty state after this result is
returned. Set this to false if you wish to obtain an intermediate result.CompactSketch
.public static <S extends Summary> CompactSketch<S> aNotB(Sketch<S> skA, Sketch<S> skB)
This a stateless operation and has no impact on the internal state of this operator.
Thus, this is not an accumulating update and is independent of the setA(Sketch)
,
notB(Sketch)
, notB(org.apache.datasketches.theta.Sketch)
, and
getResult(boolean)
methods.
If either argument is null an exception is thrown.
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 null, which represents a nonexistent 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 null is a programming error, we throw an exception.
S
- Type of SummaryskA
- The incoming Tuple sketch for the first argumentskB
- The incoming Tuple sketch for the second argumentCompactSketch
public static <S extends Summary> CompactSketch<S> aNotB(Sketch<S> skA, Sketch skB)
This a stateless operation and has no impact on the internal state of this operator.
Thus, this is not an accumulating update and is independent of the setA(Sketch)
,
notB(Sketch)
, notB(org.apache.datasketches.theta.Sketch)
, and
getResult(boolean)
methods.
If either argument is null an exception is thrown.
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 null, which represents a nonexistent 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 null is a programming error for either argument we throw a an exception.
S
- Type of SummaryskA
- The incoming Tuple sketch for the first argumentskB
- The incoming Theta sketch for the second argumentCompactSketch
public void reset()
Copyright © 2015–2024 The Apache Software Foundation. All rights reserved.