sqlite-simple-0.4.18.2: Mid-Level SQLite client library

Copyright | (c) 2011 MailRank Inc. (c) 2011-2012 Leon P Smith (c) 2012-2013 Janne Hellsten
License | BSD3
Maintainer | Janne Hellsten <jjhellst@gmail.com>
Portability | portable
Safe Haskell | Safe-Inferred
Language | Haskell2010

Database.SQLite.Simple.FromField

Description

The `FromField` typeclass, for converting a single value in a row returned by a SQL query into a more useful Haskell representation.

A Haskell numeric type is considered to be compatible with all SQLite numeric types that are less accurate than it. For instance, the Haskell `Double` type is compatible with the SQLite's 32-bit `Int` type because it can represent a `Int` exactly. On the other hand, since a `Double` might lose precision if representing a 64-bit `BigInt`, the two are not considered compatible.

Synopsis

- class FromField a where
  - fromField :: FieldParser a
- type FieldParser a = Field -> Ok a
- data ResultError
  - = Incompatible {
    - errSQLType :: String
    - errHaskellType :: String
    - errMessage :: String
    }
  - | UnexpectedNull {
    - errSQLType :: String
    - errHaskellType :: String
    - errMessage :: String
    }
  - | ConversionFailed {
    - errSQLType :: String
    - errHaskellType :: String
    - errMessage :: String
    }
- data Field
- fieldData :: Field -> SQLData
- returnError :: forall a err. (Typeable a, Exception err) => (String -> String -> String -> err) -> Field -> String -> Ok a

# Documentation

class FromField a where #

A type that may be converted from a SQL type.

Methods

fromField :: FieldParser a #

Convert a SQL value to a Haskell value.

Returns a list of exceptions if the conversion fails. In the case of library instances, this will usually be a single `ResultError`, but may be a `UnicodeException`.

Implementations of `fromField` should not retain any references to the `Field` nor the `ByteString` arguments after the result has been evaluated to WHNF. Such a reference causes the entire `LibPQ.`Result`` to be retained.

For example, the instance for `ByteString` uses `copy` to avoid such a reference, and that using bytestring functions such as `drop` and `takeWhile` alone will also trigger this memory leak.

#### Instances

Instances details

FromField Int16 # |
Instance details Defined in Database.SQLite.Simple.FromField Methods fromField :: FieldParser Int16 #
FromField Int32 # |
Instance details Defined in Database.SQLite.Simple.FromField Methods fromField :: FieldParser Int32 #
FromField Int64 # |
Instance details Defined in Database.SQLite.Simple.FromField Methods fromField :: FieldParser Int64 #
FromField Int8 # |
Instance details Defined in Database.SQLite.Simple.FromField Methods fromField :: FieldParser Int8 #
FromField Word16 # |
Instance details Defined in Database.SQLite.Simple.FromField Methods fromField :: FieldParser Word16 #
FromField Word32 # |
Instance details Defined in Database.SQLite.Simple.FromField Methods fromField :: FieldParser Word32 #
FromField Word64 # |
Instance details Defined in Database.SQLite.Simple.FromField Methods fromField :: FieldParser Word64 #
FromField Word8 # |
Instance details Defined in Database.SQLite.Simple.FromField Methods fromField :: FieldParser Word8 #
FromField ByteString # |
Instance details Defined in Database.SQLite.Simple.FromField Methods fromField :: FieldParser ByteString #
FromField ByteString # |
Instance details Defined in Database.SQLite.Simple.FromField Methods fromField :: FieldParser ByteString #
FromField SQLData # |
Instance details Defined in Database.SQLite.Simple.FromField Methods fromField :: FieldParser SQLData #
FromField Null # |
Instance details Defined in Database.SQLite.Simple.FromField Methods fromField :: FieldParser Null #
FromField Text # |
Instance details Defined in Database.SQLite.Simple.FromField Methods fromField :: FieldParser Text #
FromField Text # |
Instance details Defined in Database.SQLite.Simple.FromField Methods fromField :: FieldParser Text #
FromField Day # |
Instance details Defined in Database.SQLite.Simple.FromField Methods fromField :: FieldParser Day #
FromField UTCTime # |
Instance details Defined in Database.SQLite.Simple.FromField Methods fromField :: FieldParser UTCTime #
FromField Integer # |
Instance details Defined in Database.SQLite.Simple.FromField Methods fromField :: FieldParser Integer #
FromField Bool # |
Instance details Defined in Database.SQLite.Simple.FromField Methods fromField :: FieldParser Bool #
FromField Double # |
Instance details Defined in Database.SQLite.Simple.FromField Methods fromField :: FieldParser Double #
FromField Float # |
Instance details Defined in Database.SQLite.Simple.FromField Methods fromField :: FieldParser Float #
FromField Int # |
Instance details Defined in Database.SQLite.Simple.FromField Methods fromField :: FieldParser Int #
FromField Word # |
Instance details Defined in Database.SQLite.Simple.FromField Methods fromField :: FieldParser Word #
FromField a => FromField (Maybe a) # |
Instance details Defined in Database.SQLite.Simple.FromField Methods fromField :: FieldParser (Maybe a) #
FromField [Char] # |
Instance details Defined in Database.SQLite.Simple.FromField Methods fromField :: FieldParser [Char] #

type FieldParser a = Field -> Ok a #

data ResultError #

Exception thrown if conversion from a SQL value to a Haskell value fails.

Constructors

Incompatible | The SQL and Haskell types are not compatible.
Fields errSQLType :: String errHaskellType :: String errMessage :: String
UnexpectedNull | A SQL `NULL` was encountered when the Haskell type did not permit it.
Fields errSQLType :: String errHaskellType :: String errMessage :: String
ConversionFailed | The SQL value could not be parsed, or could not be represented as a valid Haskell value, or an unexpected low-level error occurred (e.g. mismatch between metadata and actual data in a row).
Fields errSQLType :: String errHaskellType :: String errMessage :: String

#### Instances

Instances details

Exception ResultError # |
Instance details Defined in Database.SQLite.Simple.FromField Methods toException :: ResultError -> SomeException fromException :: SomeException -> Maybe ResultError displayException :: ResultError -> String
Show ResultError # |
Instance details Defined in Database.SQLite.Simple.FromField Methods showsPrec :: Int -> ResultError -> ShowS show :: ResultError -> String showList :: [ResultError] -> ShowS
Eq ResultError # |
Instance details Defined in Database.SQLite.Simple.FromField Methods (==) :: ResultError -> ResultError -> Bool (/=) :: ResultError -> ResultError -> Bool

data Field #

A Field represents metadata about a particular field

fieldData :: Field -> SQLData #

Return the actual SQL data for a database field. This allows user-defined `FromField` instances to access the SQL data associated with a field being parsed.

returnError :: forall a err. (Typeable a, Exception err) => (String -> String -> String -> err) -> Field -> String -> Ok a #

Given one of the constructors from `ResultError`, the field, and an `errMessage`, this fills in the other fields in the exception value and returns it in a 'Left . SomeException' constructor.