RUBY-2039 UUID representation POC (#146)

* RUBY-2039  UUID representation POC

* Require that representation is a symbol for performance

Author: p-mongo

docs/tutorials/bson-v4.txt

@@ -228,10 +228,11 @@ will have a ``to_bson`` method defined for them are: ``Object``, ``Array``,
 In addition to the core Ruby objects, BSON also provides some special types
 specific to the specification:
 
+
 ``BSON::Binary``
 ````````````````
 
-This is a representation of binary data. The raw data and a subtype must be
+This is a representation of binary data. The raw data and the subtype must be
 provided when constructing.
 
 .. code-block:: ruby
@@ -241,6 +242,106 @@ provided when constructing.
 Valid subtypes are: ``:generic``, ``:function``, ``:old``, ``:uuid_old``,
 ``:uuid``, ``:md5``, ``:user``.
 
+UUID Methods
+~~~~~~~~~~~~
+
+To create a UUID BSON::Binary (binary subtype 4) from its RFC 4122-compliant
+string representation, use the ``from_uuid`` method:
+
+.. code-block:: ruby
+
+  uuid_str = "00112233-4455-6677-8899-aabbccddeeff"
+  BSON::Binary.from_uuid(uuid_str)
+  # => <BSON::Binary:0x46986653612880 type=uuid data=0x0011223344556677...>
+
+To stringify a UUID BSON::Binary to an RFC 4122-compliant representation,
+use the ``to_uuid`` method:
+
+.. code-block:: ruby
+
+  binary = BSON::Binary.new("\x00\x11\x22\x33\x44\x55\x66\x77\x88\x99\xAA\xBB\xCC\xDD\xEE\xFF".force_encoding('BINARY'), :uuid)
+  => <BSON::Binary:0x46942046606480 type=uuid data=0x0011223344556677...>
+  binary.to_uuid
+  => "00112233-4455-6677-8899aabbccddeeff"
+
+The standard representation may be explicitly specified when invoking both
+``from_uuid`` and ``to_uuid`` methods:
+
+.. code-block:: ruby
+
+  binary = BSON::Binary.from_uuid(uuid_str, :standard)
+  binary.to_uuid(:standard)
+
+Note that the ``:standard`` representation can only be used with a Binary
+of subtype ``:uuid`` (not ``:uuid_old``).
+
+Legacy UUIDs
+~~~~~~~~~~~~
+
+Data stored in BSON::Binary objects of subtype 3 (``:uuid_old``) may be
+persisted in one of three different byte orders depending on which driver
+created the data. The byte orders are CSharp legacy, Java legacy and Python
+legacy. The Python legacy byte order is the same as the standard RFC 4122
+byte order; CSharp legacy and Java legacy byte orders have some of the bytes
+swapped.
+
+The Binary object containing a legacy UUID does not encode *which* format
+the UUID is stored in. Therefore, methods that convert to and from the legacy
+UUID format take the desired format, or representation, as their argument.
+An application may copy legacy UUID Binary objects without knowing which byte
+order they store their data in.
+
+The following methods for working with legacy UUIDs are provided for
+interoperability with existing deployments storing data in legacy UUID formats.
+It is recommended that new applications use the ``:uuid`` (subtype 4) format
+only, which is compliant with RFC 4122.
+
+To stringify a legacy UUID BSON::Binary, use the ``to_uuid`` method specifying
+the desired representation. Accepted representations are ``:csharp_legacy``,
+``:java_legacy`` and ``:python_legacy``. Note that a legacy UUID BSON::Binary
+cannot be stringified without specifying a representation.
+
+.. code-block:: ruby
+
+  binary = BSON::Binary.new("\x00\x11\x22\x33\x44\x55\x66\x77\x88\x99\xAA\xBB\xCC\xDD\xEE\xFF".force_encoding('BINARY'), :uuid_old)
+  => <BSON::Binary:0x46942046606480 type=uuid data=0x0011223344556677...>
+  
+  binary.to_uuid
+  # => ArgumentError (Representation must be specified for BSON::Binary objects of type :uuid_old)
+  
+  binary.to_uuid(:csharp_legacy)
+  # => "33221100-5544-7766-8899aabbccddeeff"
+
+  binary.to_uuid(:java_legacy)
+  # => "77665544-3322-1100-ffeeddccbbaa9988"
+
+  binary.to_uuid(:python_legacy)
+  # => "00112233-4455-6677-8899aabbccddeeff"
+
+To create a legacy UUID BSON::Binary from the string representation of the
+UUID, use the ``from_uuid`` method specifying the desired representation:
+
+.. code-block:: ruby
+
+  uuid_str = "00112233-4455-6677-8899-aabbccddeeff"
+  
+  BSON::Binary.from_uuid(uuid_str, :csharp_legacy)
+  # => <BSON::Binary:0x46986653650480 type=uuid_old data=0x3322110055447766...>
+
+  BSON::Binary.from_uuid(uuid_str, :java_legacy)
+  # => <BSON::Binary:0x46986653663960 type=uuid_old data=0x7766554433221100...>
+  
+  BSON::Binary.from_uuid(uuid_str, :python_legacy)
+  # => <BSON::Binary:0x46986653686300 type=uuid_old data=0x0011223344556677...>
+
+These methods can be used to convert from one representation to another:
+
+.. code-block:: ruby
+
+  BSON::Binary.from_uuid('77665544-3322-1100-ffeeddccbbaa9988',:java_legacy).to_uuid(:csharp_legacy)
+  # => "33221100-5544-7766-8899aabbccddeeff"
+
+
 ``BSON::Code``
 ``````````````