@@ -64,24 +64,51 @@ data TypeInfo = TypeInfo { typ :: !NamedOid
64 , typelem :: !(Maybe NamedOid)
64 , typelem :: !(Maybe NamedOid)
65 } deriving Show
65 } deriving Show
67+-- | Returns the data type name. This is the preferred way of identifying
68+-- types that do not have a stable type oid, such as types provided by
69+-- extensions to PostgreSQL.
71+-- More concretely, it returns the @typname@ column associated with the
72+-- type oid in the @pg_type@ table. First, postgresql-simple will check
73+-- built-in, static table. If the type oid is not there, postgresql-simple
74+-- will check a per-connection cache, and then finally query the database's
67typename :: Field -> ByteString
77typename :: Field -> ByteString
68typename = typname . typ . typeinfo
78typename = typname . typ . typeinfo
80+-- | Returns the name of the column. This is often determined by a table
81+-- definition, but it can be set using an @as@ clause.
70name :: Field -> Maybe ByteString
83name :: Field -> Maybe ByteString
71name Field{..} = unsafePerformIO (PQ.fname result column)
84name Field{..} = unsafePerformIO (PQ.fname result column)
86+-- | Returns the name of the object id of the @table@ associated with the
87+-- column, if any. Returns 'invalidOid' when there is no such table;
88+-- for example a computed column does not have a table associated with it.
89+-- Analogous to libpq's @PQftable@.
73tableOid :: Field -> PQ.Oid
91tableOid :: Field -> PQ.Oid
74tableOid Field{..} = unsafePerformIO (PQ.ftable result column)
92tableOid Field{..} = unsafePerformIO (PQ.ftable result column)
94+-- | If the column has a table associated with it, this returns the number
95+-- of the associated table column. Numbering starts from 0. Analogous
96+-- to libpq's @PQftablecol@.
76tableColumn :: Field -> Int
98tableColumn :: Field -> Int
77tableColumn Field{..} = fromCol (unsafePerformIO (PQ.ftablecol result column))
99tableColumn Field{..} = fromCol (unsafePerformIO (PQ.ftablecol result column))
79 fromCol (PQ.Col x) = fromIntegral x
101 fromCol (PQ.Col x) = fromIntegral x
103+-- | This returns whether the data was returned in a binary or textual format.
104+-- Analogous to libpq's @PQfformat@.
82format :: Field -> PQ.Format
106format :: Field -> PQ.Format
83format Field{..} = unsafePerformIO (PQ.fformat result column)
107format Field{..} = unsafePerformIO (PQ.fformat result column)
109+-- | This returns the type oid associated with the column. Analogous
110+-- to libpq's @PQftype@.
85typeOid :: Field -> PQ.Oid
112typeOid :: Field -> PQ.Oid
86typeOid = typoid . typ . typeinfo
113typeOid = typoid . typ . typeinfo