libpqxx  7.0.5
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 = value_type const &
 
using const_pointer = value_type const *
 
using const_iterator = const_pointer
 
using const_reverse_iterator = std::reverse_iterator< const_iterator >
 

Public Member Functions

 binarystring (binarystring const &)=default
 
 binarystring (field const &)
 Read and unescape bytea field. More...
 
 binarystring (std::string_view)
 Copy binary data from std::string_view. More...
 
 binarystring (void const *, 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
 
value_type const * data () const noexcept
 Unescaped field contents. More...
 
const_reference operator[] (size_type i) const noexcept
 
PQXX_PURE bool operator== (binarystring const &) const noexcept
 
bool operator!= (binarystring const &rhs) const noexcept
 
binarystringoperator= (binarystring const &)
 
const_reference at (size_type) const
 Index contained string, checking for valid index. More...
 
void swap (binarystring &)
 Swap contents with other binarystring. More...
 
char const * get () const noexcept
 Raw character buffer (no terminating zero is added). More...
 
std::string_view view () const noexcept
 Read contents as a std::string_view. 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 null bytes, they're just like any other byte value. So don't assume that it's safe to treat the contents as a C-style string unless you've made sure of it 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.

Warning
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 ( binarystring const &  )
default

◆ binarystring() [2/4]

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

Read and unescape bytea field.

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

Parameters
Fthe field to read; must be a bytea field

References pqxx::field::c_str().

◆ binarystring() [3/4]

pqxx::binarystring::binarystring ( std::string_view  s)
explicit

Copy binary data from std::string_view.

◆ binarystring() [4/4]

pqxx::binarystring::binarystring ( void const *  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
noexcept

◆ begin()

const_iterator pqxx::binarystring::begin ( ) const
noexcept

◆ cbegin()

const_iterator pqxx::binarystring::cbegin ( ) const
noexcept

◆ cend()

const_iterator pqxx::binarystring::cend ( ) const
noexcept

◆ crbegin()

const_reverse_iterator pqxx::binarystring::crbegin ( ) const

◆ crend()

const_reverse_iterator pqxx::binarystring::crend ( ) const

◆ data()

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

Unescaped field contents.

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

◆ empty()

bool pqxx::binarystring::empty ( ) const
noexcept

◆ end()

const_iterator pqxx::binarystring::end ( ) const
noexcept

◆ front()

const_reference pqxx::binarystring::front ( ) const
noexcept

◆ get()

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

Raw character buffer (no terminating zero is added).

Warning
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
noexcept

Size of converted string in bytes.

◆ operator!=()

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

◆ operator=()

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

Referenced by operator==().

◆ operator==()

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

References data(), operator=(), and size().

◆ operator[]()

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

◆ rbegin()

const_reverse_iterator pqxx::binarystring::rbegin ( ) const

◆ rend()

const_reverse_iterator pqxx::binarystring::rend ( ) const

◆ size()

size_type pqxx::binarystring::size ( ) const
noexcept

Size of converted string in bytes.

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

◆ str()

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

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

This creates and returns a new string object. Don't call this repeatedly; 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.

◆ view()

std::string_view pqxx::binarystring::view ( ) const
noexcept

Read contents as a std::string_view.


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