new: #'uuid/v1 now 10x as fast as java.util.UUID

README.md

@@ -200,11 +200,22 @@ Execution time mean : 2.012861 µs
 
 V4 identifiers are generated by directly invoking the static method
 `#'java.util.UUID/randomUUID` and are, in typical situations, slower
-to generate in addition to being non-deterministically unique.
+to generate in addition to being non-deterministically unique.  It
+exists primarily because it is very simple to implement.
 
 
 #### Namespaced (v3/v5) Identifiers
 
+First of all, the only difference between v3 and v5 UUID's is that v3's
+are computed using an MD5 digest algorithm and v5's are computed using SHA1.
+It is generally considered that SHA1 is a superior hash, but MD5 is
+computationally less expensive and so v3 may be preferred in
+situations requiring slightly faster performance. As such, when we give
+examples of namespaced identifiers, we will typically just use `v5` with
+the understanding that `v3` could be used identically in each instance.
+
+##### Namespaces
+
 If you are familiar with Clojure _vars_, you already understand the
 idea of _namespaced_ identifiers.  To resolve the value of a var, one
 needs to know not only the _name_ of a var, but also the _namespace_
@@ -250,12 +261,6 @@ user> (uuid/v5 uuid/+namespace-url+ "I am clearly not a URL")
 ;;  => #uuid "a167a791-e550-57ae-b20f-666ee47ce7c1"
 ```
 
-The only difference between v3 and v5 UUID's is that v3's are computed
-using an MD5 digest algorithm and v5's are computed using SHA1.  It is
-generally considered that SHA1 is a superior hash, but MD5 is
-computationally less expensive and so v3 may be preferred in
-situations requiring slightly faster performance.
-
 As a matter of fact, the requirements for a valid the local-part
 constituent are even more general than even just Strings.  Any kind of
 object will do:
@@ -406,8 +411,46 @@ user> (-> uuid/+namespace-dns+
 This capability can be used to represent uniqueness of a sequence of
 computations in, for example, a transaction system such as the one
 used in the graph-object database system
-[de.setf.resource](http://github.com/lisp/de.setf.resource/). 
+[de.setf.resource](http://github.com/lisp/de.setf.resource/) or the
+[CQRS/ES (Command Query Responsibility Segregation / Event Sourcing) Server](http://yuppiechef.github.io/cqrs-server/). 
+
+### A Simple Example
+
+Ok, so now you know how to use this nifty new UUID library and your are
+burning up to do somthing awesome with UUID's... But, ah, hmmm... First
+you need to figure out what exactly you want to do with them.  Well,
+before you start working on your distributed cloud-based secret
+weapon, here is a simple way you can generate cryptographically
+secure activation keys for your draconian licensing scheme.
+
+First, we pick a secret key.  We might pick a time-based id, or we might
+begin with some secret namespace, secret identifier pair to compute that
+initial namespace deterministically.  This is convenient, but not necessary
+-- the time-based or random private key could also be stored in some form
+of persistent memory.
+
+```clojure
+
+user> (def +secret-weapon-licensing-namespace+ (uuid/v1))
+
+
+user> (uuid/v5 +secret-weapon-licensing-namespace+ "joe@example.com")
+
+;;  => #uuid "b6433d1e-d369-5282-8dbc-bdd3845c376c"
+
+
+user> (uuid/v5 +secret-weapon-licensing-namespace+ "mom@knitting-arts.edu")
+
+;;  => #uuid "81e4708c-85bb-5f3c-be56-bba4d8b0ac91"
+
+```
 
+Now, as the orders start rolling in for your product, you can crank out
+secret weapon activation codes just as well as if you were Microsoft.
+Each one will be keyed to a user's email address and is guaranteed
+to be irreversible.  You will infuriate them with unreasonably high
+maintence support contract fees and intractible licensing terms.
+You truly are diabolical.
 
 
 ### Basic API