@@ -14,6 +14,8 @@ Portability: portable
1414
1515The 'FromField' typeclass, for converting a single value in a row
1616returned by a SQL query into a more useful Haskell representation.
17+Note that each instance of 'FromField' is documented by a list of
18+compatible postgresql types.
1719
1820A Haskell numeric type is considered to be compatible with all
1921PostgreSQL numeric types that are less accurate than it. For instance,
@@ -225,14 +227,20 @@ tableColumn Field{..} = fromCol (unsafeDupablePerformIO (PQ.ftablecol result col
225227format :: Field -> PQ.Format
226228format Field{..} = unsafeDupablePerformIO (PQ.fformat result column)
227229
230+-- | For dealing with null values. Compatible with any postgresql type
231+-- compatible with type @a@. Note that the type is not checked if
232+-- the value is null, although it is inadvisable to rely on this
233+-- behavior.
228234instance (FromField a) => FromField (Maybe a) where
229235 fromField _ Nothing = pure Nothing
230236 fromField f bs = Just <$> fromField f bs
231237
238+-- | compatible with any data type, but the value must be null
232239instance FromField Null where
233240 fromField _ Nothing = pure Null
234241 fromField f (Just _) = returnError ConversionFailed f "data is not null"
235242
243+-- | bool
236244instance FromField Bool where
237245 fromField f bs
238246 | typeOid f /= typoid (TypeInfo.bool) = returnError Incompatible f ""
@@ -241,6 +249,7 @@ instance FromField Bool where
241249 | bs == Just "f" = pure False
242250 | otherwise = returnError ConversionFailed f ""
243251
252+-- | \"char\"
244253instance FromField Char where
245254 fromField f bs =
246255 if typeOid f /= typoid (TypeInfo.char)
@@ -251,29 +260,43 @@ instance FromField Char where
251260 then returnError ConversionFailed f "length not 1"
252261 else return $! (B.head bs)
253262
263+-- | int2
254264instance FromField Int16 where
255265 fromField = atto ok16 $ signed decimal
256266
267+-- | int2, int4
257268instance FromField Int32 where
258269 fromField = atto ok32 $ signed decimal
259270
271+#if WORD_SIZE_IN_BITS < 64
272+-- | int2, int4, and if compiled as 64-bit code, int8 as well.
273+-- This library was compiled as 32-bit code.
274+#else
275+-- | int2, int4, and if compiled as 64-bit code, int8 as well.
276+-- This library was compiled as 64-bit code.
277+#endif
260278instance FromField Int where
261279 fromField = atto okInt $ signed decimal
262280
281+-- | int2, int4, int8
263282instance FromField Int64 where
264283 fromField = atto ok64 $ signed decimal
265284
285+-- | int2, int4, int8
266286instance FromField Integer where
267287 fromField = atto ok64 $ signed decimal
268288
289+-- | int2, float4
269290instance FromField Float where
270291 fromField = atto ok (realToFrac <$> double)
271292 where ok = mkCompats [Float4,Int2]
272293
294+-- | int2, int4, float4, float8
273295instance FromField Double where
274296 fromField = atto ok double
275297 where ok = mkCompats [Float4,Float8,Int2,Int4]
276298
299+-- | int2, int4, float4, float8, numeric
277300instance FromField (Ratio Integer) where
278301 fromField = atto ok rational
279302 where ok = mkCompats [Float4,Float8,Int2,Int4,Numeric]
@@ -281,14 +304,17 @@ instance FromField (Ratio Integer) where
281304unBinary :: Binary t -> t
282305unBinary (Binary x) = x
283306
307+-- | bytea, name, text, \"char\", bpchar, varchar, unknown
284308instance FromField SB.ByteString where
285309 fromField f dat = if typeOid f == typoid TypeInfo.bytea
286310 then unBinary <$> fromField f dat
287311 else doFromField f okText' (pure . B.copy) dat
288312
313+-- | oid
289314instance FromField PQ.Oid where
290315 fromField f dat = PQ.Oid <$> atto (mkCompat Oid) decimal f dat
291316
317+-- | bytea, name, text, \"char\", bpchar, varchar, unknown
292318instance FromField LB.ByteString where
293319 fromField f dat = LB.fromChunks . (:[]) <$> fromField f dat
294320
@@ -298,48 +324,62 @@ unescapeBytea f str = case unsafeDupablePerformIO (PQ.unescapeBytea str) of
298324 Nothing -> returnError ConversionFailed f "unescapeBytea failed"
299325 Just str -> pure (Binary str)
300326
327+-- | bytea
301328instance FromField (Binary SB.ByteString) where
302329 fromField f dat = case format f of
303330 PQ.Text -> doFromField f okBinary (unescapeBytea f) dat
304331 PQ.Binary -> doFromField f okBinary (pure . Binary . B.copy) dat
305332
333+-- | bytea
306334instance FromField (Binary LB.ByteString) where
307335 fromField f dat = Binary . LB.fromChunks . (:[]) . unBinary <$> fromField f dat
308336
337+-- | name, text, \"char\", bpchar, varchar
309338instance FromField ST.Text where
310339 fromField f = doFromField f okText $ (either left pure . ST.decodeUtf8')
311340 -- FIXME: check character encoding
312341
342+-- | name, text, \"char\", bpchar, varchar
313343instance FromField LT.Text where
314344 fromField f dat = LT.fromStrict <$> fromField f dat
315345
346+-- | name, text, \"char\", bpchar, varchar
316347instance FromField [Char] where
317348 fromField f dat = ST.unpack <$> fromField f dat
318349
350+-- | timestamptz
319351instance FromField UTCTime where
320352 fromField = ff TypeInfo.timestamptz "UTCTime" parseUTCTime
321353
354+-- | timestamptz
322355instance FromField ZonedTime where
323356 fromField = ff TypeInfo.timestamptz "ZonedTime" parseZonedTime
324357
358+-- | timestamp
325359instance FromField LocalTime where
326360 fromField = ff TypeInfo.timestamp "LocalTime" parseLocalTime
327361
362+-- | date
328363instance FromField Day where
329364 fromField = ff TypeInfo.date "Day" parseDay
330365
366+-- | time
331367instance FromField TimeOfDay where
332368 fromField = ff TypeInfo.time "TimeOfDay" parseTimeOfDay
333369
370+-- | timestamptz
334371instance FromField UTCTimestamp where
335372 fromField = ff TypeInfo.timestamptz "UTCTimestamp" parseUTCTimestamp
336373
374+-- | timestamptz
337375instance FromField ZonedTimestamp where
338376 fromField = ff TypeInfo.timestamptz "ZonedTimestamp" parseZonedTimestamp
339377
378+-- | timestamp
340379instance FromField LocalTimestamp where
341380 fromField = ff TypeInfo.timestamp "LocalTimestamp" parseLocalTimestamp
342381
382+-- | date
343383instance FromField Date where
344384 fromField = ff TypeInfo.date "Date" parseDate
345385
@@ -367,6 +407,7 @@ instance (FromField a, FromField b) => FromField (Either a b) where
367407 fromField f dat = (Right <$> fromField f dat)
368408 <|> (Left <$> fromField f dat)
369409
410+-- | any postgresql array whose elements are compatible with type @a@
370411instance (FromField a, Typeable a) => FromField (Vector a) where
371412 fromField f mdat = do
372413 info <- typeInfo f