<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml" lang="" xml:lang="">
<head>
<meta charset="utf-8" />
<meta name="generator" content="pandoc" />
<meta name="viewport" content="width=device-width, initial-scale=1.0, user-scalable=yes" />
<title>README</title>
<style>
html {
line-height: 1.5;
font-family: Georgia, serif;
font-size: 20px;
color: #1a1a1a;
background-color: #fdfdfd;
}
body {
margin: 0 auto;
max-width: 36em;
padding-left: 50px;
padding-right: 50px;
padding-top: 50px;
padding-bottom: 50px;
hyphens: auto;
overflow-wrap: break-word;
text-rendering: optimizeLegibility;
font-kerning: normal;
}
@media (max-width: 600px) {
body {
font-size: 0.9em;
padding: 1em;
}
h1 {
font-size: 1.8em;
}
}
@media print {
body {
background-color: transparent;
color: black;
font-size: 12pt;
}
p, h2, h3 {
orphans: 3;
widows: 3;
}
h2, h3, h4 {
page-break-after: avoid;
}
}
p {
margin: 1em 0;
}
a {
color: #1a1a1a;
}
a:visited {
color: #1a1a1a;
}
img {
max-width: 100%;
}
h1, h2, h3, h4, h5, h6 {
margin-top: 1.4em;
}
h5, h6 {
font-size: 1em;
font-style: italic;
}
h6 {
font-weight: normal;
}
ol, ul {
padding-left: 1.7em;
margin-top: 1em;
}
li > ol, li > ul {
margin-top: 0;
}
blockquote {
margin: 1em 0 1em 1.7em;
padding-left: 1em;
border-left: 2px solid #e6e6e6;
color: #606060;
}
code {
font-family: Menlo, Monaco, 'Lucida Console', Consolas, monospace;
font-size: 85%;
margin: 0;
}
pre {
margin: 1em 0;
overflow: auto;
}
pre code {
padding: 0;
overflow: visible;
overflow-wrap: normal;
}
.sourceCode {
background-color: transparent;
overflow: visible;
}
hr {
background-color: #1a1a1a;
border: none;
height: 1px;
margin: 1em 0;
}
table {
margin: 1em 0;
border-collapse: collapse;
width: 100%;
overflow-x: auto;
display: block;
font-variant-numeric: lining-nums tabular-nums;
}
table caption {
margin-bottom: 0.75em;
}
tbody {
margin-top: 0.5em;
border-top: 1px solid #1a1a1a;
border-bottom: 1px solid #1a1a1a;
}
th {
border-top: 1px solid #1a1a1a;
padding: 0.25em 0.5em 0.25em 0.5em;
}
td {
padding: 0.125em 0.5em 0.25em 0.5em;
}
header {
margin-bottom: 4em;
text-align: center;
}
#TOC li {
list-style: none;
}
#TOC ul {
padding-left: 1.3em;
}
#TOC > ul {
padding-left: 0;
}
#TOC a:not(:hover) {
text-decoration: none;
}
code{white-space: pre-wrap;}
span.smallcaps{font-variant: small-caps;}
span.underline{text-decoration: underline;}
div.column{display: inline-block; vertical-align: top; width: 50%;}
div.hanging-indent{margin-left: 1.5em; text-indent: -1.5em;}
ul.task-list{list-style: none;}
pre > code.sourceCode { white-space: pre; position: relative; }
pre > code.sourceCode > span { display: inline-block; line-height: 1.25; }
pre > code.sourceCode > span:empty { height: 1.2em; }
.sourceCode { overflow: visible; }
code.sourceCode > span { color: inherit; text-decoration: inherit; }
div.sourceCode { margin: 1em 0; }
pre.sourceCode { margin: 0; }
@media screen {
div.sourceCode { overflow: auto; }
}
@media print {
pre > code.sourceCode { white-space: pre-wrap; }
pre > code.sourceCode > span { text-indent: -5em; padding-left: 5em; }
}
pre.numberSource code
{ counter-reset: source-line 0; }
pre.numberSource code > span
{ position: relative; left: -4em; counter-increment: source-line; }
pre.numberSource code > span > a:first-child::before
{ content: counter(source-line);
position: relative; left: -1em; text-align: right; vertical-align: baseline;
border: none; display: inline-block;
-webkit-touch-callout: none; -webkit-user-select: none;
-khtml-user-select: none; -moz-user-select: none;
-ms-user-select: none; user-select: none;
padding: 0 4px; width: 4em;
color: #aaaaaa;
}
pre.numberSource { margin-left: 3em; border-left: 1px solid #aaaaaa; padding-left: 4px; }
div.sourceCode
{ }
@media screen {
pre > code.sourceCode > span > a:first-child::before { text-decoration: underline; }
}
code span.al { color: #ff0000; font-weight: bold; } /* Alert */
code span.an { color: #60a0b0; font-weight: bold; font-style: italic; } /* Annotation */
code span.at { color: #7d9029; } /* Attribute */
code span.bn { color: #40a070; } /* BaseN */
code span.bu { color: #008000; } /* BuiltIn */
code span.cf { color: #007020; font-weight: bold; } /* ControlFlow */
code span.ch { color: #4070a0; } /* Char */
code span.cn { color: #880000; } /* Constant */
code span.co { color: #60a0b0; font-style: italic; } /* Comment */
code span.cv { color: #60a0b0; font-weight: bold; font-style: italic; } /* CommentVar */
code span.do { color: #ba2121; font-style: italic; } /* Documentation */
code span.dt { color: #902000; } /* DataType */
code span.dv { color: #40a070; } /* DecVal */
code span.er { color: #ff0000; font-weight: bold; } /* Error */
code span.ex { } /* Extension */
code span.fl { color: #40a070; } /* Float */
code span.fu { color: #06287e; } /* Function */
code span.im { color: #008000; font-weight: bold; } /* Import */
code span.in { color: #60a0b0; font-weight: bold; font-style: italic; } /* Information */
code span.kw { color: #007020; font-weight: bold; } /* Keyword */
code span.op { color: #666666; } /* Operator */
code span.ot { color: #007020; } /* Other */
code span.pp { color: #bc7a00; } /* Preprocessor */
code span.sc { color: #4070a0; } /* SpecialChar */
code span.ss { color: #bb6688; } /* SpecialString */
code span.st { color: #4070a0; } /* String */
code span.va { color: #19177c; } /* Variable */
code span.vs { color: #4070a0; } /* VerbatimString */
code span.wa { color: #60a0b0; font-weight: bold; font-style: italic; } /* Warning */
.display.math{display: block; text-align: center; margin: 0.5rem auto;}
</style>
</head>
<body>
<h1 id="functional-red-black-tree">functional-red-black-tree</h1>
<p>A <a
href="http://en.wikipedia.org/wiki/Persistent_data_structure">fully
persistent</a> <a
href="http://en.wikipedia.org/wiki/Red%E2%80%93black_tree">red-black
tree</a> written 100% in JavaScript. Works both in node.js and in the
browser via <a href="http://browserify.org/">browserify</a>.</p>
<p>Functional (or fully persistent) data structures allow for
non-destructive updates. So if you insert an element into the tree, it
returns a new tree with the inserted element rather than destructively
updating the existing tree in place. Doing this requires using extra
memory, and if one were naive it could cost as much as reallocating the
entire tree. Instead, this data structure saves some memory by recycling
references to previously allocated subtrees. This requires using only
O(log(n)) additional memory per update instead of a full O(n) copy.</p>
<p>Some advantages of this is that it is possible to apply insertions
and removals to the tree while still iterating over previous versions of
the tree. Functional and persistent data structures can also be useful
in many geometric algorithms like point location within triangulations
or ray queries, and can be used to analyze the history of executing
various algorithms. This added power though comes at a cost, since it is
generally a bit slower to use a functional data structure than an
imperative version. However, if your application needs this behavior
then you may consider using this module.</p>
<h1 id="install">Install</h1>
<pre><code>npm install functional-red-black-tree</code></pre>
<h1 id="example">Example</h1>
<p>Here is an example of some basic usage:</p>
<div class="sourceCode" id="cb2"><pre
class="sourceCode javascript"><code class="sourceCode javascript"><span id="cb2-1"><a href="#cb2-1" aria-hidden="true" tabindex="-1"></a><span class="co">//Load the library</span></span>
<span id="cb2-2"><a href="#cb2-2" aria-hidden="true" tabindex="-1"></a><span class="kw">var</span> createTree <span class="op">=</span> <span class="pp">require</span>(<span class="st">"functional-red-black-tree"</span>)</span>
<span id="cb2-3"><a href="#cb2-3" aria-hidden="true" tabindex="-1"></a></span>
<span id="cb2-4"><a href="#cb2-4" aria-hidden="true" tabindex="-1"></a><span class="co">//Create a tree</span></span>
<span id="cb2-5"><a href="#cb2-5" aria-hidden="true" tabindex="-1"></a><span class="kw">var</span> t1 <span class="op">=</span> <span class="fu">createTree</span>()</span>
<span id="cb2-6"><a href="#cb2-6" aria-hidden="true" tabindex="-1"></a></span>
<span id="cb2-7"><a href="#cb2-7" aria-hidden="true" tabindex="-1"></a><span class="co">//Insert some items into the tree</span></span>
<span id="cb2-8"><a href="#cb2-8" aria-hidden="true" tabindex="-1"></a><span class="kw">var</span> t2 <span class="op">=</span> t1<span class="op">.</span><span class="fu">insert</span>(<span class="dv">1</span><span class="op">,</span> <span class="st">"foo"</span>)</span>
<span id="cb2-9"><a href="#cb2-9" aria-hidden="true" tabindex="-1"></a><span class="kw">var</span> t3 <span class="op">=</span> t2<span class="op">.</span><span class="fu">insert</span>(<span class="dv">2</span><span class="op">,</span> <span class="st">"bar"</span>)</span>
<span id="cb2-10"><a href="#cb2-10" aria-hidden="true" tabindex="-1"></a></span>
<span id="cb2-11"><a href="#cb2-11" aria-hidden="true" tabindex="-1"></a><span class="co">//Remove something</span></span>
<span id="cb2-12"><a href="#cb2-12" aria-hidden="true" tabindex="-1"></a><span class="kw">var</span> t4 <span class="op">=</span> t3<span class="op">.</span><span class="fu">remove</span>(<span class="dv">1</span>)</span></code></pre></div>
<h1 id="api">API</h1>
<div class="sourceCode" id="cb3"><pre
class="sourceCode javascript"><code class="sourceCode javascript"><span id="cb3-1"><a href="#cb3-1" aria-hidden="true" tabindex="-1"></a><span class="kw">var</span> createTree <span class="op">=</span> <span class="pp">require</span>(<span class="st">"functional-red-black-tree"</span>)</span></code></pre></div>
<h2 id="overview">Overview</h2>
<ul>
<li><a href="#tree-methods">Tree methods</a>
<ul>
<li><a
href="#var-tree-=-createtreecompare"><code>var tree = createTree([compare])</code></a></li>
<li><a href="#treekeys"><code>tree.keys</code></a></li>
<li><a href="#treevalues"><code>tree.values</code></a></li>
<li><a href="#treelength"><code>tree.length</code></a></li>
<li><a href="#treegetkey"><code>tree.get(key)</code></a></li>
<li><a
href="#treeinsertkey-value"><code>tree.insert(key, value)</code></a></li>
<li><a href="#treeremovekey"><code>tree.remove(key)</code></a></li>
<li><a href="#treefindkey"><code>tree.find(key)</code></a></li>
<li><a href="#treegekey"><code>tree.ge(key)</code></a></li>
<li><a href="#treegtkey"><code>tree.gt(key)</code></a></li>
<li><a href="#treeltkey"><code>tree.lt(key)</code></a></li>
<li><a href="#treelekey"><code>tree.le(key)</code></a></li>
<li><a href="#treeatposition"><code>tree.at(position)</code></a></li>
<li><a href="#treebegin"><code>tree.begin</code></a></li>
<li><a href="#treeend"><code>tree.end</code></a></li>
<li><a
href="#treeforEachvisitorkeyvalue-lo-hi"><code>tree.forEach(visitor(key,value)[, lo[, hi]])</code></a></li>
<li><a href="#treeroot"><code>tree.root</code></a></li>
</ul></li>
<li><a href="#node-properties">Node properties</a>
<ul>
<li><a href="#nodekey"><code>node.key</code></a></li>
<li><a href="#nodevalue"><code>node.value</code></a></li>
<li><a href="#nodeleft"><code>node.left</code></a></li>
<li><a href="#noderight"><code>node.right</code></a></li>
</ul></li>
<li><a href="#iterator-methods">Iterator methods</a>
<ul>
<li><a href="#iterkey"><code>iter.key</code></a></li>
<li><a href="#itervalue"><code>iter.value</code></a></li>
<li><a href="#iternode"><code>iter.node</code></a></li>
<li><a href="#itertree"><code>iter.tree</code></a></li>
<li><a href="#iterindex"><code>iter.index</code></a></li>
<li><a href="#itervalid"><code>iter.valid</code></a></li>
<li><a href="#iterclone"><code>iter.clone()</code></a></li>
<li><a href="#iterremove"><code>iter.remove()</code></a></li>
<li><a href="#iterupdatevalue"><code>iter.update(value)</code></a></li>
<li><a href="#iternext"><code>iter.next()</code></a></li>
<li><a href="#iterprev"><code>iter.prev()</code></a></li>
<li><a href="#iterhasnext"><code>iter.hasNext</code></a></li>
<li><a href="#iterhasprev"><code>iter.hasPrev</code></a></li>
</ul></li>
</ul>
<h2 id="tree-methods">Tree methods</h2>
<h3
id="var-tree--createtreecompare"><code>var tree = createTree([compare])</code></h3>
<p>Creates an empty functional tree</p>
<ul>
<li><code>compare</code> is an optional comparison function, same
semantics as array.sort()</li>
</ul>
<p><strong>Returns</strong> An empty tree ordered by
<code>compare</code></p>
<h3 id="treekeys"><code>tree.keys</code></h3>
<p>A sorted array of all the keys in the tree</p>
<h3 id="treevalues"><code>tree.values</code></h3>
<p>An array array of all the values in the tree</p>
<h3 id="treelength"><code>tree.length</code></h3>
<p>The number of items in the tree</p>
<h3 id="treegetkey"><code>tree.get(key)</code></h3>
<p>Retrieves the value associated to the given key</p>
<ul>
<li><code>key</code> is the key of the item to look up</li>
</ul>
<p><strong>Returns</strong> The value of the first node associated to
<code>key</code></p>
<h3 id="treeinsertkey-value"><code>tree.insert(key, value)</code></h3>
<p>Creates a new tree with the new pair inserted.</p>
<ul>
<li><code>key</code> is the key of the item to insert</li>
<li><code>value</code> is the value of the item to insert</li>
</ul>
<p><strong>Returns</strong> A new tree with <code>key</code> and
<code>value</code> inserted</p>
<h3 id="treeremovekey"><code>tree.remove(key)</code></h3>
<p>Removes the first item with <code>key</code> in the tree</p>
<ul>
<li><code>key</code> is the key of the item to remove</li>
</ul>
<p><strong>Returns</strong> A new tree with the given item removed if it
exists</p>
<h3 id="treefindkey"><code>tree.find(key)</code></h3>
<p>Returns an iterator pointing to the first item in the tree with
<code>key</code>, otherwise <code>null</code>.</p>
<h3 id="treegekey"><code>tree.ge(key)</code></h3>
<p>Find the first item in the tree whose key is
<code>>= key</code></p>
<ul>
<li><code>key</code> is the key to search for</li>
</ul>
<p><strong>Returns</strong> An iterator at the given element.</p>
<h3 id="treegtkey"><code>tree.gt(key)</code></h3>
<p>Finds the first item in the tree whose key is
<code>> key</code></p>
<ul>
<li><code>key</code> is the key to search for</li>
</ul>
<p><strong>Returns</strong> An iterator at the given element</p>
<h3 id="treeltkey"><code>tree.lt(key)</code></h3>
<p>Finds the last item in the tree whose key is
<code>< key</code></p>
<ul>
<li><code>key</code> is the key to search for</li>
</ul>
<p><strong>Returns</strong> An iterator at the given element</p>
<h3 id="treelekey"><code>tree.le(key)</code></h3>
<p>Finds the last item in the tree whose key is
<code><= key</code></p>
<ul>
<li><code>key</code> is the key to search for</li>
</ul>
<p><strong>Returns</strong> An iterator at the given element</p>
<h3 id="treeatposition"><code>tree.at(position)</code></h3>
<p>Finds an iterator starting at the given element</p>
<ul>
<li><code>position</code> is the index at which the iterator gets
created</li>
</ul>
<p><strong>Returns</strong> An iterator starting at position</p>
<h3 id="treebegin"><code>tree.begin</code></h3>
<p>An iterator pointing to the first element in the tree</p>
<h3 id="treeend"><code>tree.end</code></h3>
<p>An iterator pointing to the last element in the tree</p>
<h3
id="treeforeachvisitorkeyvalue-lo-hi"><code>tree.forEach(visitor(key,value)[, lo[, hi]])</code></h3>
<p>Walks a visitor function over the nodes of the tree in order.</p>
<ul>
<li><code>visitor(key,value)</code> is a callback that gets executed on
each node. If a truthy value is returned from the visitor, then
iteration is stopped.</li>
<li><code>lo</code> is an optional start of the range to visit
(inclusive)</li>
<li><code>hi</code> is an optional end of the range to visit
(non-inclusive)</li>
</ul>
<p><strong>Returns</strong> The last value returned by the callback</p>
<h3 id="treeroot"><code>tree.root</code></h3>
<p>Returns the root node of the tree</p>
<h2 id="node-properties">Node properties</h2>
<p>Each node of the tree has the following properties:</p>
<h3 id="nodekey"><code>node.key</code></h3>
<p>The key associated to the node</p>
<h3 id="nodevalue"><code>node.value</code></h3>
<p>The value associated to the node</p>
<h3 id="nodeleft"><code>node.left</code></h3>
<p>The left subtree of the node</p>
<h3 id="noderight"><code>node.right</code></h3>
<p>The right subtree of the node</p>
<h2 id="iterator-methods">Iterator methods</h2>
<h3 id="iterkey"><code>iter.key</code></h3>
<p>The key of the item referenced by the iterator</p>
<h3 id="itervalue"><code>iter.value</code></h3>
<p>The value of the item referenced by the iterator</p>
<h3 id="iternode"><code>iter.node</code></h3>
<p>The value of the node at the iterator's current position.
<code>null</code> is iterator is node valid.</p>
<h3 id="itertree"><code>iter.tree</code></h3>
<p>The tree associated to the iterator</p>
<h3 id="iterindex"><code>iter.index</code></h3>
<p>Returns the position of this iterator in the sequence.</p>
<h3 id="itervalid"><code>iter.valid</code></h3>
<p>Checks if the iterator is valid</p>
<h3 id="iterclone"><code>iter.clone()</code></h3>
<p>Makes a copy of the iterator</p>
<h3 id="iterremove"><code>iter.remove()</code></h3>
<p>Removes the item at the position of the iterator</p>
<p><strong>Returns</strong> A new binary search tree with
<code>iter</code>'s item removed</p>
<h3 id="iterupdatevalue"><code>iter.update(value)</code></h3>
<p>Updates the value of the node in the tree at this iterator</p>
<p><strong>Returns</strong> A new binary search tree with the
corresponding node updated</p>
<h3 id="iternext"><code>iter.next()</code></h3>
<p>Advances the iterator to the next position</p>
<h3 id="iterprev"><code>iter.prev()</code></h3>
<p>Moves the iterator backward one element</p>
<h3 id="iterhasnext"><code>iter.hasNext</code></h3>
<p>If true, then the iterator is not at the end of the sequence</p>
<h3 id="iterhasprev"><code>iter.hasPrev</code></h3>
<p>If true, then the iterator is not at the beginning of the
sequence</p>
<h1 id="credits">Credits</h1>
<p>(c) 2013 Mikola Lysenko. MIT License</p>
</body>
</html>
|