libpqxx  7.2.0
binarystring.hxx
1 /* Representation for raw, binary data.
2  *
3  * DO NOT INCLUDE THIS FILE DIRECTLY; include pqxx/binarystring instead.
4  *
5  * Copyright (c) 2000-2020, Jeroen T. Vermeulen.
6  *
7  * See COPYING for copyright license. If you did not receive a file called
8  * COPYING with this source code, please notify the distributor of this
9  * mistake, or contact the author.
10  */
11 #ifndef PQXX_H_BINARYSTRING
12 #define PQXX_H_BINARYSTRING
13 
14 #include "pqxx/compiler-public.hxx"
15 #include "pqxx/internal/compiler-internal-pre.hxx"
16 
17 #include <memory>
18 #include <string>
19 #include <string_view>
20 
21 #include "pqxx/result.hxx"
22 #include "pqxx/strconv.hxx"
23 
24 namespace pqxx
25 {
26 class binarystring;
27 template<> struct string_traits<binarystring>;
28 
29 
31 
56 class PQXX_LIBEXPORT binarystring
57 {
58 public:
59  using char_type = unsigned char;
60  using value_type = std::char_traits<char_type>::char_type;
61  using size_type = std::size_t;
62  using difference_type = long;
63  using const_reference = value_type const &;
64  using const_pointer = value_type const *;
66  using const_reverse_iterator = std::reverse_iterator<const_iterator>;
67 
68  binarystring(binarystring const &) = default;
69 
71 
75  explicit binarystring(field const &);
76 
78 
81  explicit binarystring(std::string_view);
82 
84  binarystring(void const *, std::size_t);
85 
87  binarystring(std::shared_ptr<value_type> ptr, size_type size) :
88  m_buf{std::move(ptr)}, m_size{size}
89  {}
90 
92  [[nodiscard]] size_type size() const noexcept { return m_size; }
94  [[nodiscard]] size_type length() const noexcept { return size(); }
95  [[nodiscard]] bool empty() const noexcept { return size() == 0; }
96 
97  [[nodiscard]] const_iterator begin() const noexcept { return data(); }
98  [[nodiscard]] const_iterator cbegin() const noexcept { return begin(); }
99  [[nodiscard]] const_iterator end() const noexcept { return data() + m_size; }
100  [[nodiscard]] const_iterator cend() const noexcept { return end(); }
101 
102  [[nodiscard]] const_reference front() const noexcept { return *begin(); }
103  [[nodiscard]] const_reference back() const noexcept
104  {
105  return *(data() + m_size - 1);
106  }
107 
108  [[nodiscard]] const_reverse_iterator rbegin() const
109  {
110  return const_reverse_iterator{end()};
111  }
112  [[nodiscard]] const_reverse_iterator crbegin() const { return rbegin(); }
113  [[nodiscard]] const_reverse_iterator rend() const
114  {
115  return const_reverse_iterator{begin()};
116  }
117  [[nodiscard]] const_reverse_iterator crend() const { return rend(); }
118 
120  [[nodiscard]] value_type const *data() const noexcept { return m_buf.get(); }
121 
122  [[nodiscard]] const_reference operator[](size_type i) const noexcept
123  {
124  return data()[i];
125  }
126 
127  [[nodiscard]] PQXX_PURE bool operator==(binarystring const &) const noexcept;
128  [[nodiscard]] bool operator!=(binarystring const &rhs) const noexcept
129  {
130  return not operator==(rhs);
131  }
132 
133  binarystring &operator=(binarystring const &);
134 
136  const_reference at(size_type) const;
137 
139  void swap(binarystring &);
140 
142 
145  [[nodiscard]] char const *get() const noexcept
146  {
147  return reinterpret_cast<char const *>(m_buf.get());
148  }
149 
151  [[nodiscard]] std::string_view view() const noexcept
152  {
153  return std::string_view(get(), size());
154  }
155 
157 
162  [[nodiscard]] std::string str() const;
163 
164 private:
165  std::shared_ptr<value_type> m_buf;
166  size_type m_size{0};
167 };
168 
169 
170 // TODO: Should binarystring have a default-constructed null value?
171 template<> struct nullness<binarystring> : no_null<binarystring>
172 {};
173 
174 
176 
183 template<> struct string_traits<binarystring>
184 {
185  static std::size_t size_buffer(binarystring const &value) noexcept
186  {
187  return internal::size_esc_bin(std::size(value));
188  }
189 
190  static zview to_buf(char *begin, char *end, binarystring const &value)
191  {
192  auto const value_end{into_buf(begin, end, value)};
193  return zview{begin, value_end - begin - 1};
194  }
195 
196  static char *into_buf(char *begin, char *end, binarystring const &value)
197  {
198  auto const budget{size_buffer(value)};
199  if (static_cast<std::size_t>(end - begin) < budget)
200  throw conversion_overrun{
201  "Not enough buffer space to escape binary data."};
202  internal::esc_bin(value.view(), begin);
203  return begin + budget;
204  }
205 
206  static binarystring from_string(std::string_view text)
207  {
208  auto const size{pqxx::internal::size_unesc_bin(std::size(text))};
209  std::shared_ptr<unsigned char> buf{
210  new unsigned char[size], [](unsigned char const *x) { delete[] x; }};
211  pqxx::internal::unesc_bin(text, reinterpret_cast<std::byte *>(buf.get()));
212  return binarystring{std::move(buf), size};
213  }
214 };
215 } // namespace pqxx
216 
217 #include "pqxx/internal/compiler-internal-post.hxx"
218 #endif
value_type const * data() const noexcept
Unescaped field contents.
Definition: binarystring.hxx:120
const_iterator end() const noexcept
Definition: binarystring.hxx:99
Traits class for use in string conversions.
Definition: strconv.hxx:126
const_iterator begin() const noexcept
Definition: binarystring.hxx:97
const_reference operator[](size_type i) const noexcept
Definition: binarystring.hxx:122
void esc_bin(std::string_view binary_data, char buffer[]) noexcept
Hex-escape binary data into a buffer.
Definition: util.cxx:123
static char * into_buf(char *begin, char *end, binarystring const &value)
Definition: binarystring.hxx:196
const_reverse_iterator rbegin() const
Definition: binarystring.hxx:108
const_iterator cend() const noexcept
Definition: binarystring.hxx:100
std::size_t size_type
Definition: binarystring.hxx:61
std::reverse_iterator< const_iterator > const_reverse_iterator
Definition: binarystring.hxx:66
Binary data corresponding to PostgreSQL&#39;s "BYTEA" binary-string type.
Definition: binarystring.hxx:56
const_reference front() const noexcept
Definition: binarystring.hxx:102
static std::size_t size_buffer(binarystring const &value) noexcept
Definition: binarystring.hxx:185
The home of all libpqxx classes, functions, templates, etc.
Definition: array.hxx:25
static binarystring from_string(std::string_view text)
Definition: binarystring.hxx:206
Reference to a field in a result set.
Definition: field.hxx:33
const_reverse_iterator crend() const
Definition: binarystring.hxx:117
binarystring(std::shared_ptr< value_type > ptr, size_type size)
Efficiently wrap a buffer of binary data in a binarystring.
Definition: binarystring.hxx:87
size_type size() const noexcept
Size of converted string in bytes.
Definition: binarystring.hxx:92
std::char_traits< char_type >::char_type value_type
Definition: binarystring.hxx:60
const_reference back() const noexcept
Definition: binarystring.hxx:103
Marker-type wrapper: zero-terminated std::string_view.
Definition: zview.hxx:36
std::string_view view() const noexcept
Read contents as a std::string_view.
Definition: binarystring.hxx:151
long difference_type
Definition: binarystring.hxx:62
constexpr std::size_t size_unesc_bin(std::size_t escaped_bytes) noexcept
Compute binary size from the size of its escaped version.
Definition: util.hxx:307
unsigned char char_type
Definition: binarystring.hxx:59
Could not convert value to string: not enough buffer space.
Definition: except.hxx:185
const_reverse_iterator crbegin() const
Definition: binarystring.hxx:112
value_type const * const_pointer
Definition: binarystring.hxx:64
constexpr std::size_t size_esc_bin(std::size_t binary_bytes) noexcept
Compute buffer size needed to escape binary data for use as a BYTEA.
Definition: util.hxx:298
std::size_t size_buffer(TYPE const &value) noexcept
Estimate how much buffer space is needed to represent value as a string.
Definition: strconv.hxx:321
const_reverse_iterator rend() const
Definition: binarystring.hxx:113
const_pointer const_iterator
Definition: binarystring.hxx:65
size_type length() const noexcept
Size of converted string in bytes.
Definition: binarystring.hxx:94
const_iterator cbegin() const noexcept
Definition: binarystring.hxx:98
Nullness traits describing a type which does not have a null value.
Definition: strconv.hxx:108
bool empty() const noexcept
Definition: binarystring.hxx:95
void unesc_bin(std::string_view escaped_data, std::byte buffer[])
Reconstitute binary data from its escaped version.
Definition: util.cxx:153
bool operator!=(binarystring const &rhs) const noexcept
Definition: binarystring.hxx:128
static zview to_buf(char *begin, char *end, binarystring const &value)
Definition: binarystring.hxx:190
Traits describing a type&#39;s "null value," if any.
Definition: strconv.hxx:86
value_type const & const_reference
Definition: binarystring.hxx:63