@@ -3,61 +3,61 @@
33{-# LANGUAGE PatternGuards, ScopedTypeVariables #-}
44{-# LANGUAGE RecordWildCards #-}
55
6−------------------------------------------------------------------------------
7−-- |
8−-- Module: Database.PostgreSQL.Simple.FromField
9−-- Copyright: (c) 2011 MailRank, Inc.
10−-- (c) 2011-2012 Leon P Smith
11−-- License: BSD3
12−-- Maintainer: Leon P Smith <leon@melding-monads.com>
13−-- Stability: experimental
14−-- Portability: portable
15−--
16−-- The 'FromField' typeclass, for converting a single value in a row
17−-- returned by a SQL query into a more useful Haskell representation.
18−--
19−-- A Haskell numeric type is considered to be compatible with all
20−-- PostgreSQL numeric types that are less accurate than it. For instance,
21−-- the Haskell 'Double' type is compatible with the PostgreSQL's 32-bit
22−-- @int@ type because it can represent a @int@ exactly. On the other hand,
23−-- since a 'Double' might lose precision if representing PostgreSQL's 64-bit
24−-- @bigint@, the two are /not/ considered compatible.
25−--
26−-- Because 'FromField' is a typeclass, one may provide conversions to
27−-- additional Haskell types without modifying postgresql-simple. This is
28−-- particularly useful for supporting PostgreSQL types that postgresql-simple
29−-- does not support out-of-box. Here's an example of what such an instance
30−-- might look like for a UUID type that implements the @Read@ class:
31−--
32−-- @
33−-- import Data.UUID ( UUID )
34−-- import Database.PostgreSQL.Simple.BuiltinTypes
35−-- ( BuiltinType(UUID), builtin2oid )
36−-- import qualified Data.ByteString as B
37−--
38−-- instance FromField UUID where
39−-- fromField f mdata =
40−-- if typeOid f /= builtin2oid UUID
41−-- then returnError Incompatible f ""
42−-- else case B.unpack `fmap` mdata of
43−-- Nothing -> returnError UnexpectedNull f ""
44−-- Just data ->
45−-- case [ x | (x,t) <- reads data, ("","") <- lex t ] of
46−-- [x] -> Ok x
47−-- _ -> returnError ConversionError f data
48−-- @
49−--
50−-- Note that because PostgreSQL's @uuid@ type is built into postgres and is
51−-- not provided by an extension, the 'typeOid' of @uuid@ does not change and
52−-- thus we can examine it directly. Here, we simply pull the type oid out
53−-- of the static table provided by postgresql-simple.
54−--
55−-- On the other hand if the type is provided by an extension, such as
56−-- @PostGIS@ or @hstore@, then the 'typeOid' is not stable and can vary from
57−-- database to database. In this case it is recommended that FromField
58−-- instances use 'typename' instead.
59−--
60−------------------------------------------------------------------------------
6+{- |
7+Module: Database.PostgreSQL.Simple.FromField
8+Copyright: (c) 2011 MailRank, Inc.
9+ (c) 2011-2012 Leon P Smith
10+License: BSD3
11+Maintainer: Leon P Smith <leon@melding-monads.com>
12+Stability: experimental
13+Portability: portable
14+
15+The 'FromField' typeclass, for converting a single value in a row
16+returned by a SQL query into a more useful Haskell representation.
17+
18+A Haskell numeric type is considered to be compatible with all
19+PostgreSQL numeric types that are less accurate than it. For instance,
20+the Haskell 'Double' type is compatible with the PostgreSQL's 32-bit
21+@int@ type because it can represent a @int@ exactly. On the other hand,
22+since a 'Double' might lose precision if representing PostgreSQL's 64-bit
23+@bigint@, the two are /not/ considered compatible.
24+
25+Because 'FromField' is a typeclass, one may provide conversions to
26+additional Haskell types without modifying postgresql-simple. This is
27+particularly useful for supporting PostgreSQL types that postgresql-simple
28+does not support out-of-box. Here's an example of what such an instance
29+might look like for a UUID type that implements the @Read@ class:
30+
31+@
32+import Data.UUID ( UUID )
33+import Database.PostgreSQL.Simple.BuiltinTypes
34+ ( BuiltinType(UUID), builtin2oid )
35+import qualified Data.ByteString as B
36+
37+instance FromField UUID where
38+ fromField f mdata =
39+ if typeOid f /= builtin2oid UUID
40+ then returnError Incompatible f \"\"
41+ else case B.unpack \`fmap\` mdata of
42+ Nothing -> returnError UnexpectedNull f \"\"
43+ Just data ->
44+ case [ x | (x,t) <- reads data, (\"\",\"\") <- lex t ] of
45+ [x] -> Ok x
46+ _ -> returnError ConversionError f data
47+@
48+
49+Note that because PostgreSQL's @uuid@ type is built into postgres and is
50+not provided by an extension, the 'typeOid' of @uuid@ does not change and
51+thus we can examine it directly. Here, we simply pull the type oid out
52+of the static table provided by postgresql-simple.
53+
54+On the other hand if the type is provided by an extension, such as
55+@PostGIS@ or @hstore@, then the 'typeOid' is not stable and can vary from
56+database to database. In this case it is recommended that FromField
57+instances use 'typename' instead.
58+
59+-}
60+
6161
6262module Database.PostgreSQL.Simple.FromField
6363 (