libpqxx  7.7.3
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 = std::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 on binary data. More...
 binarystring (void const *, std::size_t)
 Copy binary data of given length straight out of memory. More...
 binarystring (std::shared_ptr< value_type > ptr, size_type size)
 Efficiently wrap a buffer of binary data in a binarystring. 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...
std::byte const * bytes () const
 Access data as a pointer to std::byte. More...
std::basic_string_view< std::byte > bytes_view () const
 Read data as a std::basic_string_view<std::byte>. More...

Detailed Description

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

Use std::basic_string<std::byte> and std::basic_string_view<std::byte> for binary data. In C++20 or better, any contiguous_range of std::byte will do.

This class represents a binary string as stored in a field of type bytea.

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.

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

To include a binarystring value in an SQL query, escape and quote it using the transaction's quote_raw function.

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

using pqxx::binarystring::size_type = std::size_t

◆ value_type

Constructor & Destructor Documentation

◆ binarystring() [1/5]

pqxx::binarystring::binarystring ( binarystring const &  )

◆ binarystring() [2/5]

PQXX_COLD pqxx::binarystring::binarystring ( field const &  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

References pqxx::field::c_str().

◆ binarystring() [3/5]

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

Copy binary data from std::string_view on binary data.

This is inefficient in that it copies the data to a buffer allocated on the heap.

◆ binarystring() [4/5]

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

Copy binary data of given length straight out of memory.

◆ binarystring() [5/5]

pqxx::binarystring::binarystring ( std::shared_ptr< value_type ptr,
size_type  size 

Efficiently wrap a buffer of binary data in a binarystring.

Member Function Documentation

◆ at()

PQXX_COLD 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

◆ bytes()

std::byte const* pqxx::binarystring::bytes ( ) const

Access data as a pointer to std::byte.

◆ bytes_view()

std::basic_string_view<std::byte> pqxx::binarystring::bytes_view ( ) const

Read data as a std::basic_string_view<std::byte>.

Referenced by pqxx::transaction_base::quote(), and pqxx::connection::quote().

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

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

Unescaped field contents.

Referenced by at(), and operator==().

◆ empty()

bool pqxx::binarystring::empty ( ) const

◆ end()

const_iterator pqxx::binarystring::end ( ) const

◆ front()

const_reference pqxx::binarystring::front ( ) const

◆ get()

char const* 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!= ( binarystring const &  rhs) const

◆ operator=()

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

Referenced by operator==().

◆ operator==()

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

References data(), operator=(), 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==().

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

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

Swap contents with other binarystring.

◆ view()

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

Read contents as a std::string_view.

Referenced by pqxx::string_traits< binarystring >::into_buf().

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