c939fde · typeable/uuid

git.iko.soy/typeable/uuid

on master help sign in

Refactor haddock

c939fdeHerbert Valerio Riedel9 years ago

uuid-types/Data/UUID/Types.hs+9−5

compare with master

unifiedsplit

@@ -9,13 +9,17 @@ Maintainer : hvr@gnu.org

9Portability : portable

11This library is useful for comparing, parsing and

12−printing Universally Unique Identifiers.

13−See <http://en.wikipedia.org/wiki/UUID> for the general idea.

12+printing <http://en.wikipedia.org/wiki/UUID Universally Unique Identifiers (UUID)>.

14See <http://tools.ietf.org/html/rfc4122 RFC 4122> for the specification.

13See <http://tools.ietf.org/html/rfc4122 RFC 4122> for the specification.

16-}

15-}

17module Data.UUID.Types

16module Data.UUID.Types

18− ( UUID

17+ ( -- * The 'UUID' Type

18+ UUID

19+ -- * Nil UUID

20+ , nil

21+ , null

22+ -- * Textual Representation

19 , toString

23 , toString

20 , fromString

24 , fromString

21 , toText

25 , toText

@@ -24,14 +28,14 @@ module Data.UUID.Types

24 , fromASCIIBytes

28 , fromASCIIBytes

25 , toLazyASCIIBytes

29 , toLazyASCIIBytes

26 , fromLazyASCIIBytes

30 , fromLazyASCIIBytes

31+ -- * Binary Representation

27 , toByteString

32 , toByteString

28 , fromByteString

33 , fromByteString

34+ -- * Integer Representation

29 , toWords

35 , toWords

30 , fromWords

36 , fromWords

31 , toWords64

37 , toWords64

32 , fromWords64

38 , fromWords64

33− , null

34− , nil

35 ) where

39 ) where

37import Data.UUID.Types.Internal

41import Data.UUID.Types.Internal

uuid-types/Data/UUID/Types/Internal.hs+29−15

@@ -71,12 +71,10 @@ import Data.UUID.Types.Internal.Builder

71import System.Random

74−-- |The UUID type. A 'Random' instance is provided which produces

74+-- | Type representing <https://en.wikipedia.org/wiki/UUID Universally Unique Identifiers (UUID)> as specified in

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

75+-- <http://tools.ietf.org/html/rfc4122 RFC 4122>.

77−-- network order as 16 bytes.

