1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
|
== `sqlite/blob.hpp`
=== `blob_view`
A `blob_view` is a view type referring to https://www.sqlite.org/datatype3.html[Binary Large OBject],
i.e. a non-owning type.
.Definition
[source,cpp]
----
//A view to a binary large object
struct blob_view
{
// The data in the blob
const void * data() const;
// The size of the data in the blob, in bytes
std::size_t size() const
// Construct a blob from existing data
blob_view(const void * data, std::size_t size);
// Construct an empty blob
blob_view() = default;
// Construct a blob from some other blob-like structure (data() is a pointer & size() returns size_t)
template<typename T>
explicit blob_view(const T & value);
// Create a blob from the
blob_view(const struct blob & b);
};
----
The `blob_view` can be used to access binary data from the database without copying.
=== `zero_blob`
The `zero_blob` is a special type that denotes blobs full of zeros without requiring any allocations.
It can be used as a result from a <<function>> or as a parameter for a <<statement>>.
.Definition
[source,cpp]
----
enum class zero_blob : sqlite3_uint64 {};
----
.Example
[source,cpp]
----
extern sqlite::connection conn;
conn.prepare("INSERT INTO example(bdata) VALUES(?)")
.execute(sqlite::zero_blob(1024)); // <1>
----
<1> Insert a blob of zeros with the size 1024
=== `blob`
The `blob` object owns a binary large object.
[source,cpp]
----
// @brief An object that owns a binary large object. @ingroup reference
struct blob
{
// The data in the blob
void * data() const;
// The size of the data int he blob, in bytes
std::size_t size() const;
// Create a blob from a blob_view
explicit blob(blob_view bv);
// Create an empty blob with size `n`.
explicit blob(std::size_t n);
// Construct an empty blob
constexpr blob() = default;
// Release & take ownership of the blob.
void * release() &&
};
----
=== `blob_handle`
A `blob_handle` is readable & writable handle to a `blob` in the database.
It allows incremental reading/writing of the raw data.
[source,cpp]
----
// Open a blob
blob_handle open_blob(connection & conn,
cstring_ref db,
cstring_ref table,
cstring_ref column,
sqlite3_int64 row,
bool read_only,
system::error_code &ec,
error_info &ei);
blob_handle open_blob(connection & conn,
cstring_ref db,
cstring_ref table,
cstring_ref column,
sqlite3_int64 row,
bool read_only = false);
// An object that holds a binary large object. Can be obtained by using @ref blob_handle. @ingroup reference
struct blob_handle
{
// Default constructor
blob_handle() = default;
// Construct from a handle. This takesowner ship of the `sqlite3_blob` handle.
explicit blob_handle(sqlite3_blob * blob);
// Reopen the blob on another row (i.e. the same column of the same table)
void reopen(sqlite3_int64 row_id);
void reopen(sqlite3_int64 row_id, system::error_code & ec);
// Read data from the blob
void read_at(void *data, int len, int offset);
void read_at(void *data, int len, int offset, system::error_code &ec);
// Write data to the blob
void write_at(const void *data, int len, int offset);
void write_at(const void *data, int len, int offset, system::error_code &ec);
// The size of the blob
std::size_t size() const;
// The handle of the blob
using handle_type = sqlite3_blob*;
// Returns the handle of the blob
handle_type handle();
// Release the owned handle.
handle_type release() &&;
};
----
|
