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:

Classes
class	row
	The row class is part of the object-oriented interface to the PostgreSQL C library API's PGresult structure that provides specialized access to a single row. More...

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 ROW, const char *COL_NAME)
	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.

row	curr () noexcept
	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.

int	current_row () noexcept
	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.

int	fformat (const char *COL_NAME)
	Obtain the format code indicating the format of the given column.

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

result &	final () noexcept
	Reset the current row to row after 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.

row	first () noexcept
	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 char *COL_NAME)
	Obtain the type modifier of the column associated with the given column number.

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

const char *	fname (const char *COL_NAME)
	Obtain the case-sensitive name of a specific column (field).

const char *	fname (const int COL)
	Obtain the case-sensitive name of a specific column (field).

int	fnumber (const char *COL_NAME)
	Obtain the column (field) number for the specified case-insensitive name (if the name is enclosed within quotation marks, it will become case-sensitive).

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

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 char *COL_NAME)
	Obtain the OID of the table from which the given column was fetched.

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

uint	ftablecol (const char *COL_NAME)
	Obtain the column number (within its table) of the column making up the result column.

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

Oid	ftype (const char *COL_NAME)
	Obtain the OID of the data type associated with the given column number.

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

bool	getisnull (const int ROW, const char *COL_NAME)
	Find out whether the specified row and 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 char *COL_NAME)
	Obtain the length of the data at the specified row and column.

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 char *COL_NAME)
	Obtain column data.

char *	getvalue (const int ROW, const int COL)
	Obtain column data.

row	last () noexcept
	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.

row	next () noexcept
	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 () noexcept
	Obtain the total number of columns (fields).

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

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

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

Oid	oidValue () noexcept
	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.

row	operator[] (const int ROW)
	Array-style access to rows. The first row is at index 0.

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

row	prev () noexcept
	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) noexcept
	Prints out all the rows and, optionally, the column names to the specified output stream.

result &	reset () noexcept
	Reset the current row to row before 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.

char *	resStatus () noexcept
	Converts the enumerated type returned by this object's resultStatus method into a string constant describing the status code. (The caller must not free the result.)

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

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

ExecStatusType	resultStatus () noexcept
	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.

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

bool	to_bool (const int ROW, const char *COL_NAME, 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).

bool	to_bool (const int ROW, 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 ROW, const char *COL_NAME, 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).

char	to_char (const int ROW, 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 ROW, const char COL_NAME, 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 ROW, 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 ROW, const char *COL_NAME, 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).

double	to_double (const int ROW, 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 ROW, const char *COL_NAME, 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).

float	to_float (const int ROW, 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 ROW, const char *COL_NAME, 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).

int32_t	to_int (const int ROW, 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 ROW, const char *COL_NAME, 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).

int64_t	to_long (const int ROW, 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 ROW, const char *COL_NAME, 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).

int16_t	to_short (const int ROW, 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 ROW, const char *COL_NAME, 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	to_string (const int ROW, 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 ROW, const char *COL_NAME, 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).

std::string_view	to_string_view (const int ROW, 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).

row	visit (const int ROW) noexcept
	Obtain a direct reference to the specified row (0 = first row), without altering the current row position.

Static Public Member Functions
static char *	resStatus (const ExecStatusType status) noexcept
	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::errors& 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

◆ _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	ROW,
		const int	COL )

inline

Obtain column data.

Exceptions

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

Returns: Pointer to raw column data

See also: curr; current_row; final; first; seek; last; next; prev; reset; visit

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.)

◆ at() [2/2]

char * pq::result::at	(	const int	ROW,
		const char *	COL_NAME )

inline

Obtain column data.

Exceptions

pq::errors::position If the row number is out of range or the column name doesn't exist

Returns: Pointer to raw column data

See also: curr; current_row; final; first; seek; last; next; prev; reset; visit

Parameters

ROW	Row number (0 = first row; negative values count backward from the end, wherein -1 = last, -2 = penultimate, etc.)
COL_NAME	ASCIIZ column name (case-insensitive)

◆ 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

◆ curr()

row pq::result::curr ( )

inlinenoexcept

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: The row as a pq::result::row object (that references the column data internally instead of making copies)

See also: at; current_row; final; first; seek; last; next; prev; reset; visit

