libpqxx  7.6.1
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 #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 
57 class PQXX_LIBEXPORT binarystring
58 {
59 public:
60  using char_type = unsigned char;
61  using value_type = std::char_traits<char_type>::char_type;
62  using size_type = std::size_t;
63  using difference_type = long;
64  using const_reference = value_type const &;
65  using const_pointer = value_type const *;
67  using const_reverse_iterator = std::reverse_iterator<const_iterator>;
68 
69  [[deprecated("Use std::byte for binary data.")]] binarystring(
70  binarystring const &) = default;
71 
73 
77  [[deprecated("Use std::byte for binary data.")]] explicit binarystring(
78  field const &);
79 
81 
84  [[deprecated("Use std::byte for binary data.")]] explicit binarystring(
85  std::string_view);
86 
88  [[deprecated("Use std::byte for binary data.")]] binarystring(
89  void const *, std::size_t);
90 
92  [[deprecated("Use std::byte for binary data.")]] binarystring(
93  std::shared_ptr<value_type> ptr, size_type size) :
94  m_buf{std::move(ptr)}, m_size{size}
95  {}
96 
98  [[nodiscard]] size_type size() const noexcept { return m_size; }
100  [[nodiscard]] size_type length() const noexcept { return size(); }
101  [[nodiscard]] bool empty() const noexcept { return size() == 0; }
102 
103  [[nodiscard]] const_iterator begin() const noexcept { return data(); }
104  [[nodiscard]] const_iterator cbegin() const noexcept { return begin(); }
105  [[nodiscard]] const_iterator end() const noexcept { return data() + m_size; }
106  [[nodiscard]] const_iterator cend() const noexcept { return end(); }
107 
108  [[nodiscard]] const_reference front() const noexcept { return *begin(); }
109  [[nodiscard]] const_reference back() const noexcept
110  {
111  return *(data() + m_size - 1);
112  }
113 
114  [[nodiscard]] const_reverse_iterator rbegin() const
115  {
116  return const_reverse_iterator{end()};
117  }
118  [[nodiscard]] const_reverse_iterator crbegin() const { return rbegin(); }
119  [[nodiscard]] const_reverse_iterator rend() const
120  {
121  return const_reverse_iterator{begin()};
122  }
123  [[nodiscard]] const_reverse_iterator crend() const { return rend(); }
124 
126  [[nodiscard]] value_type const *data() const noexcept { return m_buf.get(); }
127 
128  [[nodiscard]] const_reference operator[](size_type i) const noexcept
129  {
130  return data()[i];
131  }
132 
133  [[nodiscard]] PQXX_PURE bool operator==(binarystring const &) const noexcept;
134  [[nodiscard]] bool operator!=(binarystring const &rhs) const noexcept
135  {
136  return not operator==(rhs);
137  }
138 
140 
142  const_reference at(size_type) const;
143 
145  void swap(binarystring &);
146 
148 
151  [[nodiscard]] char const *get() const noexcept
152  {
153  return reinterpret_cast<char const *>(m_buf.get());
154  }
155 
157  [[nodiscard]] std::string_view view() const noexcept
158  {
159  return std::string_view(get(), size());
160  }
161 
163 
168  [[nodiscard]] std::string str() const;
169 
171  [[nodiscard]] std::byte const *bytes() const
172  {
173  return reinterpret_cast<std::byte const *>(get());
174  }
175 
177  [[nodiscard]] std::basic_string_view<std::byte> bytes_view() const
178  {
179  return std::basic_string_view<std::byte>{bytes(), size()};
180  }
181 
182 private:
183  std::shared_ptr<value_type> m_buf;
184  size_type m_size{0};
185 };
186 
187 
188 template<> struct nullness<binarystring> : no_null<binarystring>
189 {};
190 
191 
193 
200 template<> struct string_traits<binarystring>
201 {
202  static std::size_t size_buffer(binarystring const &value) noexcept
203  {
204  return internal::size_esc_bin(std::size(value));
205  }
206 
207  static zview to_buf(char *begin, char *end, binarystring const &value)
208  {
209  auto const value_end{into_buf(begin, end, value)};
210  return zview{begin, value_end - begin - 1};
211  }
212 
213  static char *into_buf(char *begin, char *end, binarystring const &value)
214  {
215  auto const budget{size_buffer(value)};
216  if (static_cast<std::size_t>(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 
237 #include "pqxx/internal/compiler-internal-post.hxx"
238 #endif
The home of all libpqxx classes, functions, templates, etc.
Definition: array.hxx:26
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:230
void unesc_bin(std::string_view escaped_data, std::byte buffer[])
Reconstitute binary data from its escaped version.
Definition: util.cxx:176
void esc_bin(std::basic_string_view< std::byte > binary_data, char buffer[]) noexcept
Hex-escape binary data into a buffer.
Definition: util.cxx:145
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:326
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:335
Binary data corresponding to PostgreSQL's "BYTEA" binary-string type.
Definition: binarystring.hxx:58
char const * get() const noexcept
Raw character buffer (no terminating zero is added).
Definition: binarystring.hxx:151
const_reverse_iterator crend() const
Definition: binarystring.hxx:123
const_reverse_iterator rbegin() const
Definition: binarystring.hxx:114
bool operator!=(binarystring const &rhs) const noexcept
Definition: binarystring.hxx:134
const_pointer const_iterator
Definition: binarystring.hxx:66
std::basic_string_view< std::byte > bytes_view() const
Read data as a std::basic_string_view<std::byte>.
Definition: binarystring.hxx:177
const_iterator end() const noexcept
Definition: binarystring.hxx:105
const_iterator begin() const noexcept
Definition: binarystring.hxx:103
std::char_traits< char_type >::char_type value_type
Definition: binarystring.hxx:61
value_type const & const_reference
Definition: binarystring.hxx:64
long difference_type
Definition: binarystring.hxx:63
value_type const * data() const noexcept
Unescaped field contents.
Definition: binarystring.hxx:126
binarystring(std::shared_ptr< value_type > ptr, size_type size)
Efficiently wrap a buffer of binary data in a binarystring.
Definition: binarystring.hxx:92
const_reverse_iterator crbegin() const
Definition: binarystring.hxx:118
std::size_t size_type
Definition: binarystring.hxx:62
const_reference front() const noexcept
Definition: binarystring.hxx:108
const_reference back() const noexcept
Definition: binarystring.hxx:109
std::string_view view() const noexcept
Read contents as a std::string_view.
Definition: binarystring.hxx:157
bool empty() const noexcept
Definition: binarystring.hxx:101
const_reference operator[](size_type i) const noexcept
Definition: binarystring.hxx:128
const_iterator cend() const noexcept
Definition: binarystring.hxx:106
const_reverse_iterator rend() const
Definition: binarystring.hxx:119
size_type length() const noexcept
Size of converted string in bytes.
Definition: binarystring.hxx:100
binarystring & operator=(binarystring const &)
unsigned char char_type
Definition: binarystring.hxx:60
std::byte const * bytes() const
Access data as a pointer to std::byte.
Definition: binarystring.hxx:171
std::reverse_iterator< const_iterator > const_reverse_iterator
Definition: binarystring.hxx:67
const_iterator cbegin() const noexcept
Definition: binarystring.hxx:104
binarystring(binarystring const &)=default
value_type const * const_pointer
Definition: binarystring.hxx:65
size_type size() const noexcept
Size of converted string in bytes.
Definition: binarystring.hxx:98
static std::size_t size_buffer(binarystring const &value) noexcept
Definition: binarystring.hxx:202
static zview to_buf(char *begin, char *end, binarystring const &value)
Definition: binarystring.hxx:207
static binarystring from_string(std::string_view text)
Definition: binarystring.hxx:224
static char * into_buf(char *begin, char *end, binarystring const &value)
Definition: binarystring.hxx:213
Could not convert value to string: not enough buffer space.
Definition: except.hxx:186
Reference to a field in a result set.
Definition: field.hxx:34
Traits describing a type's "null value," if any.
Definition: strconv.hxx:91
Nullness traits describing a type which does not have a null value.
Definition: strconv.hxx:113
Traits class for use in string conversions.
Definition: strconv.hxx:153
static std::size_t size_buffer(TYPE const &value) noexcept
Estimate how much buffer space is needed to represent value.
static char * into_buf(char *begin, char *end, TYPE const &value)
Write value's string representation into buffer at begin.
Marker-type wrapper: zero-terminated std::string_view.
Definition: zview.hxx:40