# Nearest Dictionary Recipe

class sortedcollections.NearestDict(*args, **kwargs)

  A dict using nearest-key lookup.

  A `SortedDict` subclass that uses nearest-key lookup instead of exact-key lookup. Optionally, you can specify a rounding mode to return the nearest key less than or equal to or greater than or equal to the provided key.

  When using `NearestDict.NEAREST` the keys must support subtraction to allow finding the nearest key (by find the key with the smallest difference to the given one).

  Additional methods:

  - `NearestDict.nearest_key()`

  Example usage:

      >>> d = NearestDict({1.0: 'foo'})
      >>> d[1.0]
      'foo'
      >>> d[0.0]
      'foo'
      >>> d[2.0]
      'foo'

  __getitem__(request)

    Return item corresponding to `nearest_key()`.

    Parameters:

      request – nearest-key lookup value

    Returns:

      item corresponding to key nearest request

    Raises:

      KeyError – if no appropriate item can be found

        >>> d = NearestDict({1.0: 'foo'})
        >>> d[0.0]
        'foo'
        >>> d[2.0]
        'foo'

        >>> d = NearestDict({1.0: 'foo'}, rounding=NearestDict.NEAREST_NEXT)
        >>> d[0.0]
        'foo'
        >>> d[2.0]
        Traceback (most recent call last):
          ...
        KeyError: 'No key above 2.0 found'

  __init__(*args, **kwargs)

    Initialize a NearestDict instance.

    Optional rounding argument dictates how `NearestDict.nearest_key()` rounds. It must be one of `NearestDict.NEAREST_NEXT`, `NearestDict.NEAREST`, or `NearestDict.NEAREST_PREV`. (Default: `NearestDict.NEAREST`)

    Params rounding:

      how to round on nearest-key lookup (optional)

    Params args:

      positional arguments for `SortedDict`.

    Params kwargs:

      keyword arguments for `SortedDict`.

  nearest_key(request)

    Return nearest-key to request, respecting self.rounding.

        >>> d = NearestDict({1.0: 'foo'})
        >>> d.nearest_key(0.0)
        1.0
        >>> d.nearest_key(2.0)
        1.0

        >>> d = NearestDict({1.0: 'foo'}, rounding=NearestDict.NEAREST_PREV)
        >>> d.nearest_key(0.0)
        Traceback (most recent call last):
          ...
        KeyError: 'No key below 0.0 found'
        >>> d.nearest_key(2.0)
        1.0

    Parameters:

      request – nearest-key lookup value

    Returns:

      key nearest to request, respecting rounding

    Raises:

      KeyError – if no appropriate key can be found