libpqxx  7.3.1
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-2021, 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  [[deprecated("Use std::byte for binary data.")]] binarystring(
69  binarystring const &) = default;
70 
72 
76  [[deprecated("Use std::byte for binary data.")]] explicit binarystring(
77  field const &);
78 
80 
83  [[deprecated("Use std::byte for binary data.")]] explicit binarystring(
84  std::string_view);
85 
87  [[deprecated("Use std::byte for binary data.")]] binarystring(
88  void const *, std::size_t);
89 
91  [[deprecated("Use std::byte for binary data.")]] binarystring(
92  std::shared_ptr<value_type> ptr, size_type size) :
93  m_buf{std::move(ptr)}, m_size{size}
94  {}
95 
97  [[nodiscard]] size_type size() const noexcept { return m_size; }
99  [[nodiscard]] size_type length() const noexcept { return size(); }
100  [[nodiscard]] bool empty() const noexcept { return size() == 0; }
101 
102  [[nodiscard]] const_iterator begin() const noexcept { return data(); }
103  [[nodiscard]] const_iterator cbegin() const noexcept { return begin(); }
104  [[nodiscard]] const_iterator end() const noexcept { return data() + m_size; }
105  [[nodiscard]] const_iterator cend() const noexcept { return end(); }
106 
107  [[nodiscard]] const_reference front() const noexcept { return *begin(); }
108  [[nodiscard]] const_reference back() const noexcept
109  {
110  return *(data() + m_size - 1);
111  }
112 
113  [[nodiscard]] const_reverse_iterator rbegin() const
114  {
115  return const_reverse_iterator{end()};
116  }
117  [[nodiscard]] const_reverse_iterator crbegin() const { return rbegin(); }
118  [[nodiscard]] const_reverse_iterator rend() const
119  {
120  return const_reverse_iterator{begin()};
121  }
122  [[nodiscard]] const_reverse_iterator crend() const { return rend(); }
123 
125  [[nodiscard]] value_type const *data() const noexcept { return m_buf.get(); }
126 
127  [[nodiscard]] const_reference operator[](size_type i) const noexcept
128  {
129  return data()[i];
130  }
131 
132  [[nodiscard]] PQXX_PURE bool operator==(binarystring const &) const noexcept;
133  [[nodiscard]] bool operator!=(binarystring const &rhs) const noexcept
134  {
135  return not operator==(rhs);
136  }
137 
138  binarystring &operator=(binarystring const &);
139 
141  const_reference at(size_type) const;
142 
144  void swap(binarystring &);
145 
147 
150  [[nodiscard]] char const *get() const noexcept
151  {
152  return reinterpret_cast<char const *>(m_buf.get());
153  }
154 
156  [[nodiscard]] std::string_view view() const noexcept
157  {
158  return std::string_view(get(), size());
159  }
160 
162 
167  [[nodiscard]] std::string str() const;
168 
169 private:
170  std::shared_ptr<value_type> m_buf;
171  size_type m_size{0};
172 };
173 
174 
175 template<> struct nullness<binarystring> : no_null<binarystring>
176 {};
177 
178 
180 
187 template<> struct string_traits<binarystring>
188 {
189  static std::size_t size_buffer(binarystring const &value) noexcept
190  {
191  return internal::size_esc_bin(std::size(value));
192  }
193 
194  static zview to_buf(char *begin, char *end, binarystring const &value)
195  {
196  auto const value_end{into_buf(begin, end, value)};
197  return zview{begin, value_end - begin - 1};
198  }
199 
200  static char *into_buf(char *begin, char *end, binarystring const &value)
201  {
202  auto const budget{size_buffer(value)};
203  if (static_cast<std::size_t>(end - begin) < budget)
204  throw conversion_overrun{
205  "Not enough buffer space to escape binary data."};
206  internal::esc_bin(value.view(), begin);
207  return begin + budget;
208  }
209 
210  static binarystring from_string(std::string_view text)
211  {
212 #include "pqxx/internal/ignore-deprecated-pre.hxx"
213  auto const size{pqxx::internal::size_unesc_bin(std::size(text))};
214  std::shared_ptr<unsigned char> buf{
215  new unsigned char[size], [](unsigned char const *x) { delete[] x; }};
216  pqxx::internal::unesc_bin(text, reinterpret_cast<std::byte *>(buf.get()));
217  return binarystring{std::move(buf), size};
218 #include "pqxx/internal/ignore-deprecated-post.hxx"
219  }
220 };
221 } // namespace pqxx
222 
223 #include "pqxx/internal/compiler-internal-post.hxx"
224 #endif
long difference_type
Definition: binarystring.hxx:62
void esc_bin(std::string_view binary_data, char buffer[]) noexcept
Hex-escape binary data into a buffer.
Definition: util.cxx:122
const_iterator begin() const noexcept
Definition: binarystring.hxx:102
Traits class for use in string conversions.
Definition: strconv.hxx:148
The home of all libpqxx classes, functions, templates, etc.
Definition: array.hxx:25
Binary data corresponding to PostgreSQL&#39;s "BYTEA" binary-string type.
Definition: binarystring.hxx:56
value_type const & const_reference
Definition: binarystring.hxx:63
binarystring(std::shared_ptr< value_type > ptr, size_type size)
Efficiently wrap a buffer of binary data in a binarystring.
Definition: binarystring.hxx:91
const_reverse_iterator crend() const
Definition: binarystring.hxx:122
const_reverse_iterator rend() const
Definition: binarystring.hxx:118
std::reverse_iterator< const_iterator > const_reverse_iterator
Definition: binarystring.hxx:66
static std::size_t size_buffer(binarystring const &value) noexcept
Definition: binarystring.hxx:189
Nullness traits describing a type which does not have a null value.
Definition: strconv.hxx:108
std::size_t size_type
Definition: binarystring.hxx:61
size_type length() const noexcept
Size of converted string in bytes.
Definition: binarystring.hxx:99
const_iterator end() const noexcept
Definition: binarystring.hxx:104
value_type const * const_pointer
Definition: binarystring.hxx:64
const_pointer const_iterator
Definition: binarystring.hxx:65
Reference to a field in a result set.
Definition: field.hxx:33
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:269
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:364
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:278
const_iterator cend() const noexcept
Definition: binarystring.hxx:105
Marker-type wrapper: zero-terminated std::string_view.
Definition: zview.hxx:37
void unesc_bin(std::string_view escaped_data, std::byte buffer[])
Reconstitute binary data from its escaped version.
Definition: util.cxx:152
const_reverse_iterator rbegin() const
Definition: binarystring.hxx:113
static char * into_buf(char *begin, char *end, binarystring const &value)
Definition: binarystring.hxx:200
size_type size() const noexcept
Size of converted string in bytes.
Definition: binarystring.hxx:97
std::char_traits< char_type >::char_type value_type
Definition: binarystring.hxx:60
unsigned char char_type
Definition: binarystring.hxx:59
value_type const * data() const noexcept
Unescaped field contents.
Definition: binarystring.hxx:125
const_reference front() const noexcept
Definition: binarystring.hxx:107
const_reverse_iterator crbegin() const
Definition: binarystring.hxx:117
bool empty() const noexcept
Definition: binarystring.hxx:100
const_reference back() const noexcept
Definition: binarystring.hxx:108
const_reference operator[](size_type i) const noexcept
Definition: binarystring.hxx:127
static binarystring from_string(std::string_view text)
Definition: binarystring.hxx:210
const_iterator cbegin() const noexcept
Definition: binarystring.hxx:103
Could not convert value to string: not enough buffer space.
Definition: except.hxx:185
static zview to_buf(char *begin, char *end, binarystring const &value)
Definition: binarystring.hxx:194
Traits describing a type&#39;s "null value," if any.
Definition: strconv.hxx:86
bool operator!=(binarystring const &rhs) const noexcept
Definition: binarystring.hxx:133
std::string_view view() const noexcept
Read contents as a std::string_view.
Definition: binarystring.hxx:156