Deploy d62ec23

codex-semantics-library · Apr 29, 2024 · 07c5991 · 07c5991
1 parent ea0a35e
commit 07c5991
Showing 1 changed file with 2 additions and 2 deletions.
diff --git a/main/index.html b/main/index.html
@@ -1,7 +1,7 @@
 <!DOCTYPE html>
 <html xmlns="http://www.w3.org/1999/xhtml"><head><title>index (patricia-tree.index)</title><meta charset="utf-8"/><link rel="stylesheet" href="../odoc.support/odoc.css"/><meta name="generator" content="odoc 2.4.1"/><meta name="viewport" content="width=device-width,initial-scale=1.0"/><script src="../odoc.support/highlight.pack.js"></script><script>hljs.initHighlightingOnLoad();</script><script>let base_url = '../';
 let search_urls = ['db.js','../sherlodoc.js'];
-</script><script src="../odoc.support/odoc_search.js" defer="defer"></script></head><body class="odoc"><nav class="odoc-nav"><a href="../index.html">Up</a> – patricia-tree</nav><div class="odoc-search"><div class="search-inner"><input class="search-bar" placeholder="🔎 Search..."/><div class="search-snake"></div><div class="search-result"></div></div></div><header class="odoc-preamble"><h1 id="package-patricia-tree"><a href="#package-patricia-tree" class="anchor"></a>Package patricia-tree</h1><p>This library contains a single module: <a href="PatriciaTree/index.html"><code>PatriciaTree</code></a>.</p><p>This is version <code>0.9.0</code> of the library. It is known to work with OCaml versions ranging from <code>4.14</code> to <code>5.2</code>.</p><p>This is an <a href="https://ocaml.org/">OCaml</a> library that implements sets and maps as Patricia Trees, as described in Okasaki and Gill's 1998 paper <a href="https://www.semanticscholar.org/paper/Fast-Mergeable-Integer-Maps-Okasaki-Gill/23003be706e5f586f23dd7fa5b2a410cc91b659d"><i>Fast mergeable integer maps</i></a>. It is a space-efficient prefix trie over the big-endian representation of the key's integer identifier.</p><p>The source code of this library is available <a href="https://github.com/codex-semantics-library/patricia-tree">on Github</a> under an <a href="https://choosealicense.com/licenses/lgpl-2.1/">LGPL-2.1</a> license.</p><p>This library was written by <a href="https://www.researchgate.net/profile/Matthieu-Lemerre">Matthieu Lemerre</a>, with some contributions by <a href="https://www.normalesup.org/~dlesbre/">Dorian Lesbre</a>, as part of the <a href="Codex semantics library">https://codex.top/</a>, developed at <a href="https://list.cea.fr/en/">CEA List</a>.</p></header><nav class="odoc-toc"><ul><li><a href="#installation">Installation</a></li><li><a href="#features">Features</a></li><li><a href="#quick-overview">Quick overview</a><ul><li><a href="#functors">Functors</a></li><li><a href="#interfaces">Interfaces</a></li></ul></li><li><a href="#examples">Examples</a><ul><li><a href="#homogeneous-map">Homogeneous map</a></li><li><a href="#heterogeneous-map">Heterogeneous map</a></li></ul></li><li><a href="#release-status">Release status</a></li><li><a href="#known-issues">Known issues</a></li><li><a href="#comparison-to-other-ocaml-libraries">Comparison to other OCaml libraries</a><ul><li><a href="#ptmap-and-ptset">ptmap and ptset</a></li><li><a href="#dmap">dmap</a></li></ul></li><li><a href="#contributions-and-bug-reports">Contributions and bug reports</a></li></ul></nav><div class="odoc-content"><h2 id="installation"><a href="#installation" class="anchor"></a>Installation</h2><p>This library can be installed with <a href="https://opam.ocaml.org/">opam</a>:</p><pre class="language-bash"><code>opam install patricia-tree</code></pre><p>Alternatively, you can clone the source repository and install with <a href="https://dune.build/">dune</a>:</p><pre class="language-bash"><code>git clone [email protected]:codex-semantics-library/patricia-tree.git
+</script><script src="../odoc.support/odoc_search.js" defer="defer"></script></head><body class="odoc"><nav class="odoc-nav"><a href="../index.html">Up</a> – patricia-tree</nav><div class="odoc-search"><div class="search-inner"><input class="search-bar" placeholder="🔎 Search..."/><div class="search-snake"></div><div class="search-result"></div></div></div><header class="odoc-preamble"><h1 id="package-patricia-tree"><a href="#package-patricia-tree" class="anchor"></a>Package patricia-tree</h1><p>This library contains a single module: <a href="PatriciaTree/index.html"><code>PatriciaTree</code></a>.</p><p>This is version <code>0.9.0</code> of the library. It is known to work with OCaml versions ranging from <code>4.14</code> to <code>5.2</code>.</p><p>This is an <a href="https://ocaml.org/">OCaml</a> library that implements sets and maps as Patricia Trees, as described in Okasaki and Gill's 1998 paper <a href="https://www.semanticscholar.org/paper/Fast-Mergeable-Integer-Maps-Okasaki-Gill/23003be706e5f586f23dd7fa5b2a410cc91b659d"><i>Fast mergeable integer maps</i></a>. It is a space-efficient prefix trie over the big-endian representation of the key's integer identifier.</p><p>The source code of this library is available <a href="https://github.com/codex-semantics-library/patricia-tree">on Github</a> under an <a href="https://choosealicense.com/licenses/lgpl-2.1/">LGPL-2.1</a> license.</p><p>This library was written by <a href="https://www.researchgate.net/profile/Matthieu-Lemerre">Matthieu Lemerre</a>, then further improved by <a href="https://www.normalesup.org/~dlesbre/">Dorian Lesbre</a>, as part of the <a href="Codex semantics library">https://codex.top/</a>, developed at <a href="https://list.cea.fr/en/">CEA List</a>.</p></header><nav class="odoc-toc"><ul><li><a href="#installation">Installation</a></li><li><a href="#features">Features</a></li><li><a href="#quick-overview">Quick overview</a><ul><li><a href="#functors">Functors</a></li><li><a href="#interfaces">Interfaces</a></li></ul></li><li><a href="#examples">Examples</a><ul><li><a href="#homogeneous-map">Homogeneous map</a></li><li><a href="#heterogeneous-map">Heterogeneous map</a></li></ul></li><li><a href="#release-status">Release status</a></li><li><a href="#known-issues">Known issues</a></li><li><a href="#comparison-to-other-ocaml-libraries">Comparison to other OCaml libraries</a><ul><li><a href="#ptmap-and-ptset">ptmap and ptset</a></li><li><a href="#dmap">dmap</a></li></ul></li><li><a href="#contributions-and-bug-reports">Contributions and bug reports</a></li></ul></nav><div class="odoc-content"><h2 id="installation"><a href="#installation" class="anchor"></a>Installation</h2><p>This library can be installed with <a href="https://opam.ocaml.org/">opam</a>:</p><pre class="language-bash"><code>opam install patricia-tree</code></pre><p>Alternatively, you can clone the source repository and install with <a href="https://dune.build/">dune</a>:</p><pre class="language-bash"><code>git clone [email protected]:codex-semantics-library/patricia-tree.git
 opam install . --deps-only
 cd patricia-tree
 dune build
