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

#include <pq/result>

Collaboration diagram for pq::result::row:

Public Member Functions
	row (pq::result *_result, int ROW)
	Constructor.

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

char *	at (const char *COL_NAME)
	Obtain column data.

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

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

int	current_row () noexcept
	Obtain the row number (0 = first row) that this row object references.

bool	exists () noexcept
	Indicates whether this is a valid row (same as the operator const bool() method).

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.

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 char *COL_NAME)
	Find out whether the current row's specified column is NULL in the database.

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

size_t	getlength (const char *COL_NAME)
	Obtain the length of the data at the specified column.

size_t	getlength (const int COL)
	Obtain the length of the data at the specified column.

char *	getvalue (const char *COL_NAME)
	Obtain column data.

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

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

	operator const bool () noexcept
	Indicates whether this is a valid row (same as the exists() method).

const char *	operator[] (const char *COL_NAME)
	Array-style access to columns by name. Names are case-sensitive, and PostgreSQL normally presents all the letters in lower-case.

const char *	operator[] (const int COL)
	Array-style access to columns. The first column is at index 0.

bool	to_bool (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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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).

Detailed Description

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.

Author: Randolf Richardson

Version: 1.00

History

2025-Mar-16 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");
    pq::row row = res.first();
  } 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

◆ row()

pq::result::row::row	(	pq::result *	_result,
		int	ROW )

inline

Constructor.

Parameters

_result	Reference to pq::result source
ROW	Row number

◆ ~row()

pq::result::row::~row ( )

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

◆ at() [1/2]

char * pq::result::row::at ( const int COL )

inline

Obtain column data.

Exceptions

pq::errors::position 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::row::at ( const char * COL_NAME )

inline

Obtain column data.

Exceptions

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

Returns: Pointer to raw column data

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

Parameters

COL_NAME ASCIIZ column name (case-insensitive)

◆ binaryTuples()

bool pq::result::row::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

◆ current_row()

int pq::result::row::current_row ( )

inlinenoexcept

Obtain the row number (0 = first row) that this row object references.

Returns: Row number

◆ exists()

bool pq::result::row::exists ( )

inlinenoexcept

Indicates whether this is a valid row (same as the operator const bool() method).

#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");
    std::cout << "Row exists? "
              << (res.first().exists() ? "Yes" : "No")
              << std::endl;
  } catch (pq::errors& e) {
    std::cout << e << std::endl;
    return EXIT_FAILURE;
  }
  return EXIT_SUCCESS;
} // -x- int main -x-

Returns: TRUE = this row exists
FALSE = this row doesn't exist

See also: operator const bool()

◆ fformat() [1/2]

int pq::result::row::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::row::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)

◆ fmod() [1/2]

int pq::result::row::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::row::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::row::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::row::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::row::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::row::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::row::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::row::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::row::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::row::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::row::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::row::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::row::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::row::getisnull ( const int COL )

inlineLIBPQ

Find out whether the current row's specified 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

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::row::getisnull ( const char * COL_NAME )

inline

Find out whether the current row's specified 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

COL_NAME ASCIIZ column name (case-insensitive)

◆ getlength() [1/2]

size_t pq::result::row::getlength ( const int COL )

inlineLIBPQ

Obtain the length of the data at the specified column.

Exceptions

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

Returns: Length of column's data

See also: fsize; getisnull; getvalue

Parameters

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::row::getlength ( const char * COL_NAME )

inline

Obtain the length of the data at the specified column.

Exceptions

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

Returns: Length of column's data

See also: fsize; getisnull; getvalue

Parameters

COL_NAME ASCIIZ column name (case-insensitive)

◆ getvalue() [1/2]

char * pq::result::row::getvalue ( const int COL )

inlineLIBPQ

Obtain column data.

Exceptions

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

Returns: Pointer to raw column data

See also: at; getisnull; getlength

Parameters

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::row::getvalue ( const char * COL_NAME )

inline

Obtain column data.

Exceptions

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

Returns: Pointer to raw column data

See also: at; getisnull; getlength

Parameters

COL_NAME ASCIIZ column name (case-insensitive)

◆ nfields()

uint pq::result::row::nfields ( )

inlinenoexceptLIBPQ

Obtain the total number of columns (fields).

Returns: Quantity of columns

See also: col_name

◆ to_bool() [1/2]

bool pq::result::row::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::errors::position	If the column number is out of range

Returns: boolean (the BOOL data type in PostgreSQL)

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

bool pq::result::row::to_bool	(	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

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::row::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::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

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::row::to_char	(	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

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::row::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::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

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::row::to_cstr	(	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

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::row::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::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 (the FLOAT8 data type in PostgreSQL)

See also: to_float; to_short; to_int; to_long

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

double pq::result::row::to_double	(	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 (the FLOAT8 data type in PostgreSQL)

See also: to_float; to_short; to_int; to_long

Parameters

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::row::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::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

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::row::to_float	(	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

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::row::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::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

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::row::to_int	(	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

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::row::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::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

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::row::to_long	(	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

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::row::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::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

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::row::to_short	(	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

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::row::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::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

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::row::to_string	(	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

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::row::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::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

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::row::to_string_view	(	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

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`

◆ operator const bool()

pq::result::row::operator const bool ( )

inlinenoexcept

Indicates whether this is a valid row (same as the exists() method).

#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");
    std::cout << "Row exists? "
              << (res.first() ? "Yes" : "No")
              << std::endl;
  } catch (pq::errors& e) {
    std::cout << e << std::endl;
    return EXIT_FAILURE;
  }
  return EXIT_SUCCESS;
} // -x- int main -x-

Returns: TRUE = this row exists
FALSE = this row doesn't exist

See also: exists

◆ operator[]() [1/2]

const char * pq::result::row::operator[] ( const int COL )

inline

Array-style access to columns. The first column is at index 0.

Exceptions

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

Returns: Pointer to raw column data, or nullptr if column data is NULL.

See also: at; visit

Parameters

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

◆ operator[]() [2/2]

const char * pq::result::row::operator[] ( const char * COL_NAME )

inline

Array-style access to columns by name. Names are case-sensitive, and PostgreSQL normally presents all the letters in lower-case.

Exceptions

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

Returns: Pointer to raw column data, or nullptr if column data is NULL.

See also: at; visit

Parameters

COL_NAME ASCIIZ column name (case-sensitive)

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

pq/result

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ row()

◆ ~row()

Member Function Documentation

◆ at() [1/2]

◆ at() [2/2]

◆ binaryTuples()

◆ current_row()

◆ exists()

◆ fformat() [1/2]

◆ fformat() [2/2]

◆ 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]

◆ nfields()

◆ 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]

◆ to_string_view() [2/2]

◆ operator const bool()

◆ operator[]() [1/2]

◆ operator[]() [2/2]