pqxx::binarystring Class Reference

Binary data corresponding to PostgreSQL's "BYTEA" binary-string type. More...

#include <binarystring.hxx>

Public Types

using char_type = unsigned char
using value_type = std::char_traits< char_type >::char_type
using size_type = size_t
using difference_type = long
using const_reference = const value_type &
using const_pointer = const value_type *
using const_iterator = const_pointer
using const_reverse_iterator = std::reverse_iterator< const_iterator >

Public Member Functions

 binarystring (const binarystring &)=default
 binarystring (const field &)
 Read and unescape bytea field. More...
 binarystring (const std::string &)
 Copy binary data from std::string. More...
 binarystring (const void *, size_t)
 Copy binary data of given length straight out of memory. More...
size_type size () const noexcept
 Size of converted string in bytes. More...
size_type length () const noexcept
 Size of converted string in bytes. More...
bool empty () const noexcept
const_iterator begin () const noexcept
const_iterator cbegin () const noexcept
const_iterator end () const noexcept
const_iterator cend () const noexcept
const_reference front () const noexcept
const_reference back () const noexcept
const_reverse_iterator rbegin () const
const_reverse_iterator crbegin () const
const_reverse_iterator rend () const
const_reverse_iterator crend () const
const value_typedata () const noexcept
 Unescaped field contents. More...
const_reference operator[] (size_type i) const noexcept
PQXX_PURE bool operator== (const binarystring &) const noexcept
bool operator!= (const binarystring &rhs) const noexcept
binarystringoperator= (const binarystring &)
const_reference at (size_type) const
 Index contained string, checking for valid index. More...
void swap (binarystring &)
 Swap contents with other binarystring. More...
const char * get () const noexcept
 Raw character buffer (no terminating zero is added) More...
std::string str () const
 Read as regular C++ string (may include null characters) More...

Detailed Description

Binary data corresponding to PostgreSQL's "BYTEA" binary-string type.

This class represents a binary string as stored in a field of type bytea. The raw value returned by a bytea field contains escape sequences for certain characters, which are filtered out by binarystring.

Internally a binarystring is zero-terminated, but it may also contain zero bytes, just like any other byte value. So don't assume that it can be treated as a C-style string unless you've made sure of this yourself.

The binarystring retains its value even if the result it was obtained from is destroyed, but it cannot be copied or assigned.

To convert the other way, i.e. from a raw series of bytes to a string suitable for inclusion as bytea values in your SQL, use the transaction's esc_raw() functions.

This class is implemented as a reference-counting smart pointer. Copying, swapping, and destroying binarystring objects that refer to the same underlying data block is not thread-safe. If you wish to pass binarystrings around between threads, make sure that each of these operations is protected against concurrency with similar operations on the same object, or other objects pointing to the same data block.

Member Typedef Documentation

◆ char_type

using pqxx::binarystring::char_type = unsigned char

◆ const_iterator

◆ const_pointer

◆ const_reference

◆ const_reverse_iterator

◆ difference_type

◆ size_type

◆ value_type

Constructor & Destructor Documentation

◆ binarystring() [1/4]

pqxx::binarystring::binarystring ( const binarystring )

◆ binarystring() [2/4]

pqxx::binarystring::binarystring ( const field F)

Read and unescape bytea field.

The field will be zero-terminated, even if the original bytea field isn't.

Fthe field to read; must be a bytea field

◆ binarystring() [3/4]

pqxx::binarystring::binarystring ( const std::string &  s)

Copy binary data from std::string.

◆ binarystring() [4/4]

pqxx::binarystring::binarystring ( const void *  binary_data,
size_t  len 

Copy binary data of given length straight out of memory.

Member Function Documentation

◆ at()

pqxx::binarystring::const_reference pqxx::binarystring::at ( size_type  n) const

Index contained string, checking for valid index.

References data(), and pqxx::to_string().

◆ back()

const_reference pqxx::binarystring::back ( ) const

◆ begin()

const_iterator pqxx::binarystring::begin ( ) const

◆ cbegin()

const_iterator pqxx::binarystring::cbegin ( ) const

◆ cend()

const_iterator pqxx::binarystring::cend ( ) const

◆ crbegin()

const_reverse_iterator pqxx::binarystring::crbegin ( ) const

◆ crend()

const_reverse_iterator pqxx::binarystring::crend ( ) const

◆ data()

const value_type* pqxx::binarystring::data ( ) const

Unescaped field contents.

Referenced by at(), operator==(), and pqxx::connection_base::quote().

◆ empty()

bool pqxx::binarystring::empty ( ) const

◆ end()

const_iterator pqxx::binarystring::end ( ) const

◆ front()

const_reference pqxx::binarystring::front ( ) const

◆ get()

const char* pqxx::binarystring::get ( ) const

Raw character buffer (no terminating zero is added)

No terminating zero is added! If the binary data did not end in a null character, you will not find one here.

◆ length()

size_type pqxx::binarystring::length ( ) const

Size of converted string in bytes.

◆ operator!=()

bool pqxx::binarystring::operator!= ( const binarystring rhs) const

◆ operator=()

pqxx::binarystring & pqxx::binarystring::operator= ( const binarystring rhs)

◆ operator==()

bool pqxx::binarystring::operator== ( const binarystring rhs) const

References data(), and size().

◆ operator[]()

const_reference pqxx::binarystring::operator[] ( size_type  i) const

◆ rbegin()

const_reverse_iterator pqxx::binarystring::rbegin ( ) const

◆ rend()

const_reverse_iterator pqxx::binarystring::rend ( ) const

◆ size()

size_type pqxx::binarystring::size ( ) const

Size of converted string in bytes.

Referenced by operator==(), and pqxx::connection_base::quote().

◆ str()

std::string pqxx::binarystring::str ( ) const

Read as regular C++ string (may include null characters)

libpqxx releases before 3.1 stored the string and returned a reference to it. This is no longer the case! It now creates and returns a new string object. Avoid repeated use of this function; retrieve your string once and keep it in a local variable. Also, do not expect to be able to compare the string's address to that of an earlier invocation.

◆ swap()

void pqxx::binarystring::swap ( binarystring rhs)

Swap contents with other binarystring.

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