libpqxx  7.7.4
binarystring.hxx
1 /* Deprecated representation for raw, binary data.
2  *
3  * DO NOT INCLUDE THIS FILE DIRECTLY; include pqxx/binarystring instead.
4  *
5  * Copyright (c) 2000-2022, 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 #if !defined(PQXX_HEADER_PRE)
15 # error "Include libpqxx headers as <pqxx/header>, not <pqxx/header.hxx>."
16 #endif
17 
18 #include <memory>
19 #include <string>
20 #include <string_view>
21 
22 #include "pqxx/result.hxx"
23 #include "pqxx/strconv.hxx"
24 
25 namespace pqxx
26 {
27 class binarystring;
28 template<> struct string_traits<binarystring>;
29 
30 
32 
58 class PQXX_LIBEXPORT binarystring
59 {
60 public:
61  using char_type = unsigned char;
62  using value_type = std::char_traits<char_type>::char_type;
63  using size_type = std::size_t;
64  using difference_type = long;
65  using const_reference = value_type const &;
66  using const_pointer = value_type const *;
68  using const_reverse_iterator = std::reverse_iterator<const_iterator>;
69 
70  [[deprecated("Use std::byte for binary data.")]] binarystring(
71  binarystring const &) = default;
72 
74 
78  [[deprecated("Use std::byte for binary data.")]] explicit binarystring(
79  field const &);
80 
82 
85  [[deprecated("Use std::byte for binary data.")]] explicit binarystring(
86  std::string_view);
87 
89  [[deprecated("Use std::byte for binary data.")]] binarystring(
90  void const *, std::size_t);
91 
93  [[deprecated("Use std::byte for binary data.")]] binarystring(
94  std::shared_ptr<value_type> ptr, size_type size) :
95  m_buf{std::move(ptr)}, m_size{size}
96  {}
97 
99  [[nodiscard]] size_type size() const noexcept { return m_size; }
101  [[nodiscard]] size_type length() const noexcept { return size(); }
102  [[nodiscard]] bool empty() const noexcept { return size() == 0; }
103 
104  [[nodiscard]] const_iterator begin() const noexcept { return data(); }
105  [[nodiscard]] const_iterator cbegin() const noexcept { return begin(); }
106  [[nodiscard]] const_iterator end() const noexcept { return data() + m_size; }
107  [[nodiscard]] const_iterator cend() const noexcept { return end(); }
108 
109  [[nodiscard]] const_reference front() const noexcept { return *begin(); }
110  [[nodiscard]] const_reference back() const noexcept
111  {
112  return *(data() + m_size - 1);
113  }
114 
115  [[nodiscard]] const_reverse_iterator rbegin() const
116  {
117  return const_reverse_iterator{end()};
118  }
119  [[nodiscard]] const_reverse_iterator crbegin() const { return rbegin(); }
120  [[nodiscard]] const_reverse_iterator rend() const
121  {
122  return const_reverse_iterator{begin()};
123  }
124  [[nodiscard]] const_reverse_iterator crend() const { return rend(); }
125 
127  [[nodiscard]] value_type const *data() const noexcept { return m_buf.get(); }
128 
129  [[nodiscard]] const_reference operator[](size_type i) const noexcept
130  {
131  return data()[i];
132  }
133 
134  [[nodiscard]] PQXX_PURE bool operator==(binarystring const &) const noexcept;
135  [[nodiscard]] bool operator!=(binarystring const &rhs) const noexcept
136  {
137  return not operator==(rhs);
138  }
139 
140  binarystring &operator=(binarystring const &);
141 
143  const_reference at(size_type) const;
144 
146  void swap(binarystring &);
147 
149 
152  [[nodiscard]] char const *get() const noexcept
153  {
154  return reinterpret_cast<char const *>(m_buf.get());
155  }
156 
158  [[nodiscard]] std::string_view view() const noexcept
159  {
160  return std::string_view(get(), size());
161  }
162 
164 
169  [[nodiscard]] std::string str() const;
170 
172  [[nodiscard]] std::byte const *bytes() const
173  {
174  return reinterpret_cast<std::byte const *>(get());
175  }
176 
178  [[nodiscard]] std::basic_string_view<std::byte> bytes_view() const
179  {
180  return std::basic_string_view<std::byte>{bytes(), size()};
181  }
182 
183 private:
184  std::shared_ptr<value_type> m_buf;
185  size_type m_size{0};
186 };
187 
188 
189 template<> struct nullness<binarystring> : no_null<binarystring>
190 {};
191 
192 
194 
201 template<> struct string_traits<binarystring>
202 {
203  static std::size_t size_buffer(binarystring const &value) noexcept
204  {
205  return internal::size_esc_bin(std::size(value));
206  }
207 
208  static zview to_buf(char *begin, char *end, binarystring const &value)
209  {
210  return generic_to_buf(begin, end, value);
211  }
212 
213  static char *into_buf(char *begin, char *end, binarystring const &value)
214  {
215  auto const budget{size_buffer(value)};
216  if (internal::cmp_less(end - begin, budget))
217  throw conversion_overrun{
218  "Not enough buffer space to escape binary data."};
219  std::string_view text{value.view()};
221  return begin + budget;
222  }
223 
224  static binarystring from_string(std::string_view text)
225  {
226  auto const size{pqxx::internal::size_unesc_bin(std::size(text))};
227  std::shared_ptr<unsigned char> buf{
228  new unsigned char[size], [](unsigned char const *x) { delete[] x; }};
229  pqxx::internal::unesc_bin(text, reinterpret_cast<std::byte *>(buf.get()));
230 #include "pqxx/internal/ignore-deprecated-pre.hxx"
231  return binarystring{std::move(buf), size};
232 #include "pqxx/internal/ignore-deprecated-post.hxx"
233  }
234 };
235 } // namespace pqxx
236 #endif
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:413
std::basic_string_view< std::byte > bytes_view() const
Read data as a std::basic_string_view<std::byte>.
Definition: binarystring.hxx:178
The home of all libpqxx classes, functions, templates, etc.
Definition: array.hxx:26
value_type const & const_reference
Definition: binarystring.hxx:65
const_pointer const_iterator
Definition: binarystring.hxx:67
std::string_view view() const noexcept
Read contents as a std::string_view.
Definition: binarystring.hxx:158
std::byte const * bytes() const
Access data as a pointer to std::byte.
Definition: binarystring.hxx:172
const_iterator cend() const noexcept
Definition: binarystring.hxx:107
Traits class for use in string conversions.
Definition: strconv.hxx:154
const_iterator begin() const noexcept
Definition: binarystring.hxx:104
const_reverse_iterator crend() const
Definition: binarystring.hxx:124
Reference to a field in a result set.
Definition: field.hxx:34
value_type const * const_pointer
Definition: binarystring.hxx:66
binarystring(std::shared_ptr< value_type > ptr, size_type size)
Efficiently wrap a buffer of binary data in a binarystring.
Definition: binarystring.hxx:93
static char * into_buf(char *begin, char *end, binarystring const &value)
Definition: binarystring.hxx:213
const_reverse_iterator rend() const
Definition: binarystring.hxx:120
size_type length() const noexcept
Size of converted string in bytes.
Definition: binarystring.hxx:101
Nullness traits describing a type which does not have a null value.
Definition: strconv.hxx:114
void esc_bin(std::basic_string_view< std::byte > binary_data, char buffer[]) noexcept
Hex-escape binary data into a buffer.
Definition: util.cxx:126
std::reverse_iterator< const_iterator > const_reverse_iterator
Definition: binarystring.hxx:68
bool empty() const noexcept
Definition: binarystring.hxx:102
std::size_t size_type
Definition: binarystring.hxx:63
const_reverse_iterator rbegin() const
Definition: binarystring.hxx:115
const_iterator end() const noexcept
Definition: binarystring.hxx:106
Could not convert value to string: not enough buffer space.
Definition: except.hxx:194
unsigned char char_type
Definition: binarystring.hxx:61
const_reference front() const noexcept
Definition: binarystring.hxx:109
size_type size() const noexcept
Size of converted string in bytes.
Definition: binarystring.hxx:99
const_reference operator[](size_type i) const noexcept
Definition: binarystring.hxx:129
std::char_traits< char_type >::char_type value_type
Definition: binarystring.hxx:62
zview generic_to_buf(char *begin, char *end, TYPE const &value)
Implement string_traits<TYPE>::to_buf by calling into_buf.
Definition: strconv.hxx:442
value_type const * data() const noexcept
Unescaped field contents.
Definition: binarystring.hxx:127
Marker-type wrapper: zero-terminated std::string_view.
Definition: zview.hxx:37
const_reference back() const noexcept
Definition: binarystring.hxx:110
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:422
static std::size_t size_buffer(binarystring const &value) noexcept
Definition: binarystring.hxx:203
constexpr bool cmp_less(LEFT lhs, RIGHT rhs) noexcept
Same as std::cmp_less, or a workaround where that&#39;s not available.
Definition: util.hxx:66
std::size_t size_buffer(TYPE const &...value) noexcept
Estimate how much buffer space is needed to represent values as a string.
Definition: strconv.hxx:381
const_reverse_iterator crbegin() const
Definition: binarystring.hxx:119
void unesc_bin(std::string_view escaped_data, std::byte buffer[])
Reconstitute binary data from its escaped version.
Definition: util.cxx:158
Binary data corresponding to PostgreSQL&#39;s "BYTEA" binary-string type.
Definition: binarystring.hxx:58
bool operator!=(binarystring const &rhs) const noexcept
Definition: binarystring.hxx:135
static binarystring from_string(std::string_view text)
Definition: binarystring.hxx:224
static zview to_buf(char *begin, char *end, binarystring const &value)
Definition: binarystring.hxx:208
const_iterator cbegin() const noexcept
Definition: binarystring.hxx:105
Traits describing a type&#39;s "null value," if any.
Definition: strconv.hxx:92
std::basic_string_view< std::byte > binary_cast(TYPE const &data)
Cast binary data to a type that libpqxx will recognise as binary.
Definition: util.hxx:306
long difference_type
Definition: binarystring.hxx:64