Skip to content

# Comparing Values

Preserves specifies a total ordering and an equivalence between terms. The preserves.compare module implements the ordering and equivalence relations.

    >>> cmp("bzz", "c")
    -1
    >>> cmp(True, [])
    -1
    >>> lt("bzz", "c")
    True
    >>> eq("bzz", "c")
    False

Note that the ordering relates more values than Python's built-in ordering:

    >>> [1, 2, 2] < [1, 2, "3"]
    Traceback (most recent call last):
      ..
    TypeError: '<' not supported between instances of 'int' and 'str'

    >>> lt([1, 2, 2], [1, 2, "3"])
    True

## `cmp(a, b)`

Returns `-1` if `a` < `b`, or `0` if `a` = `b`, or `1` if `a` > `b` according to the Preserves total order.

Source code in `preserves/compare.py`

    83
    84
    85
    86
    def cmp(a, b):
        """Returns `-1` if `a` < `b`, or `0` if `a` = `b`, or `1` if `a` > `b` according to the
        [Preserves total order](https://preserves.dev/preserves.html#total-order)."""
        return _cmp(preserve(a), preserve(b))

## `eq(a, b)`

Returns `True` iff `a` = `b` according to the Preserves equivalence relation.

Source code in `preserves/compare.py`

     98
     99
    100
    101
    def eq(a, b):
        """Returns `True` iff `a` = `b` according to the [Preserves equivalence
        relation](https://preserves.dev/preserves.html#equivalence)."""
        return _eq(preserve(a), preserve(b))

## `le(a, b)`

Returns `True` iff `a` ≤ `b` according to the Preserves total order.

Source code in `preserves/compare.py`

    93
    94
    95
    96
    def le(a, b):
        """Returns `True` iff `a` ≤ `b` according to the [Preserves total
        order](https://preserves.dev/preserves.html#total-order)."""
        return cmp(a, b) <= 0

## `lt(a, b)`

Returns `True` iff `a` < `b` according to the Preserves total order.

Source code in `preserves/compare.py`

    88
    89
    90
    91
    def lt(a, b):
        """Returns `True` iff `a` < `b` according to the [Preserves total
        order](https://preserves.dev/preserves.html#total-order)."""
        return cmp(a, b) < 0

## `sorted(iterable, *, key=lambda x: x, reverse=False)`

Returns a sorted list built from `iterable`, extracting a sort key using `key`, and ordering according to the Preserves total order. Directly analogous to the built-in Python `sorted` routine, except uses the Preserves order instead of Python's less-than relation.

Source code in `preserves/compare.py`

    107
    108
    109
    110
    111
    112
    113
    114
    115
    116
    def sorted(iterable, *, key=lambda x: x, reverse=False):
        """Returns a sorted list built from `iterable`, extracting a sort key using `key`, and
        ordering according to the [Preserves total
        order](https://preserves.dev/preserves.html#total-order). Directly analogous to the
        [built-in Python `sorted`
        routine](https://docs.python.org/3/library/functions.html#sorted), except uses the
        Preserves order instead of Python's less-than relation.

        """
        return _sorted(iterable, key=lambda x: _key(key(x)), reverse=reverse)

## `sorted_items(d)`

Given a dictionary `d`, yields a list of `(key, value)` tuples sorted by `key`.

Source code in `preserves/compare.py`

    118
    119
    120
    def sorted_items(d):
        """Given a dictionary `d`, yields a list of `(key, value)` tuples sorted by `key`."""
        return sorted(d.items(), key=_item_key)

Last update: March 16, 2023
Created: March 16, 2023