The result class is an object-oriented interface to the PostgreSQL C library API's PGresult structure. More...

#include <pq/result>

Collaboration diagram for pq::result:

Public Member Functions
	result (PGresult *pg_result)
	Constructor.

	~result () noexcept
	Destructor, which automatically performs the following actions once the instantiated object of this class goes out of scope:

PGresult *	_handle (const bool handover=false) noexcept
	Obtain the underlying PostgreSQL query result handle.

PGresult *	_to_strict (const bool strict=false) noexcept
	Whether to only convert binary data type sizes that match exactly in methods with names beginning with `to_` (when strict mode is enabled, to_int will only interpret binary data that is exactly 4 bytes, and will reject binary data that's less than 4 bytes instead of converting it).

char *	at (const int col)
	Obtain column data.

char *	at (const int row, const int col)
	Obtain column data.

bool	binaryTuples () noexcept
	Find out whether all columns contain binary data.

char *	cmdStatus ()
	Obtain the command status tag from the SQL command that generated this result.

char *	cmdTuples ()
	Obtain the number of rows affected by the SQL command.

int	cmdTuples_stoi ()
	Obtain the number of rows affected by the SQL command.

long	cmdTuples_stol ()
	Obtain the number of rows affected by the SQL command.

long long	cmdTuples_stoll ()
	Obtain the number of rows affected by the SQL command.

const char *	col_name (const int col)
	Obtain the name of a specific column (field).

uint	current ()
	Obtain the current row (0 = first row), which is used in conjunction with methods that access data by column without also specifying a row number.

result &	current (const int row)
	Specify the current row (0 = first row), which is used in conjunction with methods that access data by column without also specifying a row number.

int	fformat (const int col)
	Obtain the format code indicating the format of the given column.

result &	first ()
	Change the current row to the first valid row (0 = first row), which is used in conjunction with methods that access data by column without also specifying a row number.

int	fmod (const int col)
	Obtain the type modifier of the column associated with the given column number.

int	fsize (const int col)
	Obtain the size in bytes of the column associated with the given column number as it is stored internally in the database.

Oid	ftable (const int col)
	Obtain the OID of the table from which the given column was fetched.

uint	ftablecol (const int col)
	Obtain the column number (within its table) of the column making up the result column.

Oid	ftype (const int col)
	Obtain the OID of the data type associated with the given column number.

bool	getisnull (const int col)
	Find out whether the current row's specified column is NULL in the database.

bool	getisnull (const int row, const int col)
	Find out whether the specified row and column is NULL in the database.

size_t	getlength (const int row, const int col)
	Obtain the length of the data at the specified row and column.

char *	getvalue (const int row, const int col)
	Obtain column data.

result &	last ()
	Change the current row to the last valid row (0 = first row), which is used in conjunction with methods that access data by column without also specifying a row number.

bool	next ()
	Increment the current row number to the next row (0 = first row), which is used in conjunction with methods that access data by column without also specifying a row number.

uint	nfields ()
	Obtain the total number of columns (fields).

uint	nparams ()
	Obtain the total number of parameters of the prepared statement that this result manifested from.

uint	ntuples ()
	Obtain the total number of rows (tuples).

char *	oidStatus ()
	Obtain the OID of the inserted row in the form of an ASCIIZ string.

Oid	oidValue ()
	Obtain the OID of the inserted row, if the SQL command was an `INSERT` that inserted exactly one row into a table that has OIDs, or an `EXECUTE` of a prepared query containing a suitable `INSERT` statement.

result &	operator= (const result &source)
	Copy-operator.

Oid	paramtype (const int parameter)
	Obtain the OID of the data type of the given statement parameter.

bool	prev ()
	Decrement the current row number to the previous row (0 = first row), which is used in conjunction with methods that access data by column without also specifying a row number.

result &	print (FILE fout, const PQprintOpt po)
	Prints out all the rows and, optionally, the column names to the specified output stream.

char *	resultErrorField (const int field_code)
	Returns an individual field of an error report.

char *	resultErrorMessage ()
	Returns the error message associated with the most recent command, or an empty string if there was no error.

ExecStatusType	resultStatus ()
	Returns the result status of the most recent command, which will be one of the following values:

char *	resultVerboseErrorMessage (const PGVerbosity verbosity, const PGContextVisibility show_context)
	Returns a reformatted version of the error message associated with this result, which contains more detail than usual.

bool	to_bool (const int col, const std::optional< const bool > null_fallback={})
	Retrieves data from the column and converts it to the required datatype (both binary and text result formats are supported).

char	to_char (const int col, const std::optional< const char > null_fallback={})
	Retrieves data from the column and converts it to the required datatype (both binary and text result formats are supported).

const char *	to_cstr (const int col, const std::optional< const char * > null_fallback={})
	Retrieves data from the column and converts it to the required datatype (both binary and text result formats are supported).

double	to_double (const int col, const std::optional< const double > null_fallback={})
	Retrieves data from the column and converts it to the required datatype (both binary and text result formats are supported).

float	to_float (const int col, const std::optional< const float > null_fallback={})
	Retrieves data from the column and converts it to the required datatype (both binary and text result formats are supported).

int32_t	to_int (const int col, const std::optional< const int32_t > null_fallback={})
	Retrieves data from the column and converts it to the required datatype (both binary and text result formats are supported).

int64_t	to_long (const int col, const std::optional< const int64_t > null_fallback={})
	Retrieves data from the column and converts it to the required datatype (both binary and text result formats are supported).

int16_t	to_short (const int col, const std::optional< const int16_t > null_fallback={})
	Retrieves data from the column and converts it to the required datatype (both binary and text result formats are supported).

std::string	to_string (const int col, const std::optional< const std::string > null_fallback={})
	Retrieves data from the column and converts it to the required datatype (both binary and text result formats are supported).

std::string_view	to_string_view (const int col, const std::optional< const std::string_view > null_fallback={})
	Retrieves data from the column and converts it to the required datatype (both binary and text result formats are supported).

Static Public Member Functions
static char *	resStatus (const ExecStatusType status)
	Converts the enumerated type returned by the resultStatus method into a string constant describing the status code. (The caller must not free the result.)

Detailed Description

The result class is an object-oriented interface to the PostgreSQL C library API's PGresult structure.

Author: Randolf Richardson

Version: 1.00

History

2025-Mar-03 v1.00 Initial version

Conventions: Lower-case letters "cx" are regularly used in partial example code to represent an instantiated PostgreSQL connection object.

An ASCIIZ string is a C-string (char* array) that includes a terminating null (0) character at the end.

Notes

I use the term "ASCIIZ string" to indicate an array of characters that's terminated by a 0 (a.k.a., null). Although this is very much the same as a C-string, the difference is that in many API functions a C-string must often be accompanied by its length value. When referring to an ASCIIZ string, I'm intentionally indicating that the length of the string is not needed because the string is null-terminated. (This term was also commonly used in assembly language programming in the 1970s, 1980s, and 1990s, and as far as I know is still used by machine language programmers today.)

Example

#include <iostream> // std::cout, std::cerr, std::endl, etc.
#include <pq/pq>
 
pq::connection conn(); // Declaration only
 
int main(int argc, char *argv[]) {
  try {
    conn.connectdb("user=postgres");
    pq::result res = conn.exec("SELECT 'allballs'::TIME");
  } catch (pq::pq_error& e) {
    std::cout << e << std::endl;
    return EXIT_FAILURE;
  }
  return EXIT_SUCCESS;
} // -x- int main -x-

Parameter stacking is also supported (with methods that return result&).

Constructor & Destructor Documentation

◆ result()

pq::result::result ( PGresult * pg_result )

inline

Constructor.

Parameters

pg_result Pointer to PGresult structure

◆ ~result()

pq::result::~result ( )

inlinenoexcept

Destructor, which automatically performs the following actions once the instantiated object of this class goes out of scope:

free resources that were allocated

Member Function Documentation

◆ operator=()

result & pq::result::operator= ( const result & source )

inline

Copy-operator.

Note: The internal handover flag in the source will be set, even though the source reference is passed in as a as a constant. (The only exception to this occurs when the source is the same object, in which case no copy will be performed since it's also not necessary.)

Parameters

source Same class, but a different object

◆ _handle()

PGresult * pq::result::_handle ( const bool handover = false )

inlinenoexcept

Obtain the underlying PostgreSQL query result handle.

This is primarily needed for utilizing functionality from the PostgreSQL C programming API directly.

Warning: When this instantiated object goes out of scope, its destructor invalidates the underlying PGresult handle automatically (unless the handover flag is set).

Returns: PostgreSQL connection handle that was generated by libpq

Parameters

handover Whether to prevent destructor invalidation of the underlying handle
TRUE = prevent destructor invalidation
FALSE = don't prevent destructor invalidation (default)

◆ _to_strict()

PGresult * pq::result::_to_strict ( const bool strict = false )

inlinenoexcept

Whether to only convert binary data type sizes that match exactly in methods with names beginning with to_ (when strict mode is enabled, to_int will only interpret binary data that is exactly 4 bytes, and will reject binary data that's less than 4 bytes instead of converting it).

This setting has no effect on strings.

Returns: The same pq::result object so as to facilitate stacking

Parameters

strict TRUE = reject binary type sizes that don't match the data type
FALSE = accpet binary type sizes that are shorter than the data type (this is the default behaviour)

◆ at() [1/2]

char * pq::result::at ( const int col )

inline

Obtain column data.

Exceptions

pq::pq_position_error If the column number is out of range

Returns: Pointer to raw column data

See also: current; first; last; next; prev

Parameters

col	Column number (0 = first column; negative values count backward from the end, wherein -1 = last, -2 = penultimate, etc.)

◆ at() [2/2]

char * pq::result::at	(	const int	row,
		const int	col )

inline

Obtain column data.

Exceptions

pq::pq_position_error If the row or column number is out of range

Returns: Pointer to raw column data

See also: current; first; last; next; prev

Parameters

row	Row number (0 = first row; negative values count backward from the end, wherein -1 = last, -2 = penultimate, etc.)
col	Column number (0 = first column; negative values count backward from the end, wherein -1 = last, -2 = penultimate, etc.)

◆ binaryTuples()

bool pq::result::binaryTuples ( )

inlinenoexceptLIBPQ

Find out whether all columns contain binary data.

Warning: This function is deprecated (except for its use in connection with COPY), because it is possible for a single PGresult to contain text data in some columns and binary data in others; fformat is preferred.

Returns: TRUE = all columns are binary (a.k.a., format 1)
FALSE = at least one column contains non-binary/text data

See also: fformat

◆ cmdStatus()

char * pq::result::cmdStatus ( )

inlineLIBPQ

Obtain the command status tag from the SQL command that generated this result.

Note: Commonly this is just the name of the command, but it might also include additional data such as the number of rows processed.

Warning: The caller must not free the result directly as it will be freed by the destructor.

Returns: Command status tag string

◆ cmdTuples()

char * pq::result::cmdTuples ( )

inlineLIBPQ

Obtain the number of rows affected by the SQL command.

Note: This function returns the number of rows affected by the SQL statement that generated this result. This function can only be used following the execution of a SELECT, CREATE TABLE AS, INSERT, UPDATE, DELETE, MERGE, MOVE, FETCH, or COPY statement, or an EXECUTE of a prepared query that contains an INSERT, UPDATE, DELETE, or MERGE statement; if the command that generated this result was anything else, and empty string will be returned.

Warning: The caller must not free the result directly as it will be freed by the destructor.

Returns: Command status tag string

See also: cmdTuples_stoi; cmdTuples_stol; cmdTuples_stoll

◆ cmdTuples_stoi()

int pq::result::cmdTuples_stoi ( )

inline

Obtain the number of rows affected by the SQL command.

Note: This function returns the number of rows affected by the SQL statement that generated this result. This function can only be used following the execution of a SELECT, CREATE TABLE AS, INSERT, UPDATE, DELETE, MERGE, MOVE, FETCH, or COPY statement, or an EXECUTE of a prepared query that contains an INSERT, UPDATE, DELETE, or MERGE statement; if the command that generated this result was anything else -1 will be returned.

Returns: Command status value
-1 = value exceeds LONG_MAX -2 = non-numeric value returned

See also: cmdTuples; cmdTuples_stol; cmdTuples_stoll

◆ cmdTuples_stol()

long pq::result::cmdTuples_stol ( )

inline

Obtain the number of rows affected by the SQL command.

Note: This function returns the number of rows affected by the SQL statement that generated this result. This function can only be used following the execution of a SELECT, CREATE TABLE AS, INSERT, UPDATE, DELETE, MERGE, MOVE, FETCH, or COPY statement, or an EXECUTE of a prepared query that contains an INSERT, UPDATE, DELETE, or MERGE statement; if the command that generated this result was anything else -1 will be returned.

Returns: Command status value
-1 = value exceeds LONG_MAX -2 = non-numeric value returned

See also: cmdTuples; cmdTuples_stoi; cmdTuples_stoll

◆ cmdTuples_stoll()

long long pq::result::cmdTuples_stoll ( )

inline

Obtain the number of rows affected by the SQL command.

Note: This function returns the number of rows affected by the SQL statement that generated this result. This function can only be used following the execution of a SELECT, CREATE TABLE AS, INSERT, UPDATE, DELETE, MERGE, MOVE, FETCH, or COPY statement, or an EXECUTE of a prepared query that contains an INSERT, UPDATE, DELETE, or MERGE statement; if the command that generated this result was anything else -1 will be returned.

Returns: Command status value
-1 = value exceeds LONG_MAX -2 = non-numeric value returned

See also: cmdTuples; cmdTuples_stoi; cmdTuples_stol

◆ col_name()

const char * pq::result::col_name ( const int col )

inline

Obtain the name of a specific column (field).

Exceptions

pq::pq_position_error If the column number is out of range

Returns: Pointer to ASCIIZ column name

See also: cols

Parameters

col	Column number (0 = first column; negative values count backward from the end, wherein -1 = last, -2 = penultimate, etc.)

◆ current() [1/2]

uint pq::result::current ( )

inline

Obtain the current row (0 = first row), which is used in conjunction with methods that access data by column without also specifying a row number.

Returns: Current row

See also: at; current(const uint); first; last; next; prev

◆ current() [2/2]

result & pq::result::current ( const int row )

inline

Specify the current row (0 = first row), which is used in conjunction with methods that access data by column without also specifying a row number.

Returns: The same pq::result object so as to facilitate stacking

See also: at; current(); first; last; next; prev

Parameters

row	Row number (0 = first row; negative values count backward from the end, wherein -1 = last, -2 = penultimate, etc.)

◆ first()

result & pq::result::first ( )

inline

Change the current row to the first valid row (0 = first row), which is used in conjunction with methods that access data by column without also specifying a row number.

If there are no rows, then the current row will be set to -1.

Returns: The same pq::result object so as to facilitate stacking

See also: at; current; last; next; prev

◆ fformat()

int pq::result::fformat ( const int col )

inlineLIBPQ

Obtain the format code indicating the format of the given column.

Exceptions

pq::pq_position_error If the column number is out of range, or if the specified column is not a simple reference to a table column (PQfformat doesn't return a different error code when an out-of-range column is specified, so we perform an additional check for this beforehand.)

Returns: 0 = textual data representation
1 = binary data representation
(Other format codes are reserved for future definition, and will be returned normally if they are encountered.)

See also: ftype

Parameters

col	Column number (0 = first column; negative values count backward from the end, wherein -1 = last, -2 = penultimate, etc.)

◆ fmod()

int pq::result::fmod ( const int col )

inlineLIBPQ

Obtain the type modifier of the column associated with the given column number.

Note: The interpretation of modifier values is type-specific; they typically indicate precision or size limits

Exceptions

pq::pq_position_error If the column number is out of range, or if the specified column is not a simple reference to a table column (PQfmod doesn't return a different error code when an out-of-range column is specified, so we perform an additional check for this beforehand.)

Returns: n = type modifier
-1 = indicates "no information available" (typically because most types do not use modifiers)

See also: ftype

Parameters

col	Column number (0 = first column; negative values count backward from the end, wherein -1 = last, -2 = penultimate, etc.)

◆ fsize()

int pq::result::fsize ( const int col )

inlineLIBPQ

Obtain the size in bytes of the column associated with the given column number as it is stored internally in the database.

Warning: This is the space allocated for this column in a database row, which is the actual size of the server's internal representation of the data type. (Accordingly, it is not really very useful to clients.) A negative value indicates the data type is variable-length.

Note: In most scenarios, the getlength method is what's actually needed.

Exceptions

pq::pq_position_error If the column number is out of range, or if the specified column is not a simple reference to a table column (PQfsize doesn't return a different error code when an out-of-range column is specified, so we perform an additional check for this beforehand.)

Returns: actual size of column data that's stored internally in the database, or a negative value to indicate a variable-length data type, etc.

See also: getlength

Parameters

col	Column number (0 = first column; negative values count backward from the end, wherein -1 = last, -2 = penultimate, etc.)

◆ ftable()

Oid pq::result::ftable ( const int col )

inlineLIBPQ

Obtain the OID of the table from which the given column was fetched.

Exceptions

pq::pq_position_error If the column number is out of range, or if the specified column is not a simple reference to a table column

Returns: OID

See also: ftablecol

Parameters

col	Column number (0 = first column; negative values count backward from the end, wherein -1 = last, -2 = penultimate, etc.)

◆ ftablecol()

uint pq::result::ftablecol ( const int col )

inlineLIBPQ

Obtain the column number (within its table) of the column making up the result column.

Note: Query-result column numbers start at 0, but table columns have non-zero numbers.

Exceptions

pq::pq_position_error If the column number is out of range, or if the specified column is not a simple reference to a table column

Returns: Column number

See also: ftable

Parameters

col	Table Column number (1 = first column; negative values count backward from the end, wherein -1 = last, -2 = penultimate, etc.)

◆ ftype()

Oid pq::result::ftype ( const int col )

inlineLIBPQ

Obtain the OID of the data type associated with the given column number.

Note: You can query the system table pg_type to obtain the names and properties of the various data types. The OIDs of the built-in data types are defined in the file catalog/pg_type_d.h (which can be found in the PostgreSQL installation's include/ directory).

Exceptions

pq::pq_position_error If the column number is out of range, or if the specified column is not a simple reference to a table column (PQftype doesn't return a different error code when an out-of-range column is specified, so we perform an additional check for this beforehand.)

Returns: OID of data type

See also: fformat; fmod

Parameters

col	Column number (0 = first column; negative values count backward from the end, wherein -1 = last, -2 = penultimate, etc.)

◆ getisnull() [1/2]

bool pq::result::getisnull ( const int col )

inline

Find out whether the current row's specified column is NULL in the database.

Exceptions

pq::pq_position_error If the row or column number is out of range

Returns: TRUE = column is NULL
FALSE = column contains 0 or more bytes of data

See also: getlength; getvalue

Parameters

col	Column number (0 = first column; negative values count backward from the end, wherein -1 = last, -2 = penultimate, etc.)

◆ getisnull() [2/2]

bool pq::result::getisnull	(	const int	row,
		const int	col )

inlineLIBPQ

Find out whether the specified row and column is NULL in the database.

Exceptions

pq::pq_position_error If the row or column number is out of range

Returns: TRUE = column is NULL
FALSE = column contains 0 or more bytes of data

See also: getlength; getvalue

Parameters

row	Row number (0 = first row; negative values count backward from the end, wherein -1 = last, -2 = penultimate, etc.)
col	Column number (0 = first column; negative values count backward from the end, wherein -1 = last, -2 = penultimate, etc.)

◆ getlength()

size_t pq::result::getlength	(	const int	row,
		const int	col )

inlineLIBPQ

Obtain the length of the data at the specified row and column.

Exceptions

pq::pq_position_error If the row or column number is out of range

Returns: Length of column's data

See also: fsize; getisnull; getvalue

Parameters

row	Row number (0 = first row; negative values count backward from the end, wherein -1 = last, -2 = penultimate, etc.)
col	Column number (0 = first column; negative values count backward from the end, wherein -1 = last, -2 = penultimate, etc.)

◆ getvalue()

char * pq::result::getvalue	(	const int	row,
		const int	col )

inlineLIBPQ

Obtain column data.

Exceptions

pq::pq_position_error If the row or column number is out of range

Returns: Pointer to raw column data

See also: at; getisnull; getlength

Parameters

row	Row number (0 = first row; negative values count backward from the end, wherein -1 = last, -2 = penultimate, etc.)
col	Column number (0 = first column; negative values count backward from the end, wherein -1 = last, -2 = penultimate, etc.)

◆ last()

result & pq::result::last ( )

inline

Change the current row to the last valid row (0 = first row), which is used in conjunction with methods that access data by column without also specifying a row number.

If no rows are available, then the current row will be set to -1.

Returns: The same pq::result object so as to facilitate stacking

See also: at; current; first; next; prev

◆ next()

bool pq::result::next ( )

inline

Increment the current row number to the next row (0 = first row), which is used in conjunction with methods that access data by column without also specifying a row number.

If there are no more rows, then FALSE is returned and the current row number will not be incremented beyond the total number of rows.

Returns: TRUE = the current row was incremented to a valid row number
FALSE = the current row was incremented beyond the last valid row

See also: at; current; first; last; prev

◆ nfields()

uint pq::result::nfields ( )

inlineLIBPQ

Obtain the total number of columns (fields).

Returns: Quantity of columns

See also: col_name

◆ nparams()

uint pq::result::nparams ( )

inlineLIBPQ

Obtain the total number of parameters of the prepared statement that this result manifested from.

Note: This function is only useful when inspecting the result of the connection::describePrepared method. For other types of results it will return zero.

Returns: Quantity of rows

◆ ntuples()

uint pq::result::ntuples ( )

inlineLIBPQ

Obtain the total number of rows (tuples).

Returns: Quantity of rows

◆ oidStatus()

char * pq::result::oidStatus ( )

inlineLIBPQ

Obtain the OID of the inserted row in the form of an ASCIIZ string.

Deprecated: This function is deprecated in favor of oidValue and is not thread-safe. It returns an ASCIIZ string with the OID of the inserted row, while the oidValue method returns the OID value directly.

Returns: OID value

See also: oidValue

◆ oidValue()

Oid pq::result::oidValue ( )

inlineLIBPQ

Obtain the OID of the inserted row, if the SQL command was an INSERT that inserted exactly one row into a table that has OIDs, or an EXECUTE of a prepared query containing a suitable INSERT statement.

Returns: Oid of the inserted row
InvalidOid = not an INSERT statement, or the affected table does not contain OIDs

See also: oidStatus

◆ paramtype()

Oid pq::result::paramtype ( const int parameter )

inlineLIBPQ

Obtain the OID of the data type of the given statement parameter.

Note: This function is only useful when inspecting the result of the connection::describePrepared method. For other types of results it will return zero.

Returns: OID of data type of the given statement parameter

See also: fformat; fmod

Parameters

parameter Parameter number (0 = first parameter; negative values count backward from the end, wherein -1 = last, -2 = penultimate, etc.)

◆ prev()

bool pq::result::prev ( )

inline

Decrement the current row number to the previous row (0 = first row), which is used in conjunction with methods that access data by column without also specifying a row number.

If there are no more rows, then FALSE is returned and the current row number will not be decremented below -1.

Returns: TRUE = the current row was decremented to a valid row number
FALSE = the current row was decremented to -1

See also: at; current; first; last; next

◆ print()

result & pq::result::print	(	FILE *	fout,
		const PQprintOpt *	po )

inlineLIBPQ

Prints out all the rows and, optionally, the column names to the specified output stream.

Note: This function was formerly used by the psql command-line shell to snd the query results to STDOUT, but this is no longer the case.

This method assumes all the data is in text format.

Returns

Parameters

fout	Output stream handle
po	Structure that provides additional parameters

◆ resultErrorField()

char * pq::result::resultErrorField ( const int field_code )

inlineLIBPQ

Returns an individual field of an error report.

Field values will normally not include a trailing newline. (The caller must not free the result directly.)

The following field codes are available:

PG_DIAG_SEVERITY
The severity; the field contents are ERROR, FATAL, or PANIC (in an error message), or WARNING, NOTICE, DEBUG, INFO, or LOG (in a notice message), or a localized translation of one of these. Always present.
PG_DIAG_SEVERITY_NONLOCALIZED
The severity; the field contents are ERROR, FATAL, or PANIC (in an error message), or WARNING, NOTICE, DEBUG, INFO, or LOG (in a notice message). This is identical to the PG_DIAG_SEVERITY field except that the contents are never localized. This is present only in reports generated by PostgreSQL versions 9.6 and newer.
PG_DIAG_SQLSTATE
The SQLSTATE code for the error. The SQLSTATE code identifies the type of error that has occurred; it can be used by front-end applications to perform specific operations (such as error handling) in response to a particular database error. For a list of the possible SQLSTATE codes, see Appendix A in the official PostgreSQL documentation. This field is not localizable, and is always present.
PG_DIAG_MESSAGE_PRIMARY
The primary human-readable error message (typically one line). Always present.
PG_DIAG_MESSAGE_DETAIL
Detail: an optional secondary error message carrying more detail about the problem. Might run to multiple lines.
PG_DIAG_MESSAGE_HINT
Hint: an optional suggestion what to do about the problem. This is intended to differ from detail in that it offers advice (potentially inappropriate) rather than hard facts. Might run to multiple lines.
PG_DIAG_STATEMENT_POSITION
A string containing a decimal integer indicating an error cursor position as an index into the original statement string. The first character has index 1, and positions are measured in characters (not bytes).
PG_DIAG_INTERNAL_POSITION
This is defined the same as the PG_DIAG_STATEMENT_POSITION field, but it is used when the cursor position refers to an internally generated command rather than the one submitted by the client. The PG_DIAG_INTERNAL_QUERY field will always appear when this field appears.
PG_DIAG_INTERNAL_QUERY
The text of a failed internally-generated command. This could be, for example, an SQL query issued by a PL/pgSQL function.
PG_DIAG_CONTEXT
An indication of the context in which the error occurred. Presently this includes a call stack traceback of active procedural language functions and internally-generated queries. The trace is one entry per line, most recent first.
PG_DIAG_SCHEMA_NAME
If the error was associated with a specific database object, the name of the schema containing that object, if any.
PG_DIAG_TABLE_NAME
If the error was associated with a specific table, the name of the table. (Refer to the schema name field for the name of the table's schema.)
PG_DIAG_COLUMN_NAME
If the error was associated with a specific table column, the name of the column. (Refer to the schema and table name fields to identify the table.)
PG_DIAG_DATATYPE_NAME
If the error was associated with a specific data type, the name of the data type. (Refer to the schema name field for the name of the data type's schema.)
PG_DIAG_CONSTRAINT_NAME
If the error was associated with a specific constraint, the name of the constraint. Refer to fields listed above for the associated table or domain. (For this purpose, indexes are treated as constraints, even if they weren't created with constraint syntax.)
PG_DIAG_SOURCE_FILE
The file name of the source-code location where the error was reported.
PG_DIAG_SOURCE_LINE
The line number of the source-code location where the error was reported.
PG_DIAG_SOURCE_FUNCTION
The name of the source-code function reporting the error.

Note: The fields for schema name, table name, column name, data type name, and constraint name are supplied only for a limited number of error types; see Appendix A in the official PostgreSQL documentation. Do not assume that the presence of any of these fields guarantees the presence of another field.
Core error sources observe the interrelationships noted above, but user-defined functions may use these fields in other ways. In the same vein, do not assume that these fields denote contemporary objects in the current database.

The client is responsible for formatting displayed information to meet its needs; in particular, it should break long lines as needed. Newline characters appearing in the error message fields should be treated as paragraph breaks, not line breaks.

Errors generated internally by libpq will have severity and primary message, but typically no other fields.

Note: These error fields are only available from result objects, not connection objects; and there exists no errorField method.

Exceptions

pq_command_error If this is not an error or warning result, or does not include the specified field

Returns: Pointer to ASCIIZ string describing the error

See also: connection::errorMessage

Parameters

field_code Error field identifier

◆ resultErrorMessage()

char * pq::result::resultErrorMessage ( )

inlineLIBPQ

Returns the error message associated with the most recent command, or an empty string if there was no error.

If there was an error, the returned string will include a trailing newline. (The caller must not free the result directly.)

Immediately following the use of the connection::exec or connection::getResult methods, the connection::errorMessage method (on the connection object) will return the same string as this resultErrorMessage method (on the result). However, a result object will retain its error message until destroyed, whereas the connection's error message will change following subsequent operations.

Use resultErrorMessage when you want to know the status associated with a particular result; use connection::errorMessage when you want to know the status from the most recent operation on the connection.

Returns: Pointer to ASCIIZ string describing the error

See also: connection::errorMessage

◆ resStatus()

static char * pq::result::resStatus ( const ExecStatusType status )

inlinestaticLIBPQ

Converts the enumerated type returned by the resultStatus method into a string constant describing the status code. (The caller must not free the result.)

Returns: Pointer to ASCIIZ string describing the ExecStatusType status code, that was most likely returned by the resultStatus method

See also: resultStatus

Parameters

status Status code to enumerate

◆ resultStatus()

ExecStatusType pq::result::resultStatus ( )

inlineLIBPQ

Returns the result status of the most recent command, which will be one of the following values:

PGRES_EMPTY_QUERY
The string sent to the server was empty.
PGRES_COMMAND_OK
Successful completion of a command returning no data.
PGRES_TUPLES_OK
Successful completion of a command returning data (such as with the SELECT or SHOW commands).
PGRES_COPY_OUT
Copy Out (from server) data transfer started.
PGRES_COPY_IN
Copy In (to server) data transfer started.
PGRES_BAD_RESPONSE
The server's response was not understood.
PGRES_NONFATAL_ERROR
A nonfatal error (a notice or warning) occurred.
PGRES_FATAL_ERROR
A fatal error occurred.
PGRES_COPY_BOTH
Copy In/Out (to and from server) data transfer started. This feature is currently used only for streaming replication, so this status should not occur in ordinary applications.
PGRES_SINGLE_TUPLE
The result contains a single result tuple from the current command. This status occurs only when single-row mode has been selected for the query (see Section 32.6 of the official PostgreSQL documentation).
PGRES_TUPLES_CHUNK
The result contains several result tuples from the current command. This status occurs only when chunked mode has been selected for the query (see Section 32.6 of the official PostgreSQL documentation). The number of tuples will not exceed the limit passed to the setChunkedRowsMode method.
PGRES_PIPELINE_SYNC
The result represents a synchronization point in pipeline mode, requested by either the pipelineSync or sendPipelineSync method. This status occurs only when pipeline mode has been selected.
PGRES_PIPELINE_ABORTED
The result represents a pipeline that has received an error from the server. The getResult method must be called repeatedly, and each time it will return this status code until the end of the current pipeline, at which point it will return PGRES_PIPELINE_SYNC and normal processing can resume.

If the result status is PGRES_TUPLES_OK, PGRES_SINGLE_TUPLE, or PGRES_TUPLES_CHUNK, then some methods can be used to retrieve the rows returned by the query. Note that a SELECT command that happens to retrieve zero rows still shows PGRES_TUPLES_OK. Also, PGRES_COMMAND_OK is for commands that can never return rows (INSERT or UPDATE without a RETURNING clause, etc.). A response of PGRES_EMPTY_QUERY might indicate a bug in the client software.

A result of status PGRES_NONFATAL_ERROR will never be returned directly by connection::exec or other query execution functions; results of this kind are instead passed to the notice processor (see Section 32.13 of the official PostgreSQL documentation).

Returns: ExecStatusType

See also: getResult; pipelineSync; resStatus; sendPipelineSync; setChunkedRowsMode; connection::exec; connection::status

◆ resultVerboseErrorMessage()

char * pq::result::resultVerboseErrorMessage	(	const PGVerbosity	verbosity,
		const PGContextVisibility	show_context )

inlineLIBPQ

Returns a reformatted version of the error message associated with this result, which contains more detail than usual.

Warning: Unlike most other methods for extracting data from a result, the result of this method is a freshly allocated string. The caller must free it using the connection::freemem() method when the string is no longer needed.

Exceptions

pq_command_error If insufficient memory

Returns: Pointer to ASCIIZ string describing the error

See also: connection::errorMessage

Parameters

verbosity	Verbosity level
show_context	Context visibility setting

◆ to_bool()

bool pq::result::to_bool	(	const int	col,
		const std::optional< const bool >	null_fallback = {} )

inline

Retrieves data from the column and converts it to the required datatype (both binary and text result formats are supported).

Exceptions

std::domain_error	If the column data is `NULL`
std::length_error	If the column is the wrong size
pq::pq_position_error	If the column number is out of range

Returns: boolean

Parameters

col	Column number (0 = first column; negative values count backward from the end, wherein -1 = last, -2 = penultimate, etc.)
null_fallback	The value to revert to instead of throwing the `std::length_error` exception if the binary column data is `NULL`

◆ to_char()

char pq::result::to_char	(	const int	col,
		const std::optional< const char >	null_fallback = {} )

inline

Retrieves data from the column and converts it to the required datatype (both binary and text result formats are supported).

Exceptions

std::domain_error	If the column data is `NULL`
std::length_error	If the column is the wrong size
pq::pq_position_error	If the column number is out of range

Returns: character

See also: to_cstr; to_string; to_string_view

Parameters

col	Column number (0 = first column; negative values count backward from the end, wherein -1 = last, -2 = penultimate, etc.)
null_fallback	The value to revert to instead of throwing the `std::length_error` exception if the binary column data is `NULL`

◆ to_cstr()

const char * pq::result::to_cstr	(	const int	col,
		const std::optional< const char * >	null_fallback = {} )

inline

Retrieves data from the column and converts it to the required datatype (both binary and text result formats are supported).

Do not attempt to free the data the returned pointer addresses because it's part of a larger structure that is managed by this class's destructor.

Exceptions

std::domain_error	If the column data is `NULL`
std::length_error	If the column is the wrong size
pq::pq_position_error	If the column number is out of range

Returns: pointer to ASCIIZ string (a.k.a., "cstring")

See also: to_char; to_string; to_string_view

Parameters

col	Column number (0 = first column; negative values count backward from the end, wherein -1 = last, -2 = penultimate, etc.)
null_fallback	The value to revert to instead of throwing the `std::length_error` exception if the binary column data is `NULL`

◆ to_double()

double pq::result::to_double	(	const int	col,
		const std::optional< const double >	null_fallback = {} )

inline

Retrieves data from the column and converts it to the required datatype (both binary and text result formats are supported).

Exceptions

std::domain_error	If the column data is `NULL`
std::length_error	If the column is the wrong size
pq::pq_position_error	If the column number is out of range
std::invalid_argument	If the column data could not be converted (e.g., text contained invalid characters)
std::out_of_range	If the column data could not be converted because it is out of range

Returns: 64-bit double (real)

See also: to_float; to_int16; to_int32; to_int64

Parameters

col	Column number (0 = first column; negative values count backward from the end, wherein -1 = last, -2 = penultimate, etc.)
null_fallback	The value to revert to instead of throwing the `std::length_error` exception if the binary column data is `NULL`

◆ to_float()

float pq::result::to_float	(	const int	col,
		const std::optional< const float >	null_fallback = {} )

inline

Retrieves data from the column and converts it to the required datatype (both binary and text result formats are supported).

Exceptions

std::domain_error	If the column data is `NULL`
std::length_error	If the column is the wrong size
pq::pq_position_error	If the column number is out of range
std::invalid_argument	If the column data could not be converted (e.g., text contained invalid characters)
std::out_of_range	If the column data could not be converted because it is out of range

Returns: 32-bit float

See also: to_double; to_int16; to_int32; to_int64

Parameters

col	Column number (0 = first column; negative values count backward from the end, wherein -1 = last, -2 = penultimate, etc.)
null_fallback	The value to revert to instead of throwing the `std::length_error` exception if the binary column data is `NULL`

◆ to_short()

int16_t pq::result::to_short	(	const int	col,
		const std::optional< const int16_t >	null_fallback = {} )

inline

Retrieves data from the column and converts it to the required datatype (both binary and text result formats are supported).

Exceptions

std::domain_error	If the column data is `NULL`
std::length_error	If the column is the wrong size
pq::pq_position_error	If the column number is out of range
std::invalid_argument	If the column data could not be converted (e.g., text contained invalid characters)
std::out_of_range	If the column data could not be converted because it is out of range

Returns: 16-bit int16_t (short)

See also: to_double; to_float; to_int32; to_int64

Parameters

col	Column number (0 = first column; negative values count backward from the end, wherein -1 = last, -2 = penultimate, etc.)
null_fallback	The value to revert to instead of throwing the `std::length_error` exception if the binary column data is `NULL`

◆ to_int()

int32_t pq::result::to_int	(	const int	col,
		const std::optional< const int32_t >	null_fallback = {} )

inline

Retrieves data from the column and converts it to the required datatype (both binary and text result formats are supported).

Exceptions

std::domain_error	If the column data is `NULL`
std::length_error	If the column is the wrong size
pq::pq_position_error	If the column number is out of range
std::invalid_argument	If the column data could not be converted (e.g., text contained invalid characters)
std::out_of_range	If the column data could not be converted because it is out of range

Returns: 32-bit int32_t (int)

See also: to_double; to_float; to_int16; to_int64

Parameters

col	Column number (0 = first column; negative values count backward from the end, wherein -1 = last, -2 = penultimate, etc.)
null_fallback	The value to revert to instead of throwing the `std::length_error` exception if the binary column data is `NULL`

◆ to_long()

int64_t pq::result::to_long	(	const int	col,
		const std::optional< const int64_t >	null_fallback = {} )

inline

Retrieves data from the column and converts it to the required datatype (both binary and text result formats are supported).

Exceptions

std::domain_error	If the column data is `NULL`
std::length_error	If the column is the wrong size
pq::pq_position_error	If the column number is out of range
std::invalid_argument	If the column data could not be converted (e.g., text contained invalid characters)
std::out_of_range	If the column data could not be converted because it is out of range

Returns: 64-bit int64_t (long)

See also: to_double; to_float; to_int16; to_int32

Parameters

col	Column number (0 = first column; negative values count backward from the end, wherein -1 = last, -2 = penultimate, etc.)
null_fallback	The value to revert to instead of throwing the `std::length_error` exception if the binary column data is `NULL`

◆ to_string()

std::string pq::result::to_string	(	const int	col,
		const std::optional< const std::string >	null_fallback = {} )

inline

Retrieves data from the column and converts it to the required datatype (both binary and text result formats are supported).

Exceptions

std::domain_error	If the column data is `NULL`
std::length_error	If the column is the wrong size
pq::pq_position_error	If the column number is out of range

Returns: pointer to ASCIIZ string (a.k.a., "cstring")

See also: to_char; to_cstr; to_string_view

Parameters

col	Column number (0 = first column; negative values count backward from the end, wherein -1 = last, -2 = penultimate, etc.)
null_fallback	The value to revert to instead of throwing the `std::length_error` exception if the binary column data is `NULL`

◆ to_string_view()

std::string_view pq::result::to_string_view	(	const int	col,
		const std::optional< const std::string_view >	null_fallback = {} )

inline

Retrieves data from the column and converts it to the required datatype (both binary and text result formats are supported).

Exceptions

std::domain_error	If the column data is `NULL`
std::length_error	If the column is the wrong size
pq::pq_position_error	If the column number is out of range

Returns: pointer to ASCIIZ string (a.k.a., "cstring")

See also: to_char; to_cstr; to_string

Parameters

col	Column number (0 = first column; negative values count backward from the end, wherein -1 = last, -2 = penultimate, etc.)
null_fallback	The value to revert to instead of throwing the `std::length_error` exception if the binary column data is `NULL`

The documentation for this class was generated from the following file:

pq/result

Public Member Functions

Static Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ result()

◆ ~result()

Member Function Documentation

◆ operator=()

◆ _handle()

◆ _to_strict()

◆ at() [1/2]

◆ at() [2/2]

◆ binaryTuples()

◆ cmdStatus()

◆ cmdTuples()

◆ cmdTuples_stoi()

◆ cmdTuples_stol()

◆ cmdTuples_stoll()

◆ col_name()

◆ current() [1/2]

◆ current() [2/2]

◆ first()

◆ fformat()

◆ fmod()

◆ fsize()

◆ ftable()

◆ ftablecol()

◆ ftype()

◆ getisnull() [1/2]

◆ getisnull() [2/2]

◆ getlength()

◆ getvalue()

◆ last()

◆ next()

◆ nfields()

◆ nparams()

◆ ntuples()

◆ oidStatus()

◆ oidValue()

◆ paramtype()

◆ prev()

◆ print()

◆ resultErrorField()

◆ resultErrorMessage()

◆ resStatus()

◆ resultStatus()

◆ resultVerboseErrorMessage()

◆ to_bool()

◆ to_char()

◆ to_cstr()

◆ to_double()

◆ to_float()

◆ to_short()

◆ to_int()

◆ to_long()

◆ to_string()

◆ to_string_view()