@@ -107,4 +107,4 @@
   EMap.idempotent_inter_filter
     { f = fun _key _l _r -&gt; None } (* polymorphic 1rst order functions are wrapped in records *)
     (EMap.add (G_Const_Int 0) 8 map)
-    (EMap.add (G_Const_Int 0) 9 map)</code></pre><h2 id="release-status"><a href="#release-status" class="anchor"></a>Release status</h2><p>This should be close to a stable release. It is already being used as part of a larger project successfully, and this usage as helped us mature the interface. As is, we believe the project is usable, and we don't anticipate any major change before 1.0.0. We didn't commit to a stable release straight away as we would like a bit more time using this library before doing so.</p><h2 id="known-issues"><a href="#known-issues" class="anchor"></a>Known issues</h2><p>There is a bug in the OCaml typechecker which prevents us from directly defining non-generic maps as instances of generic maps. To avoid this, non-generic maps use a separate value type (instead of just using <code>'b</code>)</p><pre class="language-ocaml"><code>type (_, 'b) snd = Snd of 'b [@@unboxed]</code></pre><p>It should not incur any extra performance cost as it is unboxed, but can appear when manipulating non-generic maps.</p><p>For more details about this issue, see <a href="https://discuss.ocaml.org/t/weird-behaviors-with-first-order-polymorphism/13783">the OCaml discourse discussion</a>.</p><h2 id="comparison-to-other-ocaml-libraries"><a href="#comparison-to-other-ocaml-libraries" class="anchor"></a>Comparison to other OCaml libraries</h2><h3 id="ptmap-and-ptset"><a href="#ptmap-and-ptset" class="anchor"></a>ptmap and ptset</h3><p>There are other implementations of Patricia Tree in OCaml, namely <a href="https://github.com/backtracking/ptmap">ptmap</a> and <a href="https://github.com/backtracking/ptset">ptset</a>, both by J.C. Filliatre. These are smaller and closer to OCaml's built-in <code>Map</code> and <code>Set</code>, however:</p><ul><li>Our library allows using any type <code>key</code> that comes with an injective <code>to_int</code> function, instead of requiring <code>key = int</code>.</li><li>We support generic types for keys/elements.</li><li>We support operations between sets and maps of different types.</li><li>We use a big-endian representation, allowing easy access to min/max elements of maps and trees.</li><li>Our interface and implementation tries to maximize the sharing between different versions of the tree, and to benefit from this memory sharing. Theirs do not.</li><li>These libraries work with older version of OCaml (<code>&gt;= 4.05</code> I believe), whereas ours requires OCaml <code>&gt;= 4.14</code> (for the new interface of <code>Ephemeron</code> used in <a href="PatriciaTree/WeakNode/index.html"><code>PatriciaTree.WeakNode</code></a>).</li><li>Our keys are limited to positive integers.</li></ul><h3 id="dmap"><a href="#dmap" class="anchor"></a>dmap</h3><p>Additionally, there is a dependent map library: <a href="https://gitlab.inria.fr/bmontagu/dmap">dmap</a>. It allows creating type safe dependent maps similar to our heterogeneous maps. However, its maps aren't Patricia trees. They are binary trees build using a (polymorphic) comparison function, similarly to the maps of the standard library.</p><p>Another difference is that the type of values in the map is independent from the type of the keys, allowing keys to be associated with different values in different maps. i.e. we map <code>'a key</code> to any <code>('a, 'b) value</code> type, whereas dmap only maps <code>'a key</code> to <code>'a</code> or <code>'a value</code>.</p><p><code>dmap</code> also works with OCaml <code>&gt;= 4.12</code>, whereas we require OCaml <code>&gt;= 4.14</code>.</p><h2 id="contributions-and-bug-reports"><a href="#contributions-and-bug-reports" class="anchor"></a>Contributions and bug reports</h2><p>Any contributions are welcome!</p><p>You can report any bug, issues, or desired features using the <a href="https://github.com/codex-semantics-library/patricia-tree/issues">Github issue tracker</a>. Please include OCaml, dune, and library version information in you bug reports.</p><p>If you want to contribute code, feel free to fork <a href="https://github.com/codex-semantics-library/patricia-tree">the repository on Github</a> and open a pull request. By doing so you agree to release your code under this project's license (<a href="https://choosealicense.com/licenses/lgpl-2.1/">LGPL-2.1</a>).</p><p>There is no imposed coding style for this repository, here are just a few guidelines and conventions:</p><ul><li>Module type names should use <code>SCREAMING_SNAKE_CASE</code>.</li><li>Module and functor names use <code>PascalCase</code>, functors names start with <code>Make</code>.</li><li>Even though the library implements homogeneous maps as a specialization of heterogeneous ones, the naming convention is that no prefix means homogeneous, and all heterogeneous objects are prefixed with <code>heterogeneous</code>.</li><li>Please document any new functions in the interface, using <a href="https://v2.ocaml.org/manual/ocamldoc.html#s%3Aocamldoc-comments">ocamldoc style comments</a>.</li><li>Please consider adding test for new features/fixed bugs if at all possible. This library uses a <a href="https://www.ocaml.org/p/quickcheck/latest/doc/QuickCheck/index.html">QuickCheck</a> framework for tests.</li></ul></div></body></html>
+    (EMap.add (G_Const_Int 0) 9 map)</code></pre><h2 id="release-status"><a href="#release-status" class="anchor"></a>Release status</h2><p>This should be close to a stable release. It is already being used as part of a larger project successfully, and this usage as helped us mature the interface. As is, we believe the project is usable, and we don't anticipate any major change before 1.0.0. We didn't commit to a stable release straight away as we would like a bit more time using this library before doing so.</p><h2 id="known-issues"><a href="#known-issues" class="anchor"></a>Known issues</h2><p>There is a bug in the OCaml typechecker which prevents us from directly defining non-generic maps as instances of generic maps. To avoid this, non-generic maps use a separate value type (instead of just using <code>'b</code>)</p><pre class="language-ocaml"><code>type (_, 'b) snd = Snd of 'b [@@unboxed]</code></pre><p>It should not incur any extra performance cost as it is unboxed, but can appear when manipulating non-generic maps.</p><p>For more details about this issue, see <a href="https://discuss.ocaml.org/t/weird-behaviors-with-first-order-polymorphism/13783">the OCaml discourse discussion</a>.</p><h2 id="comparison-to-other-ocaml-libraries"><a href="#comparison-to-other-ocaml-libraries" class="anchor"></a>Comparison to other OCaml libraries</h2><h3 id="ptmap-and-ptset"><a href="#ptmap-and-ptset" class="anchor"></a>ptmap and ptset</h3><p>There are other implementations of Patricia Tree in OCaml, namely <a href="https://github.com/backtracking/ptmap">ptmap</a> and <a href="https://github.com/backtracking/ptset">ptset</a>, both by J.C. Filliatre. These are smaller and closer to OCaml's built-in <code>Map</code> and <code>Set</code>, however:</p><ul><li>Our library allows using any type <code>key</code> that comes with an injective <code>to_int</code> function, instead of requiring <code>key = int</code>.</li><li>We support generic types for keys/elements.</li><li>We support operations between sets and maps of different types.</li><li>We use a big-endian representation, allowing easy access to min/max elements of maps and trees.</li><li>Our interface and implementation tries to maximize the sharing between different versions of the tree, and to benefit from this memory sharing. Theirs do not.</li><li>These libraries work with older version of OCaml (<code>&gt;= 4.05</code> I believe), whereas ours requires OCaml <code>&gt;= 4.14</code> (for the new interface of <code>Ephemeron</code> used in <a href="PatriciaTree/WeakNode/index.html"><code>PatriciaTree.WeakNode</code></a>).</li><li>Our keys are limited to positive integers.</li></ul><h3 id="dmap"><a href="#dmap" class="anchor"></a>dmap</h3><p>Additionally, there is a dependent map library: <a href="https://gitlab.inria.fr/bmontagu/dmap">dmap</a>, which gave us the idea of making our PatriciaTree dependent. It allows creating type safe dependent maps similar to our heterogeneous maps. However, its maps aren't Patricia trees. They are binary trees build using a (polymorphic) comparison function, similarly to the maps of the standard library.</p><p>Another difference is that the type of values in the map is independent from the type of the keys, allowing keys to be associated with different values in different maps. i.e. we map <code>'a key</code> to any <code>('a, 'b) value</code> type, whereas dmap only maps <code>'a key</code> to <code>'a</code> or <code>'a value</code>.</p><p><code>dmap</code> also works with OCaml <code>&gt;= 4.12</code>, whereas we require OCaml <code>&gt;= 4.14</code>.</p><h2 id="contributions-and-bug-reports"><a href="#contributions-and-bug-reports" class="anchor"></a>Contributions and bug reports</h2><p>Any contributions are welcome!</p><p>You can report any bug, issues, or desired features using the <a href="https://github.com/codex-semantics-library/patricia-tree/issues">Github issue tracker</a>. Please include OCaml, dune, and library version information in you bug reports.</p><p>If you want to contribute code, feel free to fork <a href="https://github.com/codex-semantics-library/patricia-tree">the repository on Github</a> and open a pull request. By doing so you agree to release your code under this project's license (<a href="https://choosealicense.com/licenses/lgpl-2.1/">LGPL-2.1</a>).</p><p>There is no imposed coding style for this repository, here are just a few guidelines and conventions:</p><ul><li>Module type names should use <code>SCREAMING_SNAKE_CASE</code>.</li><li>Module and functor names use <code>PascalCase</code>, functors names start with <code>Make</code>.</li><li>Even though the library implements homogeneous maps as a specialization of heterogeneous ones, the naming convention is that no prefix means homogeneous, and all heterogeneous objects are prefixed with <code>heterogeneous</code>.</li><li>Please document any new functions in the interface, using <a href="https://v2.ocaml.org/manual/ocamldoc.html#s%3Aocamldoc-comments">ocamldoc style comments</a>.</li><li>Please consider adding test for new features/fixed bugs if at all possible. This library uses a <a href="https://www.ocaml.org/p/quickcheck/latest/doc/QuickCheck/index.html">QuickCheck</a> framework for tests.</li></ul></div></body></html>