UUID Library

This is a simple library to work with UUID values. The library primarily uses the Leach-Salz variant of UUIDs, but can represent all kinds of UUIDs.

Documentation

Types

• Type uuid

  Represents an UUID value. Basically, a 128 bit number (more or less) with added structure.

• Function uuidp object → boolean

  Tests, whether object is a value of type uuid. This is equivalent with (typep object 'uuid).

Comparing and Hashing

Values of type UUID can be compared for equality as well as order. The ordering on UUIDs is total, i.e., every two UUID instances v1 and v2 can be compared, and exactly one of

• uuid< v1 v2
• uuid= v1 v2
• uuid> v1 v2

will answer true. The ordering carefully reflects the lexicographic ordering of the string representations of UUIDs, i.e., it is always the case that

• (uuidXX v1 v2) if (and only if) (stringXX (uuid-string v1) (uuid-string v2))

where XX is one of <, <=, =, >=, >, /=. Note, that the actual implementation of the predicates is more efficient than that.

The hash function can be used in Common Lisp implementations, which support custom hash functions

For example, in CCL

(make-hash-table :test 'uuid= :hash-function 'uuid-hash)

In SBCL you can

(sb-ext:define-hash-table-test uuid= #'uuid-hash)

and then use this as

(make-hash-table :test 'uuid=)

(but

(make-hash-table :test #'uuid= :hash-function #'uuid-hash)

will work there, too)

The ordering predicates can be used with data structures like FSet and WBTree:

(define-wbtree uuid-wbtree 
  (:key uuid)
  (:test uuid<)
  (:documentation "A weight-balanced binary tree, whose keys are
    UUID values."))
    
(defvar *mapping* (make-uuid-wbtree (list "F664863A-B3D9-4EF4-BB22-E1061F0010D6" 'stuff)))

*mapping* ;; => #<UUID-WBTREE #<UUID F664863A-B3D9-4EF4-BB22-E1061F0010D6> STUFF 1>

• Function uuid= object1 object2 → boolean

• Function uuid/= object1 object2 → boolean

• Function uuid<= object1 object2 → boolean

• Function uuid< object1 object2 → boolean

• Function uuid>= object1 object2 → boolean

• Function uuid> object1 object2 → boolean

  Each of these functions compares the argument values, both of which must be instances of type uuid, and returns true, if the values have the ordering/equality relationship hinted at by the suffix (=, <, ...)

• Function compare-uuids object1 object2 → integer

  Compares the given UUIDs for order, and answers an integer value, that is

  • negative, if object1 is uuid< compared to object2
  • zero, if object1 is uuid= compared to object2
  • positive, if object1 is uuid> compared to object2

  i.e., the result of this function satisfies

  (eql (signum (compare-uuids object1 object2))
       (cond
         ((uuid< object1 object2) -1)
         ((uuid= object1 object2) 0)
         ((uuid> object1 object2) 1)))

• Function uuid-hash object → fixnum

  Computes a hash code for the UUID value object. The algorithm used is compatible with the type's notion of equality, i.e., for two UUID values v1 and v2, the following property always holds: (or (uuid/= v1 v2) (eql (uuid-hash v1) (uuid-hash v2)))

Reading and Writing

• Function parse-uuid string &key start end → object

  Parses the string representation of a UUID, returning the result as instance of type uuid. The general format understood by this function is XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX where each X is a hexadecimal digit. Optionally, the value may be enclosed in curly braces, i.e., {XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX}; note, that if the opening brace is present, the closing must be, too. The number of Xes in the pattern is the maximum length; the function also accepts strings, where each group of Xes is shorter. Note, that at least one digit is required per group. So, the following values result in the same UUID being produced by this function:

  • 00000001-0002-0003-0004-000000000005
  • 1-2-3-4-5

  If the value can be parsed, the function returns the UUID value. If an error is detected, the function returns nil.

  This function will only inspect the portion of string in the region represented by start (inclusive) and end (exclusive). If omitted, start defaults to 0 (the beginning of string) and end to (length string).

• Function print-uuid object &key stream braces downcase → answer

  Writes a string representation of object in the "usual" format into the given character stream stream (which defaults to *standard-output*). The representation written has the general format XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX, where each X is a hexadecimal digit. If braces is true, the value is additionally enclosed in curly braces {/}. The default is to not use braces. If downcase, the function uses lower case letters in the hex representation, otherwise it uses upper case letters (the default).

  This function returns its first argument object

• Function uuid-string-p object &key lenient braces → boolean

  Tests, whether object is a string, that looks like the supported representation of a UUID value. Note, that this function is slightly more strict than parse-uuid, in that

  • if braces is true, then braces are required, if it is false (the default), then they are not accepted.

  • if lenient is true, the "short" representation is accepted, otherwise (the default) each group of hexadecimal digits must have the "nominal" length (i.e., be of 8, 4, 4, and finally 12 hex digits, respectively).

Conversions

• Function uuid object → uuid

  Coerces object to a UUID value. The argument may be one of

  • an instance of type uuid, in which case it is returned unchanged
  • a string designator (string, symbol), whose string content is the textual representation of a UUID in the format accepted by parse-uuid.
  • a byte array (i.e., (array (unsigned-byte 8) (16)))
  • an 128 bit unsigned integer number (i.e., (unsigned-byte 128))

  If object is neither of the above, the function signals a fatal condition of type type-error.

• Function uuid-bytes object → array

  Answers an (array (unsigned-byte 8) (16)), which holds the contents of the UUID object. The value array can later be passed to function uuid to reconstruct the UUID value. For all UUID values object, it is always the case that (uuid= object (uuid (uuid-bytes object))).

• Function uuid-string object &key braces downcase → string

  Answers a string representation of object in the "usual" format, i.e., XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX, where each X is a hexadecimal digit. If braces is true, the value is additionally enclosed in curly braces {/}. The default is to not use braces. If downcase, the function uses lower case letters in the hex representation, otherwise it uses upper case letters (the default).

  For any UUID value object and any combination of argument values for braces and downcase, this function guarantees, that (uuid= object (uuid (uuid-string object :braces braces :downcase downcase)))

• Function uuid-number object → value

  Answers an integer of type (unsigned-byte 128), which holds the contents of the UUID object. The value value can later be passed to function uuid to reconstruct the UUID value. For all UUID values object, it is always the case that (uuid= object (uuid (uuid-number object))).

Special Constructors

• Function random-uuid &key generator random-state → object

  Generates a fresh UUID of the "random" variant. If generator is given it must be a function of a single argument, a positive integer N, which returns an (array (unsigned-byte) (N)) of N random bytes. If random-state is given, it must be a random state. If neither is given, the function uses random with the value of *random-state* to generate the bytes. Only one of generator or random-state can be used.

• Function uuid-for-name string &key start end digest namespace → object

  FIXME

Format Information

The following functions extract information about variant and version of a UUID value. Certain extractor functions (like uuid-clock-sequence, uuid-timestamp, etc.) are meaningful only for certain variants, if at all. These functions are provided for completeness, but I have yet to find a reason for using any of them...

• Function uuid-version object → value
• Function uuid-variant object → value
• Function uuid-node object → variant
• Function uuid-clock-sequence object → variant
• Function uuid-timestamp object → variant

Compatibility with System UUID

The UUID provided by this library is comparable to the one provided by the UUID library with the following differences

• this library's UUID representation is more compact
• this library provides a complete set of comparison operators for UUIDs as well as a hash function
• there is no support for the generation of "v1" style UUIDs in this library as of now

You can convert between uuid:uuid and darts.lib.uuid:uuid values, for example, by

(defvar *uuid-uuid* (uuid:make-v1-uuid))
(defvar *darts-uuid* (darts.lib.uuid:uuid (uuid:uuid-to-byte-array *uuid-uuid*)))

and

(defvar *darts-uuid-2* (darts.lib.uuid:random-uuid))
(defvar *uuid-uuid-2* (uuid:byte-array-to-uuid (darts.lib.uuid:uuid-bytes *darts-uuid-2*)))