Request for documentation

Please add a documentation section for BINARY cursors for each and every
data type.

I am not asking for the internal format of a double or any other data
type.

Rather, for the non-obvious types (e.g. Numeric, time-with-timezone,
etc.) what exactly is returned by PQgetvalue()?

Lacking this information, it is extremely frustrating to try to use
binary cursors.

It could be a very simple table:

data type | returns
----------+------------------------------------------------
float | pointer to native float
----------+------------------------------------------------
int | pointer to native int
----------+------------------------------------------------
numeric | pointer to struct <foo> as defined in <module>
----------+------------------------------------------------
timestamp | pointer to struct <bar> as defined in <module>
----------+------------------------------------------------

etc.

For sure, I am not the only one who is having trouble with this
stuff.[1]
I see some macros that might be useful in the header files. Of course,
these macros are also completely undocumented.

For instance, when would I use DatumGetNumeric() verses
DataumGetNumericCopy()? It seems like the second performs an allocation
(as a wild guess).

For a binary cursor, somehow, I need to know exactly what data type
pointer is returned in a call to PQgetvalue(). I seem to be a poor
guesser.

[1] A post from a PostgreSQL site:
"David McCombs <davidmc(at)newcottage(dot)com>
2001-12-14 13:57:44-06
Lost one day struggling with the BINARY CURSOR and gave up:
- After reverse engineering postgres source -
(there is NO documentation on this!):
For all types it's pretty clear what the BE gives back,
BUT with the Timestamp value (double) it really wasn't clear
what the value means.

Postgres really should provide FE functions to turn the Timestamp into a
tm struct.

It should also provide an FE function to unpack the packed values of the
Numeric and Decimal (synonomous) types.

I have decided to give in and use the character return data, only to
convert it to the native type.

The major issue for me with this is that I KNOW that precision is going
to be lost on the floating point and double values. I have already seen
this in the return string representation of the data.

Also there is the performance issue of formatting to strings, converting
to a native type, then re-formatting again for a web page (or XML
stream.)

David McCombs 12/14/2001"