78data UUID = UUID {-# UNPACK #-} !Word64 {-# UNPACK #-} !Word64

76data UUID = UUID {-# UNPACK #-} !Word64 {-# UNPACK #-} !Word64

79− deriving (Eq, Ord, Typeable)

77+ deriving (Eq, Ord, Typeable)

80{-

78{-

81 Prior to uuid-types-1.0.4:

79 Prior to uuid-types-1.0.4:

82 !Word32 !Word32 !Word32 !Word32

80 !Word32 !Word32 !Word32 !Word32

@@ -95,6 +93,9 @@ data UUID = UUID {-# UNPACK #-} !Word64 {-# UNPACK #-} !Word64

95-- Useful for when you need to serialize a UUID and

93-- Useful for when you need to serialize a UUID and

96-- neither 'Storable' nor 'Binary' are appropriate.

94-- neither 'Storable' nor 'Binary' are appropriate.

97--

95--

96+-- >>> toWords <$> fromString "550e8400-e29b-41d4-a716-446655440000"

97+-- Just (1427014656,3801825748,2803254374,1430519808)

98+--

98-- See also 'toWords64'.

99-- See also 'toWords64'.

99--

100--

100-- /Since: @uuid-1.2.2@/

101-- /Since: @uuid-1.2.2@/

@@ -122,6 +123,9 @@ fromWords w1 w2 w3 w4 = UUID (w32to64 w1 w2) (w32to64 w3 w4)

122

123

123-- | Convert a 'UUID' into a pair of 'Word64's.

124-- | Convert a 'UUID' into a pair of 'Word64's.

124--

125--

126+-- >>> toWords64 <$> fromString "550e8400-e29b-41d4-a716-446655440000"

127+-- Just (6128981282234515924,12039885860129472512)

128+--

125-- See also 'toWords'.

129-- See also 'toWords'.

126--

130--

127-- @since 1.0.4

131-- @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 =

234 where b6' = b6 .&. 0x0f .|. (v `shiftL` 4)

238 where b6' = b6 .&. 0x0f .|. (v `shiftL` 4)

235 b8' = b8 .&. 0x3f .|. 0x80

239 b8' = b8 .&. 0x3f .|. 0x80

236

240

237−-- |Build a UUID of a given version from Word32 values.

241+-- |Build a UUID of a given version from 'Word32' values.

238buildFromWords :: Word8 -> Word32 -> Word32 -> Word32 -> Word32 -> UUID

242buildFromWords :: Word8 -> Word32 -> Word32 -> Word32 -> Word32 -> UUID

239buildFromWords v w0 w1 w2 w3 = fromWords w0 w1' w2' w3

243buildFromWords v w0 w1 w2 w3 = fromWords w0 w1' w2' w3

240 where w1' = w1 .&. 0xffff0fff .|. ((fromIntegral v) `shiftL` 12)

244 where w1' = w1 .&. 0xffff0fff .|. ((fromIntegral v) `shiftL` 12)

@@ -268,8 +272,8 @@ null = (== nil)

268 -- null (UUID 0 0 0 0) = True

272 -- null (UUID 0 0 0 0) = True

269 -- null _ = False

273 -- null _ = False

270

274

271−-- |The nil UUID, as defined in <http://tools.ietf.org/html/rfc4122 RFC 4122>.

275+-- |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'@.

276+-- It is a UUID of all zeros. @'null' u@ /iff/ @'u' == 'nil'@.

273nil :: UUID

277nil :: UUID

274nil = UUID 0 0

278nil = UUID 0 0

275

279

@@ -279,6 +283,8 @@ fromByteString :: BL.ByteString -> Maybe UUID

279fromByteString = fromList . BL.unpack

283fromByteString = fromList . BL.unpack

280

284

281-- |Encode a UUID into a 'ByteString' in network order.

285-- |Encode a UUID into a 'ByteString' in network order.

286+--

287+-- This uses the same encoding as the 'Binary' instance.

282toByteString :: UUID -> BL.ByteString

288toByteString :: UUID -> BL.ByteString

283toByteString = BL.pack . toList

289toByteString = BL.pack . toList

284

290

@@ -286,9 +292,8 @@ toByteString = BL.pack . toList

286-- The hyphens may not be omitted.

292-- The hyphens may not be omitted.

287-- Example:

293-- Example:

288--

294--

289−-- @

290−-- fromString \"c2cc10e1-57d6-4b6f-9899-38d972112d8c\"

295+-- >>> fromString "c2cc10e1-57d6-4b6f-9899-38d972112d8c"

291−-- @

296+-- Just c2cc10e1-57d6-4b6f-9899-38d972112d8c

292--

297--

293-- Hex digits may be upper or lower-case.

298-- Hex digits may be upper or lower-case.

294fromString :: String -> Maybe UUID

299fromString :: String -> Maybe UUID

@@ -320,9 +325,10 @@ fromString' s0 = do

320-- | Convert a UUID into a hypenated string using lower-case letters.

325-- | Convert a UUID into a hypenated string using lower-case letters.

321-- Example:

326-- Example:

322--

327--

323−-- @

324−-- toString \<$\> fromString \"550e8400-e29b-41d4-a716-446655440000\"

328+-- >>> toString <$> fromString "550e8400-e29b-41d4-a716-446655440000"

325−-- @

329+-- Just "550e8400-e29b-41d4-a716-446655440000"

330+--

331+--

326toString :: UUID -> String

332toString :: UUID -> String

327toString uuid = hexw w0 $ hexw' w1 $ hexw' w2 $ hexw w3 ""

333toString uuid = hexw w0 $ hexw' w1 $ hexw' w2 $ hexw w3 ""

328 where hexw :: Word32 -> String -> String

334 where hexw :: Word32 -> String -> String

@@ -462,6 +468,8 @@ fromLazyASCIIBytes bs =

462-- Class Instances

468-- Class Instances

463--

469--

464

470

471+-- | This 'Random' instance produces __insecure__ version 4 UUIDs as

472+-- specified in <http://tools.ietf.org/html/rfc4122 RFC 4122>.

465instance Random UUID where

473instance Random UUID where

466 random g = (fromGenNext w0 w1 w2 w3 w4, g4)

474 random g = (fromGenNext w0 w1 w2 w3 w4, g4)

467 where (w0, g0) = next g

475 where (w0, g0) = next g

@@ -508,6 +516,11 @@ instance Hashable UUID where

508 `hashWithSalt` w2

516 `hashWithSalt` w2

509 `hashWithSalt` w3

517 `hashWithSalt` w3

510

518

519+-- | Pretty prints a 'UUID' (without quotation marks). See also 'toString'.

520+--

521+-- >>> show nil

522+-- "00000000-0000-0000-0000-000000000000"

523+--

511instance Show UUID where

524instance Show UUID where

512 show = toString

525 show = toString

513

526

@@ -518,7 +531,7 @@ instance Read UUID where

518 Nothing -> []

531 Nothing -> []

519 Just u -> [(u,drop 36 noSpaces)]

532 Just u -> [(u,drop 36 noSpaces)]

520

533

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__.

522instance Storable UUID where

535instance Storable UUID where

523 sizeOf _ = 16

536 sizeOf _ = 16

524 alignment _ = 4

537 alignment _ = 4

@@ -555,6 +568,7 @@ instance Storable UUID where

555 pokeByteOff p (off+14) x9

568 pokeByteOff p (off+14) x9

556 pokeByteOff p (off+15) x10

569 pokeByteOff p (off+15) x10

557

570

571+-- | This 'Binary' instance is compatible with <http://tools.ietf.org/html/rfc4122 RFC 4122>, storing the fields in network order as 16 bytes.

558instance Binary UUID where

572instance Binary UUID where

559 put (UUID w0 w1) = putWord64be w0 >> putWord64be w1

573 put (UUID w0 w1) = putWord64be w0 >> putWord64be w1

560 get = liftM2 UUID getWord64be getWord64be

574 get = liftM2 UUID getWord64be getWord64be