From bb7d68b3b92e68f0438f9fc335c54a415b5d92b1 Mon Sep 17 00:00:00 2001
From: Tom Ritchford <tom@swirly.com>
Date: Fri, 20 Mar 2015 13:25:27 -0400
Subject: [PATCH] Add notes about Rippled's container classes.

---
 src/ripple/basics/README.md | 37 ++++++++++++++++++++++++++++++++++++-
 1 file changed, 36 insertions(+), 1 deletion(-)

diff --git a/src/ripple/basics/README.md b/src/ripple/basics/README.md
index a19cbf5bf..544bc8aec 100644
--- a/src/ripple/basics/README.md
+++ b/src/ripple/basics/README.md
@@ -2,4 +2,39 @@
 
 Utility functions and classes.
 
-There should be no dependencies on business logic in other modules.
\ No newline at end of file
+ripple/basic should contain no dependencies on other modules.
+
+
+Choosing a rippled container.
+=============================
+
+* `std::vector`
+  * For ordered containers with most insertions or erases at the end.
+
+* `std::deque`
+  * For ordered containers with most insertions or erases at the start or end.
+
+* `std::list`
+  * For ordered containers with inserts and erases to the middle.
+  * For containers with iterators stable over insert and erase.
+  * Generally slower and bigger than `std::vector` or `std::deque` except for
+    those cases.
+
+* `std::set`
+  * For sorted containers.
+
+* `ripple::hash_set`
+  * Where inserts and contains need to be O(1).
+  * For "small" sets, `std::set` might be faster and smaller.
+
+* `ripple::hardened_hash_set`
+  * For data sets where the key could be manipulated by an attacker
+    in an attempt to mount an algorithmic complexity attack:  see
+    http://en.wikipedia.org/wiki/Algorithmic_complexity_attack
+
+
+The following container is deprecated
+
+* `std::unordered_set`
+ * Use `ripple::hash_set` instead, which uses a better hashing algorithm.
+ * Or use `ripple::hardened_hash_set` to prevent algorithmic complexity attacks.