Update compare.py docs
This commit is contained in:
parent
514dc04920
commit
c7687772b0
|
|
@ -1,4 +1,33 @@
|
|||
"""TODO"""
|
||||
"""Preserves specifies a [total ordering](https://preserves.dev/preserves.html#total-order) and
|
||||
an [equivalence](https://preserves.dev/preserves.html#equivalence) between terms. This module
|
||||
implements the ordering and equivalence relations.
|
||||
|
||||
```python
|
||||
>>> 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:
|
||||
|
||||
```python
|
||||
>>> [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
|
||||
|
||||
```
|
||||
|
||||
"""
|
||||
|
||||
import numbers
|
||||
from enum import Enum
|
||||
|
|
@ -52,19 +81,23 @@ def type_number(v):
|
|||
return TypeNumber.SEQUENCE
|
||||
|
||||
def cmp(a, b):
|
||||
"""TODO"""
|
||||
"""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))
|
||||
|
||||
def lt(a, b):
|
||||
"""TODO"""
|
||||
"""Returns `True` iff `a` < `b` according to the [Preserves total
|
||||
order](https://preserves.dev/preserves.html#total-order)."""
|
||||
return cmp(a, b) < 0
|
||||
|
||||
def le(a, b):
|
||||
"""TODO"""
|
||||
"""Returns `True` iff `a` ≤ `b` according to the [Preserves total
|
||||
order](https://preserves.dev/preserves.html#total-order)."""
|
||||
return cmp(a, b) <= 0
|
||||
|
||||
def eq(a, b):
|
||||
"""TODO"""
|
||||
"""Returns `True` iff `a` = `b` according to the [Preserves equivalence
|
||||
relation](https://preserves.dev/preserves.html#equivalence)."""
|
||||
return _eq(preserve(a), preserve(b))
|
||||
|
||||
key = cmp_to_key(cmp)
|
||||
|
|
@ -72,11 +105,18 @@ _key = key
|
|||
|
||||
_sorted = sorted
|
||||
def sorted(iterable, *, key=lambda x: x, reverse=False):
|
||||
"""TODO"""
|
||||
"""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)
|
||||
|
||||
def sorted_items(d):
|
||||
"""TODO"""
|
||||
"""Given a dictionary `d`, yields a list of `(key, value)` tuples sorted by `key`."""
|
||||
return sorted(d.items(), key=_item_key)
|
||||
|
||||
def _eq_sequences(aa, bb):
|
||||
|
|
|
|||
|
|
@ -529,7 +529,27 @@
|
|||
<a id="preserves.compare"></a>
|
||||
<div class="doc doc-contents first">
|
||||
|
||||
<p>TODO</p>
|
||||
<p>Preserves specifies a <a href="https://preserves.dev/preserves.html#total-order">total ordering</a> and
|
||||
an <a href="https://preserves.dev/preserves.html#equivalence">equivalence</a> between terms. This module
|
||||
implements the ordering and equivalence relations.</p>
|
||||
<div class="highlight"><pre><span></span><code><span class="o">>>></span> <span class="n">cmp</span><span class="p">(</span><span class="s2">"bzz"</span><span class="p">,</span> <span class="s2">"c"</span><span class="p">)</span>
|
||||
<span class="o">-</span><span class="mi">1</span>
|
||||
<span class="o">>>></span> <span class="n">cmp</span><span class="p">(</span><span class="kc">True</span><span class="p">,</span> <span class="p">[])</span>
|
||||
<span class="o">-</span><span class="mi">1</span>
|
||||
<span class="o">>>></span> <span class="n">lt</span><span class="p">(</span><span class="s2">"bzz"</span><span class="p">,</span> <span class="s2">"c"</span><span class="p">)</span>
|
||||
<span class="kc">True</span>
|
||||
<span class="o">>>></span> <span class="n">eq</span><span class="p">(</span><span class="s2">"bzz"</span><span class="p">,</span> <span class="s2">"c"</span><span class="p">)</span>
|
||||
<span class="kc">False</span>
|
||||
</code></pre></div>
|
||||
<p>Note that the ordering relates more values than Python's built-in ordering:</p>
|
||||
<div class="highlight"><pre><span></span><code><span class="o">>>></span> <span class="p">[</span><span class="mi">1</span><span class="p">,</span> <span class="mi">2</span><span class="p">,</span> <span class="mi">2</span><span class="p">]</span> <span class="o"><</span> <span class="p">[</span><span class="mi">1</span><span class="p">,</span> <span class="mi">2</span><span class="p">,</span> <span class="s2">"3"</span><span class="p">]</span>
|
||||
<span class="n">Traceback</span> <span class="p">(</span><span class="n">most</span> <span class="n">recent</span> <span class="n">call</span> <span class="n">last</span><span class="p">):</span>
|
||||
<span class="o">..</span>
|
||||
<span class="ne">TypeError</span><span class="p">:</span> <span class="s1">'<'</span> <span class="ow">not</span> <span class="n">supported</span> <span class="n">between</span> <span class="n">instances</span> <span class="n">of</span> <span class="s1">'int'</span> <span class="ow">and</span> <span class="s1">'str'</span>
|
||||
|
||||
<span class="o">>>></span> <span class="n">lt</span><span class="p">([</span><span class="mi">1</span><span class="p">,</span> <span class="mi">2</span><span class="p">,</span> <span class="mi">2</span><span class="p">],</span> <span class="p">[</span><span class="mi">1</span><span class="p">,</span> <span class="mi">2</span><span class="p">,</span> <span class="s2">"3"</span><span class="p">])</span>
|
||||
<span class="kc">True</span>
|
||||
</code></pre></div>
|
||||
|
||||
|
||||
|
||||
|
|
@ -555,14 +575,17 @@
|
|||
|
||||
<div class="doc doc-contents ">
|
||||
|
||||
<p>TODO</p>
|
||||
<p>Returns <code>-1</code> if <code>a</code> < <code>b</code>, or <code>0</code> if <code>a</code> = <code>b</code>, or <code>1</code> if <code>a</code> > <code>b</code> according to the
|
||||
<a href="https://preserves.dev/preserves.html#total-order">Preserves total order</a>.</p>
|
||||
|
||||
<details class="quote">
|
||||
<summary>Source code in <code>preserves/compare.py</code></summary>
|
||||
<div class="highlight"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span><span class="normal">54</span>
|
||||
<span class="normal">55</span>
|
||||
<span class="normal">56</span></pre></div></td><td class="code"><div><pre><span></span><code><span class="k">def</span> <span class="nf">cmp</span><span class="p">(</span><span class="n">a</span><span class="p">,</span> <span class="n">b</span><span class="p">):</span>
|
||||
<span class="w"> </span><span class="sd">"""TODO"""</span>
|
||||
<div class="highlight"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span><span class="normal">83</span>
|
||||
<span class="normal">84</span>
|
||||
<span class="normal">85</span>
|
||||
<span class="normal">86</span></pre></div></td><td class="code"><div><pre><span></span><code><span class="k">def</span> <span class="nf">cmp</span><span class="p">(</span><span class="n">a</span><span class="p">,</span> <span class="n">b</span><span class="p">):</span>
|
||||
<span class="w"> </span><span class="sd">"""Returns `-1` if `a` < `b`, or `0` if `a` = `b`, or `1` if `a` > `b` according to the</span>
|
||||
<span class="sd"> [Preserves total order](https://preserves.dev/preserves.html#total-order)."""</span>
|
||||
<span class="k">return</span> <span class="n">_cmp</span><span class="p">(</span><span class="n">preserve</span><span class="p">(</span><span class="n">a</span><span class="p">),</span> <span class="n">preserve</span><span class="p">(</span><span class="n">b</span><span class="p">))</span>
|
||||
</code></pre></div></td></tr></table></div>
|
||||
</details>
|
||||
|
|
@ -582,14 +605,17 @@
|
|||
|
||||
<div class="doc doc-contents ">
|
||||
|
||||
<p>TODO</p>
|
||||
<p>Returns <code>True</code> iff <code>a</code> = <code>b</code> according to the <a href="https://preserves.dev/preserves.html#equivalence">Preserves equivalence
|
||||
relation</a>.</p>
|
||||
|
||||
<details class="quote">
|
||||
<summary>Source code in <code>preserves/compare.py</code></summary>
|
||||
<div class="highlight"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span><span class="normal">66</span>
|
||||
<span class="normal">67</span>
|
||||
<span class="normal">68</span></pre></div></td><td class="code"><div><pre><span></span><code><span class="k">def</span> <span class="nf">eq</span><span class="p">(</span><span class="n">a</span><span class="p">,</span> <span class="n">b</span><span class="p">):</span>
|
||||
<span class="w"> </span><span class="sd">"""TODO"""</span>
|
||||
<div class="highlight"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span><span class="normal"> 98</span>
|
||||
<span class="normal"> 99</span>
|
||||
<span class="normal">100</span>
|
||||
<span class="normal">101</span></pre></div></td><td class="code"><div><pre><span></span><code><span class="k">def</span> <span class="nf">eq</span><span class="p">(</span><span class="n">a</span><span class="p">,</span> <span class="n">b</span><span class="p">):</span>
|
||||
<span class="w"> </span><span class="sd">"""Returns `True` iff `a` = `b` according to the [Preserves equivalence</span>
|
||||
<span class="sd"> relation](https://preserves.dev/preserves.html#equivalence)."""</span>
|
||||
<span class="k">return</span> <span class="n">_eq</span><span class="p">(</span><span class="n">preserve</span><span class="p">(</span><span class="n">a</span><span class="p">),</span> <span class="n">preserve</span><span class="p">(</span><span class="n">b</span><span class="p">))</span>
|
||||
</code></pre></div></td></tr></table></div>
|
||||
</details>
|
||||
|
|
@ -609,14 +635,17 @@
|
|||
|
||||
<div class="doc doc-contents ">
|
||||
|
||||
<p>TODO</p>
|
||||
<p>Returns <code>True</code> iff <code>a</code> ≤ <code>b</code> according to the <a href="https://preserves.dev/preserves.html#total-order">Preserves total
|
||||
order</a>.</p>
|
||||
|
||||
<details class="quote">
|
||||
<summary>Source code in <code>preserves/compare.py</code></summary>
|
||||
<div class="highlight"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span><span class="normal">62</span>
|
||||
<span class="normal">63</span>
|
||||
<span class="normal">64</span></pre></div></td><td class="code"><div><pre><span></span><code><span class="k">def</span> <span class="nf">le</span><span class="p">(</span><span class="n">a</span><span class="p">,</span> <span class="n">b</span><span class="p">):</span>
|
||||
<span class="w"> </span><span class="sd">"""TODO"""</span>
|
||||
<div class="highlight"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span><span class="normal">93</span>
|
||||
<span class="normal">94</span>
|
||||
<span class="normal">95</span>
|
||||
<span class="normal">96</span></pre></div></td><td class="code"><div><pre><span></span><code><span class="k">def</span> <span class="nf">le</span><span class="p">(</span><span class="n">a</span><span class="p">,</span> <span class="n">b</span><span class="p">):</span>
|
||||
<span class="w"> </span><span class="sd">"""Returns `True` iff `a` ≤ `b` according to the [Preserves total</span>
|
||||
<span class="sd"> order](https://preserves.dev/preserves.html#total-order)."""</span>
|
||||
<span class="k">return</span> <span class="n">cmp</span><span class="p">(</span><span class="n">a</span><span class="p">,</span> <span class="n">b</span><span class="p">)</span> <span class="o"><=</span> <span class="mi">0</span>
|
||||
</code></pre></div></td></tr></table></div>
|
||||
</details>
|
||||
|
|
@ -636,14 +665,17 @@
|
|||
|
||||
<div class="doc doc-contents ">
|
||||
|
||||
<p>TODO</p>
|
||||
<p>Returns <code>True</code> iff <code>a</code> < <code>b</code> according to the <a href="https://preserves.dev/preserves.html#total-order">Preserves total
|
||||
order</a>.</p>
|
||||
|
||||
<details class="quote">
|
||||
<summary>Source code in <code>preserves/compare.py</code></summary>
|
||||
<div class="highlight"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span><span class="normal">58</span>
|
||||
<span class="normal">59</span>
|
||||
<span class="normal">60</span></pre></div></td><td class="code"><div><pre><span></span><code><span class="k">def</span> <span class="nf">lt</span><span class="p">(</span><span class="n">a</span><span class="p">,</span> <span class="n">b</span><span class="p">):</span>
|
||||
<span class="w"> </span><span class="sd">"""TODO"""</span>
|
||||
<div class="highlight"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span><span class="normal">88</span>
|
||||
<span class="normal">89</span>
|
||||
<span class="normal">90</span>
|
||||
<span class="normal">91</span></pre></div></td><td class="code"><div><pre><span></span><code><span class="k">def</span> <span class="nf">lt</span><span class="p">(</span><span class="n">a</span><span class="p">,</span> <span class="n">b</span><span class="p">):</span>
|
||||
<span class="w"> </span><span class="sd">"""Returns `True` iff `a` < `b` according to the [Preserves total</span>
|
||||
<span class="sd"> order](https://preserves.dev/preserves.html#total-order)."""</span>
|
||||
<span class="k">return</span> <span class="n">cmp</span><span class="p">(</span><span class="n">a</span><span class="p">,</span> <span class="n">b</span><span class="p">)</span> <span class="o"><</span> <span class="mi">0</span>
|
||||
</code></pre></div></td></tr></table></div>
|
||||
</details>
|
||||
|
|
@ -663,14 +695,33 @@
|
|||
|
||||
<div class="doc doc-contents ">
|
||||
|
||||
<p>TODO</p>
|
||||
<p>Returns a sorted list built from <code>iterable</code>, extracting a sort key using <code>key</code>, and
|
||||
ordering according to the <a href="https://preserves.dev/preserves.html#total-order">Preserves total
|
||||
order</a>. Directly analogous to the
|
||||
<a href="https://docs.python.org/3/library/functions.html#sorted">built-in Python <code>sorted</code>
|
||||
routine</a>, except uses the
|
||||
Preserves order instead of Python's less-than relation.</p>
|
||||
|
||||
<details class="quote">
|
||||
<summary>Source code in <code>preserves/compare.py</code></summary>
|
||||
<div class="highlight"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span><span class="normal">74</span>
|
||||
<span class="normal">75</span>
|
||||
<span class="normal">76</span></pre></div></td><td class="code"><div><pre><span></span><code><span class="k">def</span> <span class="nf">sorted</span><span class="p">(</span><span class="n">iterable</span><span class="p">,</span> <span class="o">*</span><span class="p">,</span> <span class="n">key</span><span class="o">=</span><span class="k">lambda</span> <span class="n">x</span><span class="p">:</span> <span class="n">x</span><span class="p">,</span> <span class="n">reverse</span><span class="o">=</span><span class="kc">False</span><span class="p">):</span>
|
||||
<span class="w"> </span><span class="sd">"""TODO"""</span>
|
||||
<div class="highlight"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span><span class="normal">107</span>
|
||||
<span class="normal">108</span>
|
||||
<span class="normal">109</span>
|
||||
<span class="normal">110</span>
|
||||
<span class="normal">111</span>
|
||||
<span class="normal">112</span>
|
||||
<span class="normal">113</span>
|
||||
<span class="normal">114</span>
|
||||
<span class="normal">115</span>
|
||||
<span class="normal">116</span></pre></div></td><td class="code"><div><pre><span></span><code><span class="k">def</span> <span class="nf">sorted</span><span class="p">(</span><span class="n">iterable</span><span class="p">,</span> <span class="o">*</span><span class="p">,</span> <span class="n">key</span><span class="o">=</span><span class="k">lambda</span> <span class="n">x</span><span class="p">:</span> <span class="n">x</span><span class="p">,</span> <span class="n">reverse</span><span class="o">=</span><span class="kc">False</span><span class="p">):</span>
|
||||
<span class="w"> </span><span class="sd">"""Returns a sorted list built from `iterable`, extracting a sort key using `key`, and</span>
|
||||
<span class="sd"> ordering according to the [Preserves total</span>
|
||||
<span class="sd"> order](https://preserves.dev/preserves.html#total-order). Directly analogous to the</span>
|
||||
<span class="sd"> [built-in Python `sorted`</span>
|
||||
<span class="sd"> routine](https://docs.python.org/3/library/functions.html#sorted), except uses the</span>
|
||||
<span class="sd"> Preserves order instead of Python's less-than relation.</span>
|
||||
|
||||
<span class="sd"> """</span>
|
||||
<span class="k">return</span> <span class="n">_sorted</span><span class="p">(</span><span class="n">iterable</span><span class="p">,</span> <span class="n">key</span><span class="o">=</span><span class="k">lambda</span> <span class="n">x</span><span class="p">:</span> <span class="n">_key</span><span class="p">(</span><span class="n">key</span><span class="p">(</span><span class="n">x</span><span class="p">)),</span> <span class="n">reverse</span><span class="o">=</span><span class="n">reverse</span><span class="p">)</span>
|
||||
</code></pre></div></td></tr></table></div>
|
||||
</details>
|
||||
|
|
@ -690,14 +741,14 @@
|
|||
|
||||
<div class="doc doc-contents ">
|
||||
|
||||
<p>TODO</p>
|
||||
<p>Given a dictionary <code>d</code>, yields a list of <code>(key, value)</code> tuples sorted by <code>key</code>.</p>
|
||||
|
||||
<details class="quote">
|
||||
<summary>Source code in <code>preserves/compare.py</code></summary>
|
||||
<div class="highlight"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span><span class="normal">78</span>
|
||||
<span class="normal">79</span>
|
||||
<span class="normal">80</span></pre></div></td><td class="code"><div><pre><span></span><code><span class="k">def</span> <span class="nf">sorted_items</span><span class="p">(</span><span class="n">d</span><span class="p">):</span>
|
||||
<span class="w"> </span><span class="sd">"""TODO"""</span>
|
||||
<div class="highlight"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span><span class="normal">118</span>
|
||||
<span class="normal">119</span>
|
||||
<span class="normal">120</span></pre></div></td><td class="code"><div><pre><span></span><code><span class="k">def</span> <span class="nf">sorted_items</span><span class="p">(</span><span class="n">d</span><span class="p">):</span>
|
||||
<span class="w"> </span><span class="sd">"""Given a dictionary `d`, yields a list of `(key, value)` tuples sorted by `key`."""</span>
|
||||
<span class="k">return</span> <span class="nb">sorted</span><span class="p">(</span><span class="n">d</span><span class="o">.</span><span class="n">items</span><span class="p">(),</span> <span class="n">key</span><span class="o">=</span><span class="n">_item_key</span><span class="p">)</span>
|
||||
</code></pre></div></td></tr></table></div>
|
||||
</details>
|
||||
|
|
|
|||
File diff suppressed because one or more lines are too long
Loading…
Reference in New Issue