Merge pull request #58 from larsmans/order-statistic-doc

document use of sortedlist and sortedset as order statistic DSs

doc/sortedlist.rst

@@ -26,6 +26,10 @@ sortedlist
    *key* function must always return the same key for an item or the
    results are unpredictable.
 
+   A :class:`sortedlist` can be used as an order statistic tree
+   (Cormen *et al.*, *Introduction to Algorithms*, ch. 14)
+   that allows duplicate keys.
+
    .. method:: x in L
 
       Returns True if and only if *x* is an element in the list.
@@ -67,6 +71,8 @@ sortedlist
       |theta(1)| operations if the list's size has not been changed
       recently.  Requires no comparisons in any case.
 
+      (Cormen *et al.* call this operation "SELECT".)
+
       :rtype: item
 
    .. method:: L[i:j]
@@ -198,6 +204,8 @@ sortedlist
       In the worst case, requires |theta(log**2 m)| operations and
       |theta(log m)| comparisons, where *m* is *stop* - *start*.
 
+      (Cormen *et al.* call this operation "RANK".)
+
       :rtype: :class:`int`
 
    .. method:: L.pop([index])

doc/sortedset.rst

@@ -23,6 +23,9 @@ sortedset
    Unlike a :class:`set`, a :class:`sortedset` does not require items
    to be hashable.
 
+   A :class:`sortedset` can be used as an order statistic tree
+   (Cormen *et al.*, *Introduction to Algorithms*, ch. 14).
+
    .. method:: x in S
 
       Returns True if and only if *x* is an element in the set.
@@ -74,6 +77,8 @@ sortedset
       |theta(1)| operations if the set's size has not been changed
       recently.  Requires no comparisons in any case.
 
+      (Cormen *et al.* call this operation "SELECT".)
+
       :rtype: item
 
    .. method:: S[i:j]
@@ -224,6 +229,8 @@ sortedset
       In the worst case, requires |theta(log**2 m)| operations and
       |theta(log m)| comparisons, where *m* is *stop* - *start*.
 
+      (Cormen *et al.* call this operation "RANK".)
+
       :rtype: :class:`int`
 
    .. method:: S.intersection(S2, ...)