@@ -71,12 +71,10 @@ import Data.UUID.Types.Internal.Builder
7171import System.Random
7272
7373
74−-- |The UUID type. A 'Random' instance is provided which produces
75−-- insecure version 4 UUIDs as specified in <http://tools.ietf.org/html/rfc4122 RFC 4122>. The 'Storable' and
76−-- 'Binary' instances are compatible with <http://tools.ietf.org/html/rfc4122 RFC 4122>, storing the fields in
77−-- network order as 16 bytes.
74+-- | Type representing <https://en.wikipedia.org/wiki/UUID Universally Unique Identifiers (UUID)> as specified in
75+-- <http://tools.ietf.org/html/rfc4122 RFC 4122>.
7876data UUID = UUID {-# UNPACK #-} !Word64 {-# UNPACK #-} !Word64
79− deriving (Eq, Ord, Typeable)
77+ deriving (Eq, Ord, Typeable)
8078{-
8179 Prior to uuid-types-1.0.4:
8280 !Word32 !Word32 !Word32 !Word32
@@ -95,6 +93,9 @@ data UUID = UUID {-# UNPACK #-} !Word64 {-# UNPACK #-} !Word64
9593-- Useful for when you need to serialize a UUID and
9694-- neither 'Storable' nor 'Binary' are appropriate.
9795--
96+-- >>> toWords <$> fromString "550e8400-e29b-41d4-a716-446655440000"
97+-- Just (1427014656,3801825748,2803254374,1430519808)
98+--
9899-- See also 'toWords64'.
99100--
100101-- /Since: @uuid-1.2.2@/
@@ -122,6 +123,9 @@ fromWords w1 w2 w3 w4 = UUID (w32to64 w1 w2) (w32to64 w3 w4)
122123
123124-- | Convert a 'UUID' into a pair of 'Word64's.
124125--
126+-- >>> toWords64 <$> fromString "550e8400-e29b-41d4-a716-446655440000"
127+-- Just (6128981282234515924,12039885860129472512)
128+--
125129-- See also 'toWords'.
126130--
127131-- @since 1.0.4
@@ -234,7 +238,7 @@ buildFromBytes v b0 b1 b2 b3 b4 b5 b6 b7 b8 b9 ba bb bc bd be bf =
234238 where b6' = b6 .&. 0x0f .|. (v `shiftL` 4)
235239 b8' = b8 .&. 0x3f .|. 0x80
236240
237−-- |Build a UUID of a given version from Word32 values.
241+-- |Build a UUID of a given version from 'Word32' values.
238242buildFromWords :: Word8 -> Word32 -> Word32 -> Word32 -> Word32 -> UUID
239243buildFromWords v w0 w1 w2 w3 = fromWords w0 w1' w2' w3
240244 where w1' = w1 .&. 0xffff0fff .|. ((fromIntegral v) `shiftL` 12)
@@ -268,8 +272,8 @@ null = (== nil)
268272 -- null (UUID 0 0 0 0) = True
269273 -- null _ = False
270274
271−-- |The nil UUID, as defined in <http://tools.ietf.org/html/rfc4122 RFC 4122>.
272−-- It is a UUID of all zeros. @'null' u@ iff @'u' == 'nil'@.
275+-- |The 'nil' UUID, as defined in <http://tools.ietf.org/html/rfc4122 RFC 4122>.
276+-- It is a UUID of all zeros. @'null' u@ /iff/ @'u' == 'nil'@.
273277nil :: UUID
274278nil = UUID 0 0
275279
@@ -279,6 +283,8 @@ fromByteString :: BL.ByteString -> Maybe UUID
279283fromByteString = fromList . BL.unpack
280284
281285-- |Encode a UUID into a 'ByteString' in network order.
286+--
287+-- This uses the same encoding as the 'Binary' instance.
282288toByteString :: UUID -> BL.ByteString
283289toByteString = BL.pack . toList
284290
@@ -286,9 +292,8 @@ toByteString = BL.pack . toList
286292-- The hyphens may not be omitted.
287293-- Example:
288294--
289−-- @
290−-- fromString \"c2cc10e1-57d6-4b6f-9899-38d972112d8c\"
291−-- @
295+-- >>> fromString "c2cc10e1-57d6-4b6f-9899-38d972112d8c"
296+-- Just c2cc10e1-57d6-4b6f-9899-38d972112d8c
292297--
293298-- Hex digits may be upper or lower-case.
294299fromString :: String -> Maybe UUID
@@ -320,9 +325,10 @@ fromString' s0 = do
320325-- | Convert a UUID into a hypenated string using lower-case letters.
321326-- Example:
322327--
323−-- @
324−-- toString \<$\> fromString \"550e8400-e29b-41d4-a716-446655440000\"
325−-- @
328+-- >>> toString <$> fromString "550e8400-e29b-41d4-a716-446655440000"
329+-- Just "550e8400-e29b-41d4-a716-446655440000"
330+--
331+--
326332toString :: UUID -> String
327333toString uuid = hexw w0 $ hexw' w1 $ hexw' w2 $ hexw w3 ""
328334 where hexw :: Word32 -> String -> String
@@ -462,6 +468,8 @@ fromLazyASCIIBytes bs =
462468-- Class Instances
463469--
464470
471+-- | This 'Random' instance produces __insecure__ version 4 UUIDs as
472+-- specified in <http://tools.ietf.org/html/rfc4122 RFC 4122>.
465473instance Random UUID where
466474 random g = (fromGenNext w0 w1 w2 w3 w4, g4)
467475 where (w0, g0) = next g
@@ -508,6 +516,11 @@ instance Hashable UUID where
508516 `hashWithSalt` w2
509517 `hashWithSalt` w3
510518
519+-- | Pretty prints a 'UUID' (without quotation marks). See also 'toString'.
520+--
521+-- >>> show nil
522+-- "00000000-0000-0000-0000-000000000000"
523+--
511524instance Show UUID where
512525 show = toString
513526
@@ -518,7 +531,7 @@ instance Read UUID where
518531 Nothing -> []
519532 Just u -> [(u,drop 36 noSpaces)]
520533
521−
534+-- | This 'Storable' instance uses the memory layout as described in <http://tools.ietf.org/html/rfc4122 RFC 4122>, but in contrast to the 'Binary' instance, __the fields are stored in host byte order__.
522535instance Storable UUID where
523536 sizeOf _ = 16
524537 alignment _ = 4
@@ -555,6 +568,7 @@ instance Storable UUID where
555568 pokeByteOff p (off+14) x9
556569 pokeByteOff p (off+15) x10
557570
571+-- | This 'Binary' instance is compatible with <http://tools.ietf.org/html/rfc4122 RFC 4122>, storing the fields in network order as 16 bytes.
558572instance Binary UUID where
559573 put (UUID w0 w1) = putWord64be w0 >> putWord64be w1
560574 get = liftM2 UUID getWord64be getWord64be