Package uk.ac.starlink.table.join

# Interface Coverage

All Known Implementing Classes:
  `CuboidCoverage`, `SkyCoverage`

public interface Coverage
Provides a compact representation of a region of space. An instance of this class is in general mutable, and starts off empty but can be extended by feeding it tuples via the `extend(java.lang.Object[])` method. Once populated, tests for inclusion of other tuples in the coverage thus represented can be performed by use of the `createTestFactory()` method.

The details of how the accumulated set of input tuples affects the inclusion of test tuples are determined by the nature of the matching a given coverage implementation is designed to support. When used for crossmatching, the idea is that the coverage represents the region of space in which an external tuple must be included in order to be a potential match.

Instances of this class are not thread-safe, so should not be used from multiple threads concurrently.

Since:
  8 Jun 2022
Author:
  Mark Taylor

## Field Summary

Fields
Modifier and Type
Field
Description
`static final Coverage`
`FULL`
Instance representing full coverage.

## Method Summary

Modifier and Type
Method
Description
`String`
`coverageText()`
Provides a short, human-readable indication of the coverage.
`Supplier<Predicate<Object[]>>`
`createTestFactory()`
Returns a supplier for an object that can test whether given tuples are considered to fall within the current state of this coverage object.
`void`
`extend(Object[] tuple)`
Extends this coverage by adding a tuple to it.
`void`
`intersection(Coverage other)`
Narrows this coverage object to contain only the intersection of its current state and the supplied coverage.
`boolean`
`isEmpty()`
Returns true if the coverage represents the empty set.
`void`
`union(Coverage other)`
Modifies the state of this coverage object as if all the tuples fed to the other had been fed to this one as well as its current contents.

## Field Details

### FULL

static final Coverage FULL
Instance representing full coverage. The `createTestFactory()` test always returns true. Note that in accordance with the general contract, the set operations are only supported for use with compatible coverage objects, so attempting to perform an intersection with another coverage instance will fail (with an UnsupportedOperationException).

## Method Details

### extend

void extend(Object[] tuple)
Extends this coverage by adding a tuple to it. The tuple contains the coordinates of a row from a table suitable for use with this coverage. The state of this coverage object should not depend on the order in which tuples are submitted.

Parameters:
  `tuple` - coordinate data

### createTestFactory

Supplier<Predicate<Object[]>> createTestFactory()
Returns a supplier for an object that can test whether given tuples are considered to fall within the current state of this coverage object. The returned Supplier must be thread-safe, and should not be affected by subsequent changes to the state of this coverage object. The Predicates it dispenses however are not required to be thread-safe, and must not be used concurrently from different threads.

Returns:
  supplier of tuple inclusion tests

### isEmpty

boolean isEmpty()
Returns true if the coverage represents the empty set.

Returns:
  true iff the `createTestFactory()` test is guaranteed to return false

### intersection

void intersection(Coverage other)
Narrows this coverage object to contain only the intersection of its current state and the supplied coverage.

Parameters:
  `other` - different coverage object of a type assumed compatible with this object

### union

void union(Coverage other)
Modifies the state of this coverage object as if all the tuples fed to the other had been fed to this one as well as its current contents.

Parameters:
  `other` - different coverage object of a type assumed compatible with this object

### coverageText

String coverageText()
Provides a short, human-readable indication of the coverage.

Returns:
  string representation