Package generic

# Interface Span.Domain<N,S extends Span<N,S>>

Type Parameters:
  `N` - the type of endpoints
  `S` - the type of spans

All Known Implementing Classes:
  `End.EndDomain`, `FieldSpan.Domain`, `KeySpan.Domain`, `Lifespan.Domain`, `ULongSpan.Domain`

Enclosing interface:
  `Span<N,S extends Span<N,S>>`

public static interface Span.Domain<N,S extends Span<N,S>>
The (discrete) domain of endpoints for a span

This defines the domain, which may introduce behaviors different than those naturally acquired from the type. For example, a domain may impose unsigned comparison on a (boxed) primitive type.

Implementation Notes:
  each domain should be a singleton class

- ## Method Summary

  Modifier and Type
  Method
  Description
  `S`
  `all()`
  Get the span containing all values in the domain
  `default S`
  `atLeast(N min)`
  Construct a new span with the given lower endpoint, inclusive.
  `default S`
  `atMost(N max)`
  Construct a new span with the given upper endpoint, inclusive.
  `default S`
  `bound(S s1, S s2)`
  Compute the smallest span which contains two spans
  `default S`
  `closed(N min, N max)`
  Create a new span with the given endpoints, inclusive.
  `int`
  `compare(N n1, N n2)`
  Compare two values
  `N`
  `dec(N n)`
  Get a given value, decremented by 1
  `S`
  `empty()`
  Get the span that contains no value, nor has any endpoints
  `default boolean`
  `encloses(S s1, S s2)`
  Check if one span encloses another
  `N`
  `inc(N n)`
  Get a given value, incremented by 1
  `default S`
  `intersect(S s1, S s2)`
  Compute the intersection of two spans
  `default boolean`
  `intersects(S s1, S s2)`
  Check if two spans intersect
  `N`
  `max()`
  Get the maximum value in the domain
  `default N`
  `max(N n1, N n2)`
  Get the greater of two values
  `N`
  `min()`
  Get the minimum value in the domain
  `default N`
  `min(N n1, N n2)`
  Get the lesser of two values
  `S`
  `newSpan(N min, N max)`
  Factory method for a new span after arguments are validated
  `default List<S>`
  `subtract(S s1, S s2)`
  Subtract two spans
  `default String`
  `toMaxString(N max, Function<? super N,String> nToString)`
  Render the upper bound of a span
  `default String`
  `toMinString(N min, Function<? super N,String> nToString)`
  Render the lower bound of a span
  `default String`
  `toString(N n)`
  Render the given value as a string
  `default String`
  `toString(S s)`
  Render the given span as a string
  `default String`
  `toString(S s, Function<? super N,String> nToString)`
  Render the given span as a string
  `default S`
  `value(N n)`
  Construct a span containing only the given value

- ## Method Details

  - ### closed

    default S closed(N min, N max)
    Create a new span with the given endpoints, inclusive.
    Parameters:
      `min` - the lower endpoint
      `max` - the upper endpoint
    Returns:
      the span
    Throws:
      `IllegalArgumentException` - if max is less than min

  - ### newSpan

    S newSpan(N min, N max)
    Factory method for a new span after arguments are validated
    Parameters:
      `min` - the lower endpoint
      `max` - the upper endpoint
    Returns:
      the span

  - ### value

    default S value(N n)
    Construct a span containing only the given value
    Parameters:
      `n` - the value
    Returns:
      the span

  - ### atMost

    default S atMost(N max)
    Construct a new span with the given upper endpoint, inclusive.

    The lower endpoint becomes the minimum value in the domain

    Parameters:
      `max` - the upper endpoint
    Returns:
      the span

  - ### atLeast

    default S atLeast(N min)
    Construct a new span with the given lower endpoint, inclusive.

    The upper endpoint becomes the maximum value in the domain

    Parameters:
      `min` - the lower endpoint
    Returns:
      the span

  - ### all

    S all()
    Get the span containing all values in the domain
    Returns:
      the span
    Implementation Notes:
      It is recommended to return a static object

  - ### empty

    S empty()
    Get the span that contains no value, nor has any endpoints

    This span is returned when the result doesn't exist, e.g., when finding the intersection of spans which do not intersect.

    Returns:
      the empty span
    Implementation Notes:
      It is recommended to implement `Span.Empty` as a singleton class and return its instance

  - ### toString

    default String toString(N n)
    Render the given value as a string
    Parameters:
      `n` - the value
    Returns:
      the string

  - ### toString

    default String toString(S s)
    Render the given span as a string
    Parameters:
      `s` - the span
    Returns:
      the string

  - ### toString

    default String toString(S s, Function<? super N,String> nToString)
    Render the given span as a string
    Parameters:
      `s` - the span
      `nToString` - a function to convert n to a string
    Returns:
      the string

  - ### toMinString

    default String toMinString(N min, Function<? super N,String> nToString)
    Render the lower bound of a span
    Parameters:
      `min` - the lower bound
      `nToString` - a function to convert n to a string
    Returns:
      the string

  - ### toMaxString

    default String toMaxString(N max, Function<? super N,String> nToString)
    Render the upper bound of a span
    Parameters:
      `max` - the upper bound
      `nToString` - a function to convert n to a string
    Returns:
      the string

  - ### compare

    int compare(N n1, N n2)
    Compare two values
    Parameters:
      `n1` - a value
      `n2` - another value
    Returns:
      the result, as in `Comparator.compare(Object, Object)`

  - ### min

    N min()
    Get the minimum value in the domain

    This value can also represent negative infinity.

    Returns:
      the minimum value

  - ### max

    N max()
    Get the maximum value in the domain

    This value can also represent positive infinity.

    Returns:
      the maximum value

  - ### inc

    N inc(N n)
    Get a given value, incremented by 1

    If the resulting value would exceed `max()`, this should wrap to `min()`.

    Parameters:
      `n` - the value
    Returns:
      the value incremented

  - ### dec

    N dec(N n)
    Get a given value, decremented by 1

    If the resulting value would exceed `min()`, this should wrap to `max()`.

    Parameters:
      `n` - the value
    Returns:
      the value decremented

  - ### min

    default N min(N n1, N n2)
    Get the lesser of two values

    If the values are equal, then either may be chosen

    Parameters:
      `n1` - a value
      `n2` - another value
    Returns:
      the lesser

  - ### max

    default N max(N n1, N n2)
    Get the greater of two values

    If the values are equal, then either may be chosen

    Parameters:
      `n1` - a value
      `n2` - another value
    Returns:
      the greater

  - ### intersect

    default S intersect(S s1, S s2)
    Compute the intersection of two spans
    Parameters:
      `s1` - a span
      `s2` - another span
    Returns:
      the intersection, possibly empty

  - ### intersects

    default boolean intersects(S s1, S s2)
    Check if two spans intersect
    Parameters:
      `s1` - a span
      `s2` - another span
    Returns:
      true if they intersect

  - ### encloses

    default boolean encloses(S s1, S s2)
    Check if one span encloses another
    Parameters:
      `s1` - a span
      `s2` - another span
    Returns:
      true if s1 encloses s2

  - ### bound

    default S bound(S s1, S s2)
    Compute the smallest span which contains two spans
    Parameters:
      `s1` - a span
      `s2` - another span
    Returns:
      the bounding span

  - ### subtract

    default List<S> subtract(S s1, S s2)
    Subtract two spans

    If the first span is empty, this returns 0 spans.

    Parameters:
      `s1` - a span
      `s2` - another span
    Returns:
      0, 1, or 2 spans