libpqxx
The C++ client library for PostgreSQL
Loading...
Searching...
No Matches
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-2024, 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
25namespace pqxx
26{
27class binarystring;
28template<> struct string_traits<binarystring>;
29
30
32
57class PQXX_LIBEXPORT binarystring
58{
59public:
60 using char_type = unsigned char;
61 using value_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 *;
66 using const_iterator = const_pointer;
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
139 binarystring &operator=(binarystring const &);
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]] pqxx::bytes_view bytes_view() const
178 {
179 return pqxx::bytes_view{bytes(), size()};
180 }
181
182private:
183 std::shared_ptr<value_type> m_buf;
184 size_type m_size{0};
185};
186
187
188template<> struct nullness<binarystring> : no_null<binarystring>
189{};
190
191
193
200template<> 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 return generic_to_buf(begin, end, value);
210 }
211
212 static char *into_buf(char *begin, char *end, binarystring const &value)
213 {
214 auto const budget{size_buffer(value)};
215 if (internal::cmp_less(end - begin, budget))
216 throw conversion_overrun{
217 "Not enough buffer space to escape binary data."};
218 std::string_view text{value.view()};
219 internal::esc_bin(binary_cast(text), begin);
220 return begin + budget;
221 }
222
223 static binarystring from_string(std::string_view text)
224 {
225 auto const size{pqxx::internal::size_unesc_bin(std::size(text))};
226 std::shared_ptr<unsigned char> buf{
227 new unsigned char[size], [](unsigned char const *x) { delete[] x; }};
228 pqxx::internal::unesc_bin(text, reinterpret_cast<std::byte *>(buf.get()));
229#include "pqxx/internal/ignore-deprecated-pre.hxx"
230 return binarystring{std::move(buf), size};
231#include "pqxx/internal/ignore-deprecated-post.hxx"
232 }
233};
234} // namespace pqxx
235#endif
Reference to a field in a result set.
Definition field.hxx:35
Marker-type wrapper: zero-terminated std::string_view.
Definition zview.hxx:38
char const * get() const noexcept
Raw character buffer (no terminating zero is added).
Definition binarystring.hxx:151
binarystring(std::shared_ptr< value_type > ptr, size_type size)
Efficiently wrap a buffer of binary data in a binarystring.
Definition binarystring.hxx:92
std::string_view view() const noexcept
Read contents as a std::string_view.
Definition binarystring.hxx:157
pqxx::bytes_view bytes_view() const
Read data as a bytes_view.
Definition binarystring.hxx:177
std::byte const * bytes() const
Access data as a pointer to std::byte.
Definition binarystring.hxx:171
value_type const * data() const noexcept
Unescaped field contents.
Definition binarystring.hxx:126
size_type length() const noexcept
Size of converted string in bytes.
Definition binarystring.hxx:100
size_type size() const noexcept
Size of converted string in bytes.
Definition binarystring.hxx:98
Binary data corresponding to PostgreSQL's "BYTEA" binary-string type.
Definition binarystring.hxx:58
Could not convert value to string: not enough buffer space.
Definition except.hxx:313
void PQXX_LIBEXPORT unesc_bin(std::string_view escaped_data, std::byte buffer[])
Reconstitute binary data from its escaped version.
Definition util.cxx:165
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:516
constexpr bool cmp_less(LEFT lhs, RIGHT rhs) noexcept
Same as std::cmp_less, or a workaround where that's not available.
Definition util.hxx:65
void PQXX_LIBEXPORT esc_bin(bytes_view binary_data, char buffer[]) noexcept
Hex-escape binary data into a buffer.
Definition util.cxx:133
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:525
The home of all libpqxx classes, functions, templates, etc.
Definition array.cxx:27
bytes_view binary_cast(TYPE const &data)
Cast binary data to a type that libpqxx will recognise as binary.
Definition util.hxx:409
zview generic_to_buf(char *begin, char *end, TYPE const &value)
Implement string_traits<TYPE>::to_buf by calling into_buf.
Definition strconv.hxx:586
std::conditional< has_generic_bytes_char_traits, std::basic_string< std::byte >, std::basic_string< std::byte, byte_char_traits > >::type bytes
Type alias for a container containing bytes.
Definition util.hxx:375
std::conditional< has_generic_bytes_char_traits, std::basic_string_view< std::byte >, std::basic_string_view< std::byte, byte_char_traits > >::type bytes_view
Type alias for a view of bytes.
Definition util.hxx:385
Nullness traits describing a type which does not have a null value.
Definition strconv.hxx:113
Traits describing a type's "null value," if any.
Definition strconv.hxx:91
Traits class for use in string conversions.
Definition strconv.hxx:153
static TYPE from_string(std::string_view text)
Parse a string representation of a TYPE value.
static std::size_t size_buffer(TYPE const &value) noexcept
Estimate how much buffer space is needed to represent value.
static zview to_buf(char *begin, char *end, TYPE const &value)
Return a string_view representing value, plus terminating zero.
static char * into_buf(char *begin, char *end, TYPE const &value)
Write value's string representation into buffer at begin.