# 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, 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