libpqxx  7.7.0
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 <memory>
15 #include <string>
16 #include <string_view>
17 
18 #include "pqxx/result.hxx"
19 #include "pqxx/strconv.hxx"
20 
21 namespace pqxx
22 {
23 class binarystring;
24 template<> struct string_traits<binarystring>;
25 
26 
28 
54 class PQXX_LIBEXPORT binarystring
55 {
56 public:
57  using char_type = unsigned char;
58  using value_type = std::char_traits<char_type>::char_type;
59  using size_type = std::size_t;
60  using difference_type = long;
61  using const_reference = value_type const &;
62  using const_pointer = value_type const *;
64  using const_reverse_iterator = std::reverse_iterator<const_iterator>;
65 
66  [[deprecated("Use std::byte for binary data.")]] binarystring(
67  binarystring const &) = default;
68 
70 
74  [[deprecated("Use std::byte for binary data.")]] explicit binarystring(
75  field const &);
76 
78 
81  [[deprecated("Use std::byte for binary data.")]] explicit binarystring(
82  std::string_view);
83 
85  [[deprecated("Use std::byte for binary data.")]] binarystring(
86  void const *, std::size_t);
87 
89  [[deprecated("Use std::byte for binary data.")]] binarystring(
90  std::shared_ptr<value_type> ptr, size_type size) :
91  m_buf{std::move(ptr)}, m_size{size}
92  {}
93 
95  [[nodiscard]] size_type size() const noexcept { return m_size; }
97  [[nodiscard]] size_type length() const noexcept { return size(); }
98  [[nodiscard]] bool empty() const noexcept { return size() == 0; }
99 
100  [[nodiscard]] const_iterator begin() const noexcept { return data(); }
101  [[nodiscard]] const_iterator cbegin() const noexcept { return begin(); }
102  [[nodiscard]] const_iterator end() const noexcept { return data() + m_size; }
103  [[nodiscard]] const_iterator cend() const noexcept { return end(); }
104 
105  [[nodiscard]] const_reference front() const noexcept { return *begin(); }
106  [[nodiscard]] const_reference back() const noexcept
107  {
108  return *(data() + m_size - 1);
109  }
110 
111  [[nodiscard]] const_reverse_iterator rbegin() const
112  {
113  return const_reverse_iterator{end()};
114  }
115  [[nodiscard]] const_reverse_iterator crbegin() const { return rbegin(); }
116  [[nodiscard]] const_reverse_iterator rend() const
117  {
118  return const_reverse_iterator{begin()};
119  }
120  [[nodiscard]] const_reverse_iterator crend() const { return rend(); }
121 
123  [[nodiscard]] value_type const *data() const noexcept { return m_buf.get(); }
124 
125  [[nodiscard]] const_reference operator[](size_type i) const noexcept
126  {
127  return data()[i];
128  }
129 
130  [[nodiscard]] PQXX_PURE bool operator==(binarystring const &) const noexcept;
131  [[nodiscard]] bool operator!=(binarystring const &rhs) const noexcept
132  {
133  return not operator==(rhs);
134  }
135 
136  binarystring &operator=(binarystring const &);
137 
139  const_reference at(size_type) const;
140 
142  void swap(binarystring &);
143 
145 
148  [[nodiscard]] char const *get() const noexcept
149  {
150  return reinterpret_cast<char const *>(m_buf.get());
151  }
152 
154  [[nodiscard]] std::string_view view() const noexcept
155  {
156  return std::string_view(get(), size());
157  }
158 
160 
165  [[nodiscard]] std::string str() const;
166 
168  [[nodiscard]] std::byte const *bytes() const
169  {
170  return reinterpret_cast<std::byte const *>(get());
171  }
172 
174  [[nodiscard]] std::basic_string_view<std::byte> bytes_view() const
175  {
176  return std::basic_string_view<std::byte>{bytes(), size()};
177  }
178 
179 private:
180  std::shared_ptr<value_type> m_buf;
181  size_type m_size{0};
182 };
183 
184 
185 template<> struct nullness<binarystring> : no_null<binarystring>
186 {};
187 
188 
190 
197 template<> struct string_traits<binarystring>
198 {
199  static std::size_t size_buffer(binarystring const &value) noexcept
200  {
201  return internal::size_esc_bin(std::size(value));
202  }
203 
204  static zview to_buf(char *begin, char *end, binarystring const &value)
205  {
206  return generic_to_buf(begin, end, value);
207  }
208 
209  static char *into_buf(char *begin, char *end, binarystring const &value)
210  {
211  auto const budget{size_buffer(value)};
212  if (internal::cmp_less(end - begin, budget))
213  throw conversion_overrun{
214  "Not enough buffer space to escape binary data."};
215  std::string_view text{value.view()};
217  return begin + budget;
218  }
219 
220  static binarystring from_string(std::string_view text)
221  {
222  auto const size{pqxx::internal::size_unesc_bin(std::size(text))};
223  std::shared_ptr<unsigned char> buf{
224  new unsigned char[size], [](unsigned char const *x) { delete[] x; }};
225  pqxx::internal::unesc_bin(text, reinterpret_cast<std::byte *>(buf.get()));
226 #include "pqxx/internal/ignore-deprecated-pre.hxx"
227  return binarystring{std::move(buf), size};
228 #include "pqxx/internal/ignore-deprecated-post.hxx"
229  }
230 };
231 } // namespace pqxx
232 #endif
const_reverse_iterator rbegin() const
Definition: binarystring.hxx:111
void esc_bin(std::basic_string_view< std::byte > binary_data, char buffer[]) noexcept
Hex-escape binary data into a buffer.
Definition: util.cxx:148
Binary data corresponding to PostgreSQL&#39;s "BYTEA" binary-string type.
Definition: binarystring.hxx:54
Could not convert value to string: not enough buffer space.
Definition: except.hxx:182
void unesc_bin(std::string_view escaped_data, std::byte buffer[])
Reconstitute binary data from its escaped version.
Definition: util.cxx:179
Reference to a field in a result set.
Definition: field.hxx:30
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:406
static std::size_t size_buffer(binarystring const &value) noexcept
Definition: binarystring.hxx:199
bool operator!=(binarystring const &rhs) const noexcept
Definition: binarystring.hxx:131
Nullness traits describing a type which does not have a null value.
Definition: strconv.hxx:110
static binarystring from_string(std::string_view text)
Definition: binarystring.hxx:220
zview generic_to_buf(char *begin, char *end, TYPE const &value)
Implement string_traits<TYPE>::to_buf by calling into_buf.
Definition: strconv.hxx:439
constexpr bool cmp_less(LEFT lhs, RIGHT rhs)
C++20 std::cmp_less, or workaround if not available.
Definition: util.hxx:53
std::basic_string_view< std::byte > bytes_view() const
Read data as a std::basic_string_view<std::byte>.
Definition: binarystring.hxx:174
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:375
static char * into_buf(char *begin, char *end, binarystring const &value)
Definition: binarystring.hxx:209
const_reference front() const noexcept
Definition: binarystring.hxx:105
bool empty() const noexcept
Definition: binarystring.hxx:98
value_type const * data() const noexcept
Unescaped field contents.
Definition: binarystring.hxx:123
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:397
std::char_traits< char_type >::char_type value_type
Definition: binarystring.hxx:58
const_iterator begin() const noexcept
Definition: binarystring.hxx:100
const_iterator cend() const noexcept
Definition: binarystring.hxx:103
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:289
size_type length() const noexcept
Size of converted string in bytes.
Definition: binarystring.hxx:97
value_type const * const_pointer
Definition: binarystring.hxx:62
static zview to_buf(char *begin, char *end, binarystring const &value)
Definition: binarystring.hxx:204
binarystring(std::shared_ptr< value_type > ptr, size_type size)
Efficiently wrap a buffer of binary data in a binarystring.
Definition: binarystring.hxx:89
std::reverse_iterator< const_iterator > const_reverse_iterator
Definition: binarystring.hxx:64
const_reference back() const noexcept
Definition: binarystring.hxx:106
Marker-type wrapper: zero-terminated std::string_view.
Definition: zview.hxx:37
const_reverse_iterator crend() const
Definition: binarystring.hxx:120
unsigned char char_type
Definition: binarystring.hxx:57
const_reference operator[](size_type i) const noexcept
Definition: binarystring.hxx:125
std::string_view view() const noexcept
Read contents as a std::string_view.
Definition: binarystring.hxx:154
size_type size() const noexcept
Size of converted string in bytes.
Definition: binarystring.hxx:95
const_reverse_iterator rend() const
Definition: binarystring.hxx:116
long difference_type
Definition: binarystring.hxx:60
const_iterator end() const noexcept
Definition: binarystring.hxx:102
Traits describing a type&#39;s "null value," if any.
Definition: strconv.hxx:88
const_reverse_iterator crbegin() const
Definition: binarystring.hxx:115
const_iterator cbegin() const noexcept
Definition: binarystring.hxx:101
The home of all libpqxx classes, functions, templates, etc.
Definition: array.hxx:22
std::byte const * bytes() const
Access data as a pointer to std::byte.
Definition: binarystring.hxx:168
value_type const & const_reference
Definition: binarystring.hxx:61
Traits class for use in string conversions.
Definition: strconv.hxx:152
const_pointer const_iterator
Definition: binarystring.hxx:63
std::size_t size_type
Definition: binarystring.hxx:59