◆ current_row()

int pq::result::current_row ( )

inlinenoexcept

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: The row as a pq::result::row object (that references the column data internally instead of making copies)

See also: at; curr; final; first; seek; last; next; prev; reset; visit

◆ fformat() [1/2]

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

inlineLIBPQ

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

Exceptions

pq::errors::position 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.)

◆ fformat() [2/2]

int pq::result::fformat ( const char * COL_NAME )

inline

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

Exceptions

pq::errors::position 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_NAME ASCIIZ column name (case-insensitive)

◆ final()

result & pq::result::final ( )

inlinenoexcept

Reset the current row to row after 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.

The current row will be reset to whatever the total number of tuples is, the opposite of the reset method, which is one past the last valid row (this is useful for before methods like prev are used). This makes it easy to run multiple while (pq::result::row row = res.prev()) {} loops over the same result set without having to execute the same query.

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

See also: at; curr; current_row; first; seek; last; next; prev; reset; visit

◆ first()

row pq::result::first ( )

inlinenoexcept

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 row as a pq::result::row object (that references the column data internally instead of making copies)

See also: at; curr; current_row; final; seek; last; next; prev; reset; visit

◆ fmod() [1/2]

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::errors::position 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.)

◆ fmod() [2/2]

int pq::result::fmod ( const char * COL_NAME )

inline

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::errors::position 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_NAME ASCIIZ column name (case-insensitive)

◆ fname() [1/2]

const char * pq::result::fname ( const int COL )

inlineLIBPQ

Obtain the case-sensitive name of a specific column (field).

Exceptions

pq::errors::position If the column number is out of range

Returns: Pointer to ASCIIZ column name (case-sensitive)

See also: fnumber

Parameters

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

◆ fname() [2/2]

const char * pq::result::fname ( const char * COL_NAME )

inline

Obtain the case-sensitive name of a specific column (field).

Exceptions

pq::errors::position If the column number is out of range

Returns: Pointer to ASCIIZ column name (case-sensitive)

See also: fnumber

Parameters

COL_NAME ASCIIZ column name (case-insensitive)

◆ fnumber()

int pq::result::fnumber ( const char * COL_NAME )

inlineLIBPQ

Obtain the column (field) number for the specified case-insensitive name (if the name is enclosed within quotation marks, it will become case-sensitive).

Exceptions

pq::errors::position If the column name doesn't exist

Returns: Column (field) number (0 = first column)

See also: fname

Parameters

COL_NAME ASCIIZ column name (case-sensitive)

◆ fsize() [1/2]

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::errors::position 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.)

◆ fsize() [2/2]

int pq::result::fsize ( const char * COL_NAME )

inline

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::errors::position 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_NAME ASCIIZ column name (case-insensitive)

◆ ftable() [1/2]

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

inlineLIBPQ

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

Exceptions

pq::errors::position 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.)

◆ ftable() [2/2]

Oid pq::result::ftable ( const char * COL_NAME )

inline

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

Exceptions

pq::errors::position 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_NAME ASCIIZ column name (case-insensitive)

◆ ftablecol() [1/2]

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::errors::position 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.)

◆ ftablecol() [2/2]

uint pq::result::ftablecol ( const char * COL_NAME )

inline

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::errors::position 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_NAME ASCIIZ column name (case-insensitive)

◆ ftype() [1/2]

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::errors::position 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.)

◆ ftype() [2/2]

Oid pq::result::ftype ( const char * COL_NAME )

inline

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::errors::position 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_NAME ASCIIZ column name (case-insensitive)

◆ getisnull() [1/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::errors::position 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.)

◆ getisnull() [2/2]

bool pq::result::getisnull	(	const int	ROW,
		const char *	COL_NAME )

inline

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

Exceptions

pq::errors::position 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_NAME	ASCIIZ column name (case-insensitive)

◆ getlength() [1/2]

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::errors::position 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.)

◆ getlength() [2/2]

size_t pq::result::getlength	(	const int	ROW,
		const char *	COL_NAME )

inline

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

Exceptions

pq::errors::position 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_NAME	ASCIIZ column name (case-insensitive)

◆ getvalue() [1/2]

char * pq::result::getvalue	(	const int	ROW,
		const int	COL )

inlineLIBPQ

Obtain column data.

