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 
82
83
84
85
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 
 97
 98
 99
100
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 
92
93
94
95
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 
87
88
89
90
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 
106
107
108
109
110
111
112
113
114
115
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 
117
118
119
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)