# Class CuboidCoverage

java.lang.Object
uk.ac.starlink.table.join.CuboidCoverage

All Implemented Interfaces:
  `Coverage`

public abstract class CuboidCoverage extends Object implements Coverage
Partial coverage implementation representing an N-dimensional hypercuboid. It is suitable for representing simple contiguous regions in N-dimensional Cartesian space.

Factory methods are provided for concrete instances of this class.

Since:
  8 Jun 2022
Author:
  Mark Taylor

## Nested Class Summary

Nested Classes
Modifier and Type
Class
Description
`static interface`
`CuboidCoverage.ErrorDecoder`
Defines mapping of tuple to error value.
`static interface`
`CuboidCoverage.PointDecoder`
Defines mapping of tuple to Cartesian position.

## Field Summary

### Fields inherited from interface Coverage

`FULL`

## Constructor Summary

Constructors
Modifier
Constructor
Description
`protected`
`CuboidCoverage(int ndim)`
Constructor.

## Method Summary

Modifier and Type
Method
Description
`String`
`coverageText()`
Provides a short, human-readable indication of the coverage.
`static CuboidCoverage.PointDecoder`
`createCartesianPointDecoder(int ndim)`
Returns a PointDecoder for simple Cartesian tuples.
`static CuboidCoverage`
`createFixedCartesianCoverage(int ndim, double err)`
Creates a coverage suitable for a fixed isotropic match error in an N-dimensional Cartesian space, where tuples are simple N-dimensional coordinate vectors.
`static CuboidCoverage`
`createFixedCartesianCoverage(int ndim, double[] errs)`
Creates a coverage suitable for a fixed anisotropic match error in an N-dimensional Cartesian space, where tuples are simple N-dimensional coordinate vectors.
`static CuboidCoverage`
`createFixedErrorCoverage(int ndim, double[] errors, CuboidCoverage.PointDecoder pointDecoder)`
Creates a coverage suitable for a fixed anisotropic match error in an N-dimensional coordinate space, with custom tuple->coordinate mapping.
`static CuboidCoverage`
`createVariableErrorCoverage(int ndim, CuboidCoverage.PointDecoder pointDecoder, CuboidCoverage.ErrorDecoder errorDecoder)`
Creates a coverage suitable for variable isotropic match errors in an N-dimensional coordinate space.
`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.

### Methods inherited from class Object

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

### Methods inherited from interface Coverage

`createTestFactory, extend`

## Constructor Details

### CuboidCoverage

protected CuboidCoverage(int ndim)
Constructor. Instance is empty on construction.

Parameters:
  `ndim` - dimensionality of region

## Method Details

### isEmpty

public boolean isEmpty()
Description copied from interface: `Coverage`
Returns true if the coverage represents the empty set.

Specified by:
  `isEmpty` in interface `Coverage`
Returns:
  true iff the `Coverage.createTestFactory()` test is guaranteed to return false

### union

public void union(Coverage other)
Description copied from interface: `Coverage`
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.

Specified by:
  `union` in interface `Coverage`
Parameters:
  `other` - different coverage object of a type assumed compatible with this object

### intersection

public void intersection(Coverage other)
Description copied from interface: `Coverage`
Narrows this coverage object to contain only the intersection of its current state and the supplied coverage.

Specified by:
  `intersection` in interface `Coverage`
Parameters:
  `other` - different coverage object of a type assumed compatible with this object

### coverageText

public String coverageText()
Description copied from interface: `Coverage`
Provides a short, human-readable indication of the coverage.

Specified by:
  `coverageText` in interface `Coverage`
Returns:
  string representation

### createFixedCartesianCoverage

public static CuboidCoverage createFixedCartesianCoverage(int ndim, double err)
Creates a coverage suitable for a fixed isotropic match error in an N-dimensional Cartesian space, where tuples are simple N-dimensional coordinate vectors.

Parameters:
  `ndim` - dimensionality
  `err` - maximum separation for match
Returns:
  new empty coverage

### createFixedCartesianCoverage

public static CuboidCoverage createFixedCartesianCoverage(int ndim, double[] errs)
Creates a coverage suitable for a fixed anisotropic match error in an N-dimensional Cartesian space, where tuples are simple N-dimensional coordinate vectors.

Parameters:
  `ndim` - dimensionality
  `errs` - ndim-dimensional array giving maximum separations along each axis
Returns:
  new empty coverage

### createFixedErrorCoverage

public static CuboidCoverage createFixedErrorCoverage(int ndim, double[] errors, CuboidCoverage.PointDecoder pointDecoder)
Creates a coverage suitable for a fixed anisotropic match error in an N-dimensional coordinate space, with custom tuple->coordinate mapping.

Parameters:
  `ndim` - dimensionality of Cartesian space
  `errors` - ndim-dimensional array giving maximum separations along each axis
  `pointDecoder` - thread-safe converter of tuples into N-dimensional Cartesian position vectors
Returns:
  new empty coverage

### createVariableErrorCoverage

public static CuboidCoverage createVariableErrorCoverage(int ndim, CuboidCoverage.PointDecoder pointDecoder, CuboidCoverage.ErrorDecoder errorDecoder)
Creates a coverage suitable for variable isotropic match errors in an N-dimensional coordinate space.

Parameters:
  `ndim` - dimensionality of Cartesian space
  `pointDecoder` - thread-safe converter of tuples into N-dimensional Cartesian position vectors
  `errorDecoder` - thread-safe extractor of isotropic maximum match separation from tuples
Returns:
  new empty coverage

### createCartesianPointDecoder

public static CuboidCoverage.PointDecoder createCartesianPointDecoder(int ndim)
Returns a PointDecoder for simple Cartesian tuples.

Parameters:
  `ndim` - dimensionality of tuples and output vectors
Returns:
  new point decoder