Exceptions

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

Returns: Pointer to raw column data

See also: at; visit; 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.)

◆ getvalue() [2/2]

char * pq::result::getvalue	(	const int	ROW,
		const char *	COL_NAME )

inline

Obtain column data.

Exceptions

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

Returns: Pointer to raw column data

See also: at; visit; getisnull; getlength

Parameters

ROW	Row number (0 = first row; negative values count backward from the end, wherein -1 = last, -2 = penultimate, etc.)
COL_NAME	ASCIIZ column name (case-insensitive)

◆ last()

row pq::result::last ( )

inlinenoexcept

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 row as a pq::result::row object (that references the column data internally instead of making copies)

See also: at; curr; current_row; final; first; seek; next; prev; reset; visit

◆ next()

row pq::result::next ( )

inlinenoexcept

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: The row as a pq::result::row object (that references the column data internally instead of making copies)

See also: at; curr; current_row; final; first; seek; last; prev; reset; visit

◆ nfields()

uint pq::result::nfields ( )

inlinenoexceptLIBPQ

Obtain the total number of columns (fields).

Returns: Quantity of columns

See also: col_name

◆ nparams()

uint pq::result::nparams ( )

inlinenoexceptLIBPQ

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 ( )

inlinenoexceptLIBPQ

Obtain the total number of rows (tuples).

Returns: Quantity of rows

◆ oidStatus()

char * pq::result::oidStatus ( )

inlinenoexceptLIBPQ

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 ( )

inlinenoexceptLIBPQ

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()

row pq::result::prev ( )

inlinenoexcept

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: The row as a pq::result::row object (that references the column data internally instead of making copies)

See also: at; curr; current_row; final; first; seek; last; next; prev; reset; visit

◆ print()

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

inlinenoexceptLIBPQ

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: The same pq::result object so as to facilitate stacking

Parameters

fout	Output stream handle
po	Structure that provides additional parameters

◆ reset()

result & pq::result::reset ( )

inlinenoexcept

Reset the current row to row before 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.

The current row will be reset to -1, which is the same state that follows immediately after a query (before methods like next are used). This makes it easy to run multiple while (pq::result::row row = res.next()) {} loops over the same result set without having to execute the same query.

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

See also: at; curr; current_row; final; first; seek; last; next; prev; pq::connection::reset

◆ 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 ( )

inlinenoexceptLIBPQ

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() [1/2]

char * pq::result::resStatus ( )

inlinenoexcept

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

This is the same as calling resStatus(resultStatus()) which is provided here for convenience.

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

See also: resStatus(const ExecStatusType); resultStatus

◆ resStatus() [2/2]

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

inlinestaticnoexceptLIBPQ

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: resStatus; resultStatus

Parameters

status Status code to enumerate

◆ resultStatus()

ExecStatusType pq::result::resultStatus ( )

inlinenoexceptLIBPQ

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

◆ seek()

row pq::result::seek ( const int ROW )

inlinenoexcept

Specify and return 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 row as a pq::result::row object (that references the column data internally instead of making copies)

See also: at; curr; current_row; final; first; last; next; prev; reset; visit

Parameters

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

◆ to_bool() [1/2]

bool pq::result::to_bool	(	const int	ROW,
		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::errors::position	If the column number is out of range

Returns: boolean (the BOOL data type in PostgreSQL)

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.)
null_fallback	The value to revert to instead of throwing the `std::length_error` exception if the binary column data is `NULL`

◆ to_bool() [2/2]

