pqxx::binarystring Class Reference
String-escaping functions

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.
| binarystring (std::string_view)
| Copy binary data from std::string_view on binary data.
| binarystring (void const *, std::size_t)
| Copy binary data of given length straight out of memory.
| binarystring (std::shared_ptr< value_type > ptr, size_type size)
| Efficiently wrap a buffer of binary data in a `binarystring`.
size_type | size () const noexcept
| Size of converted string in bytes.
size_type | length () const noexcept
| Size of converted string in bytes.
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.
const_reference | operator[] (size_type i) const noexcept
PQXX_PURE bool | operator== (binarystring const &) const noexcept
bool | operator!= (binarystring const &rhs) const noexcept
binarystring & | operator= (binarystring const &)
const_reference | at (size_type) const
| Index contained string, checking for valid index.
void | swap (binarystring &)
| Swap contents with other binarystring.
char const * | get () const noexcept
| Raw character buffer (no terminating zero is added).
std::string_view | view () const noexcept
| Read contents as a std::string_view.
std::string | str () const
| Read as regular C++ string (may include null characters).
std::byte const * | bytes () const
| Access data as a pointer to `std::byte`.
std::basic_string_view< std::byte > | bytes_view () const
| Read data as a `std::basic_string_view<std::byte>`.

## Detailed Description

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

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

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

using pqxx::binarystring::const_iterator = const_pointer

## const_pointer

using pqxx::binarystring::const_pointer = value_type const *

## const_reference

using pqxx::binarystring::const_reference = value_type const &

## const_reverse_iterator

using pqxx::binarystring::const_reverse_iterator = std::reverse_iterator<const_iterator>

## difference_type

using pqxx::binarystring::difference_type = long

## size_type

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

## value_type

using pqxx::binarystring::value_type = std::char_traits<char_type>::char_type

## Constructor & Destructor Documentation

## binarystring() [1/5]

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

default

## binarystring() [2/5]

PQXX_COLD 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

  F | the field to read; must be a bytea field

References pqxx::field::c_str(), data(), and pqxx::internal::pq::pqfreemem().

## binarystring() [3/5]

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

explicit

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 pqxx::to_string().

## back()

const_reference pqxx::binarystring::back | ( |  | ) | const

noexcept

## begin()

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

noexcept

## 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::connection::quote(), and pqxx::transaction_base::quote().

## 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 binarystring().

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

## operator==()

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

noexcept

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

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

References swap().

Referenced by swap().

## view()

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

noexcept

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:

- binarystring.hxx
- binarystring.cxx