# Class ThetaAnotB

java.lang.Object
org.apache.datasketches.theta.ThetaSetOperation
org.apache.datasketches.theta.ThetaAnotB

All Implemented Interfaces:
  `MemorySegmentStatus`

public abstract class ThetaAnotB extends ThetaSetOperation
Computes a set difference, A-AND-NOT-B, of two ThetaSketches. This class includes both stateful and stateless operations.

The stateful operation is as follows:

    ThetaAnotB anotb = ThetaSetOperationBuilder.buildAnotB();

    anotb.setA(ThetaSketch skA); //The first argument.
    anotb.notB(ThetaSketch skB); //The second (subtraction) argument.
    anotb.notB(ThetaSketch skC); // ...any number of additional subtractions...
    anotb.getResult(false); //Get an interim result.
    anotb.notB(ThetaSketch skD); //Additional subtractions.
    anotb.getResult(true);  //Final result and resets the ThetaAnotB operator.

The stateless operation is as follows:

    ThetaAnotB anotb = ThetaSetOperationBuilder.buildAnotB();

    CompactThetaSketch csk = anotb.aNotB(ThetaSketch skA, ThetaSketch skB);

Calling the setA operation a second time essentially clears the internal state and loads the new ThetaSketch.

The stateless and stateful operations are independent of each other with the exception of sharing the same update hash seed loaded as the default seed or specified by the user as an argument to the builder.

Author:
  Lee Rhodes

## Method Summary

Modifier and Type
Method
Description
`CompactThetaSketch`
`aNotB(ThetaSketch skA, ThetaSketch skB)`
Perform A-and-not-B set operation on the two given sketches and return the result as an ordered CompactThetaSketch on the heap.
`abstract CompactThetaSketch`
`aNotB(ThetaSketch skA, ThetaSketch skB, boolean dstOrdered, MemorySegment dstSeg)`
Perform A-and-not-B set operation on the two given sketches and return the result as a CompactThetaSketch.
`Family`
`getFamily()`
Gets the Family of this ThetaSetOperation
`abstract CompactThetaSketch`
`getResult(boolean reset)`
Gets the result of the multistep, stateful operation ThetaAnotB that have been executed with calls to `setA(ThetaSketch)` and (`notB(ThetaSketch)` or `notB(org.apache.datasketches.theta.ThetaSketch)`).
`abstract CompactThetaSketch`
`getResult(boolean dstOrdered, MemorySegment dstSeg, boolean reset)`
Gets the result of the multistep, stateful operation ThetaAnotB that have been executed with calls to `setA(ThetaSketch)` and (`notB(ThetaSketch)` or `notB(org.apache.datasketches.theta.ThetaSketch)`).
`abstract void`
`notB(ThetaSketch skB)`
This is part of a multistep, stateful ThetaAnotB operation and sets the given ThetaSketch as the second (or n+1th) argument B of A-AND-NOT-B.
`abstract void`
`setA(ThetaSketch skA)`
This is part of a multistep, stateful ThetaAnotB operation and sets the given ThetaSketch as the first argument A of A-AND-NOT-B.

### Methods inherited from class ThetaSetOperation

`builder, getMaxAnotBResultBytes, getMaxIntersectionBytes, getMaxUnionBytes, heapify, heapify, wrap, wrap`

### Methods inherited from class Object

`equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

### Methods inherited from interface MemorySegmentStatus

`hasMemorySegment, isOffHeap, isSameResource`

## Method Details

### getFamily

public Family getFamily()
Description copied from class: `ThetaSetOperation`
Gets the Family of this ThetaSetOperation

Specified by:
  `getFamily` in class `ThetaSetOperation`
Returns:
  the Family of this ThetaSetOperation

### setA

public abstract void setA(ThetaSketch skA)
This is part of a multistep, stateful ThetaAnotB operation and sets the given ThetaSketch as the first argument A of A-AND-NOT-B. This overwrites the internal state of this ThetaAnotB operator with the contents of the given sketch. This sets the stage for multiple following notB steps.

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.

Parameters:
  `skA` - The incoming sketch for the first argument, A.

### notB

public abstract void notB(ThetaSketch skB)
This is part of a multistep, stateful ThetaAnotB operation and sets the given ThetaSketch as the second (or n+1th) argument B of A-AND-NOT-B. Performs an AND NOT operation with the existing internal state of this ThetaAnotB operator.

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.

Parameters:
  `skB` - The incoming ThetaSketch for the second (or following) argument B.

### getResult

public abstract CompactThetaSketch getResult(boolean reset)
Gets the result of the multistep, stateful operation ThetaAnotB that have been executed with calls to `setA(ThetaSketch)` and (`notB(ThetaSketch)` or `notB(org.apache.datasketches.theta.ThetaSketch)`).

Parameters:
  `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.
Returns:
  the result of this operation as an ordered, on-heap `CompactThetaSketch`.

### getResult

public abstract CompactThetaSketch getResult(boolean dstOrdered, MemorySegment dstSeg, boolean reset)
Gets the result of the multistep, stateful operation ThetaAnotB that have been executed with calls to `setA(ThetaSketch)` and (`notB(ThetaSketch)` or `notB(org.apache.datasketches.theta.ThetaSketch)`).

Parameters:
  `dstOrdered` - If true, the result will be an ordered `CompactThetaSketch`. See Destination Ordered.
  `dstSeg` - if not null the given MemorySegment will be the target location of the result.
  `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.
Returns:
  the result of this operation as a `CompactThetaSketch` in the given dstSeg.

### aNotB

public CompactThetaSketch aNotB(ThetaSketch skA, ThetaSketch skB)
Perform A-and-not-B set operation on the two given sketches and return the result as an ordered CompactThetaSketch on the heap.

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 `setA(ThetaSketch)`, `notB(ThetaSketch)`, `getResult(boolean)`, or `getResult(boolean, MemorySegment, 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 null is a programming error due to a non-initialized object.

With a null as the first argument we cannot know what the user's intent is and throw an exception. With a null as the second argument for this method we must return a result and there is no following possible viable arguments for the second argument so we thrown an exception.

Parameters:
  `skA` - The incoming sketch for the first argument. It must not be null.
  `skB` - The incoming sketch for the second argument. It must not be null.
Returns:
  an ordered CompactThetaSketch on the heap

### aNotB

public abstract CompactThetaSketch aNotB(ThetaSketch skA, ThetaSketch skB, boolean dstOrdered, MemorySegment dstSeg)
Perform A-and-not-B set operation on the two given sketches and return the result as a CompactThetaSketch.

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 `setA(ThetaSketch)`, `notB(ThetaSketch)`, `getResult(boolean)`, or `getResult(boolean, MemorySegment, 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 null is a programming error due to a non-initialized object.

With a null as the first argument we cannot know what the user's intent is and throw an exception. With a null as the second argument for this method we must return a result and there is no following possible viable arguments for the second argument so we thrown an exception.

Parameters:
  `skA` - The incoming sketch for the first argument. It must not be null.
  `skB` - The incoming sketch for the second argument. It must not be null.
  `dstOrdered` - See Destination Ordered.
  `dstSeg` - the destination MemorySegment
Returns:
  the result as a CompactThetaSketch.