bool pq::result::to_bool	(	const int	ROW,
		const char *	COL_NAME,
		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::errors::position	If the column number is out of range

Returns: boolean (the BOOL data type in PostgreSQL)

Parameters

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

◆ to_char() [1/2]

char pq::result::to_char	(	const int	ROW,
		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::errors::position	If the column number is out of range

Returns: character (the CHAR data type in PostgreSQL)

See also: to_cstr; to_string; to_string_view

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.)
null_fallback	The value to revert to instead of throwing the `std::length_error` exception if the binary column data is `NULL`

◆ to_char() [2/2]

char pq::result::to_char	(	const int	ROW,
		const char *	COL_NAME,
		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::errors::position	If the column number is out of range

Returns: character (the CHAR data type in PostgreSQL)

See also: to_cstr; to_string; to_string_view

Parameters

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

◆ to_cstr() [1/2]

const char * pq::result::to_cstr	(	const int	ROW,
		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::errors::position	If the column number is out of range

Returns: pointer to ASCIIZ string (a.k.a., cstring in PostgreSQL, which is used internally for the CHAR[n], VARCHAR, and TEXT data types)

See also: to_char; to_string; to_string_view

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.)
null_fallback	The value to revert to instead of throwing the `std::length_error` exception if the binary column data is `NULL`

◆ to_cstr() [2/2]

const char * pq::result::to_cstr	(	const int	ROW,
		const char *	COL_NAME,
		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::errors::position	If the column number is out of range

Returns: pointer to ASCIIZ string (a.k.a., cstring in PostgreSQL, which is used internally for the CHAR[n], VARCHAR, and TEXT data types)

See also: to_char; to_string; to_string_view

Parameters

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

◆ to_double() [1/2]

double pq::result::to_double	(	const int	ROW,
		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::errors::position	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; the FLOAT8 data type in PostgreSQL)

See also: to_float; to_short; to_int; to_long

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.)
null_fallback	The value to revert to instead of throwing the `std::length_error` exception if the binary column data is `NULL`

◆ to_double() [2/2]

double pq::result::to_double	(	const int	ROW,
		const char *	COL_NAME,
		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::errors::position	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; the FLOAT8 data type in PostgreSQL)

See also: to_float; to_short; to_int; to_long

Parameters

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

◆ to_float() [1/2]

float pq::result::to_float	(	const int	ROW,
		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::errors::position	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 (the FLOAT4 data type in PostgreSQL)

See also: to_double; to_short; to_int; to_long

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.)
null_fallback	The value to revert to instead of throwing the `std::length_error` exception if the binary column data is `NULL`

◆ to_float() [2/2]

float pq::result::to_float	(	const int	ROW,
		const char *	COL_NAME,
		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::errors::position	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 (the FLOAT4 data type in PostgreSQL)

See also: to_double; to_short; to_int; to_long

Parameters

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

◆ to_int() [1/2]

int32_t pq::result::to_int	(	const int	ROW,
		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::errors::position	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; the INT4 data type in PostgreSQL)

See also: to_double; to_float; to_short; to_long

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.)
null_fallback	The value to revert to instead of throwing the `std::length_error` exception if the binary column data is `NULL`

◆ to_int() [2/2]

int32_t pq::result::to_int	(	const int	ROW,
		const char *	COL_NAME,
		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::errors::position	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; the INT4 data type in PostgreSQL)

See also: to_double; to_float; to_short; to_long

Parameters

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

◆ to_long() [1/2]

int64_t pq::result::to_long	(	const int	ROW,
		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::errors::position	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; the INT8 data type in PostgreSQL)

See also: to_double; to_float; to_short; to_int

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.)
null_fallback	The value to revert to instead of throwing the `std::length_error` exception if the binary column data is `NULL`

◆ to_long() [2/2]

int64_t pq::result::to_long	(	const int	ROW,
		const char *	COL_NAME,
		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::errors::position	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; the INT8 data type in PostgreSQL)

See also: to_double; to_float; to_short; to_int

Parameters

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

◆ to_short() [1/2]

int16_t pq::result::to_short	(	const int	ROW,
		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::errors::position	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; the INT2 data type in PostgreSQL)

See also: to_double; to_float; to_int; to_long

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.)
null_fallback	The value to revert to instead of throwing the `std::length_error` exception if the binary column data is `NULL`

◆ to_short() [2/2]

int16_t pq::result::to_short	(	const int	ROW,
		const char *	COL_NAME,
		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::errors::position	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; the INT2 data type in PostgreSQL)

See also: to_double; to_float; to_int; to_long

Parameters

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

◆ to_string() [1/2]

std::string pq::result::to_string	(	const int	ROW,
		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::errors::position	If the column number is out of range

Returns: pointer to ASCIIZ string (a.k.a., cstring in PostgreSQL, which is used internally for the CHAR[n], VARCHAR, and TEXT data types)

See also: to_char; to_cstr; to_string_view

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.)
null_fallback	The value to revert to instead of throwing the `std::length_error` exception if the binary column data is `NULL`

