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 = 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_type * | data () 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
binarystring & | operator= (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.

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 = const value_type *

## const_reference

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

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

## value_type

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

## Constructor & Destructor Documentation

## binarystring() [1/4]

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

default

## binarystring() [2/4]

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

## binarystring() [3/4]

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

explicit

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

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

noexcept

Unescaped field contents.

Referenced by pqxx::connection_base::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()

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

noexcept

## operator=()

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

## operator==()

bool pqxx::binarystring::operator== | ( | const binarystring & | 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.

Referenced by pqxx::connection_base::quote().

## str()

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

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

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

- binarystring.hxx
- binarystring.cxx