Docs.

Author: mirek

Readme.md

@@ -1,9 +1,18 @@
 # Red-black tree module
 
-Based on:
+Red-black tree based on:
 - [Chris Okasaki. Red-black trees in a functional setting. J. Funct. Program., 9(4):471–477, 1999.](https://www.cs.tufts.edu/comp/150FP/archive/chris-okasaki/redblack99.pdf)
 - [Kimball Germane and Matthew Might (2014). "Deletion: The curse of the red-black tree." Journal of Functional Programming, 24(4), pp 423-433. July 2014.](https://matt.might.net/papers/germane2014deletion.pdf)
 
+Modifications include:
+1. keeping track of number elements to support multiset (aka. bag)
+2. keeping track of number of elements in children – to answer range queries on counts (ie. percentile on multiset)
+
+Keeping track of those counts doesn't increase complexity of operations.
+This is due to functional/immutable implementation.
+Updating counts doesn't require any traversal.
+Node creation has to keep sum of their immediate children, which is constant time operation.
+
 # Usage
 
 ```bash

prelude.ts

@@ -1,11 +1,22 @@
+/** Red. */
 export const R = 1
+
+/** Black. */
 export const B = 2
+
+/** Black-black. */
 export const BB = 3
 
+/** Color. */
 export type P = typeof R | typeof B | typeof BB
 
+/** Nil node. */
 export const E = undefined
+
+/** Black-black nil node. */
 export const EE = null
+
+/** Node. */
 export type N<T> = typeof E | typeof EE | {
   c: P,
   l: N<T>,
@@ -15,9 +26,13 @@ export type N<T> = typeof E | typeof EE | {
   s: number // n + l.s + r.s
 }
 
+/** Non nil node. */
 export type M<T> = NonNullable<N<T>>
+
+/** Node with explicit type for left and optionally right child. */
 export type O<T, L, R = N<T>> = { c: P, l: L, v: T, n: number, r: R, s: number }
 
+/** @returns node. */
 export const mk =
   <T>(c: P, l: N<T>, v: T, n: number, r: N<T>): M<T> => {
     const s = n + (l?.s ?? 0) + (r?.s ?? 0)

rb-tree.ts

@@ -21,10 +21,12 @@ export type RbTree<T, K> = {
 
 export type t<T, K> = RbTree<T, K>
 
+/** Range query. */
 export type Query<K> =
   | undefined
   | ({} | { $l: K } | { $le: K } & ({} | { $r: K } | { $re: K }))
 
+/** @returns Red-black tree based on element-to-key mapping function and comparision over keys function. */
 export const of =
   <T, K>(cmp: Cmp.t<K>, key: ((value: T) => K)): RbTree<T, K> => ({
     cmp,