◆ to_string() [2/2]

std::string pq::result::to_string	(	const int	ROW,
		const char *	COL_NAME,
		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::errors::position	If the column number is out of range

Returns: pointer to ASCIIZ string (a.k.a., cstring in PostgreSQL, which is used internally for the CHAR[n], VARCHAR, and TEXT data types)

See also: to_char; to_cstr; to_string_view

Parameters

ROW	Row number (0 = first row; negative values count backward from the end, wherein -1 = last, -2 = penultimate, etc.)
COL_NAME	ASCIIZ column name (case-insensitive)
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() [1/2]

std::string_view pq::result::to_string_view	(	const int	ROW,
		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::errors::position	If the column number is out of range

Returns: pointer to ASCIIZ string (a.k.a., cstring in PostgreSQL, which is used internally for the CHAR[n], VARCHAR, and TEXT data types)

See also: to_char; to_cstr; to_string

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.)
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() [2/2]

std::string_view pq::result::to_string_view	(	const int	ROW,
		const char *	COL_NAME,
		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::errors::position	If the column number is out of range

Returns: pointer to ASCIIZ string (a.k.a., cstring in PostgreSQL, which is used internally for the CHAR[n], VARCHAR, and TEXT data types)

See also: to_char; to_cstr; to_string

Parameters

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

◆ visit()

row pq::result::visit ( const int ROW )

inlinenoexcept

Obtain a direct reference to the specified row (0 = first row), without altering the current row position.

Returns: The row as a pq::result::row object (that references the column data internally instead of making copies)

See also: at; curr; current_row; final; first; seek; getvalue; last; next; prev; reset

Parameters

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

◆ 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.)

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

Parameters

source Same class, but a different object

◆ operator[]()

row pq::result::operator[] ( const int ROW )

inline

Array-style access to rows. The first row is at index 0.

Exceptions

pq::errors::position If the current row number is out of range

Returns: The row as a pq::result::row object (that references the column data internally instead of making copies)

See also: at; visit

Parameters

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

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

pq/result

Classes

Public Member Functions

Static Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ result()

◆ ~result()

Member Function Documentation

◆ _handle()

◆ _to_strict()

◆ at() [1/2]

◆ at() [2/2]

◆ binaryTuples()

◆ cmdStatus()

◆ cmdTuples()

◆ cmdTuples_stoi()

◆ cmdTuples_stol()

◆ cmdTuples_stoll()

◆ curr()

◆ current_row()

◆ fformat() [1/2]

◆ fformat() [2/2]

◆ final()

◆ first()

◆ fmod() [1/2]

◆ fmod() [2/2]

◆ fname() [1/2]

◆ fname() [2/2]

◆ fnumber()

◆ fsize() [1/2]

◆ fsize() [2/2]

◆ ftable() [1/2]

◆ ftable() [2/2]

◆ ftablecol() [1/2]

◆ ftablecol() [2/2]

◆ ftype() [1/2]

◆ ftype() [2/2]

◆ getisnull() [1/2]

◆ getisnull() [2/2]

◆ getlength() [1/2]

◆ getlength() [2/2]

◆ getvalue() [1/2]

◆ getvalue() [2/2]

◆ last()

◆ next()

◆ nfields()

◆ nparams()

◆ ntuples()

◆ oidStatus()

◆ oidValue()

◆ paramtype()

◆ prev()

◆ print()

◆ reset()

◆ resultErrorField()

◆ resultErrorMessage()

◆ resStatus() [1/2]

◆ resStatus() [2/2]

◆ resultStatus()

◆ resultVerboseErrorMessage()

◆ seek()

◆ to_bool() [1/2]

◆ to_bool() [2/2]

◆ to_char() [1/2]

◆ to_char() [2/2]

◆ to_cstr() [1/2]

◆ to_cstr() [2/2]

◆ to_double() [1/2]

◆ to_double() [2/2]

◆ to_float() [1/2]

◆ to_float() [2/2]

◆ to_int() [1/2]

◆ to_int() [2/2]

◆ to_long() [1/2]

◆ to_long() [2/2]

◆ to_short() [1/2]

◆ to_short() [2/2]

◆ to_string() [1/2]

◆ to_string() [2/2]

◆ to_string_view() [1/2]