diff options
Diffstat (limited to 'doc/reference/statement.adoc')
| -rw-r--r-- | doc/reference/statement.adoc | 165 |
1 files changed, 0 insertions, 165 deletions
diff --git a/doc/reference/statement.adoc b/doc/reference/statement.adoc deleted file mode 100644 index 6ce89e4..0000000 --- a/doc/reference/statement.adoc +++ /dev/null @@ -1,165 +0,0 @@ -== `sqlite/statement.hpp` - -=== `param_ref` - -A reference to a value to temporary bind for an execute statement. Most values are captures by reference. - -[source,cpp] ----- -struct param_ref -{ - // Default construct a parameter, gives `null`. - param_ref() = default; - // Bind null - param_ref(variant2::monostate); - // Bind null - param_ref(std::nullptr_t); - // Bind an integer. - template<typename I> - param_ref(I value); - // Bind a blob. - param_ref(blob_view blob); - // Bind a string. - param_ref(string_view text); - - template<typename StringLike> - param_ref(StringLike && text); - template<typename BlobLike> - param_ref(BlobLike && text); - - // Bind a floating point value. - param_ref(double value) : impl_(value) { } - // Bind a zero_blob value, i.e. a blob that initialized by zero. - param_ref(zero_blob zb) : impl_(zb) { } - - // Bind pointer value to the parameter. @see https://www.sqlite.org/bindptr.html - // Requires sqlite 3.20 - // Deleter must a function pointer or trivially constructible. - template<typename T, typename Deleter> - param_ref(std::unique_ptr<T, Deleter> ptr); - - - - // Apply the param_ref to a statement. - int apply(sqlite3_stmt * stmt, int c) const; - - // Construct param_ref from a variant - template<typename T> - param_ref(T && t); - ----- - - -=== `statement` - -A statement used for a prepared-statement. - - - -[source,cpp] ----- -struct statement -{ - // execute the prepared statement once. This transfers ownership to the resultset - template <typename ArgRange = std::initializer_list<param_ref>> - resultset execute(ArgRange && params, system::error_code& ec, error_info& info) &&; // <1> - template <typename ArgRange = std::initializer_list<param_ref> - resultset execute(ArgRange && params) &&; // <1> - resultset execute( - std::initializer_list<std::pair<string_view, param_ref>> params, - system::error_code& ec, - error_info& info) &&; // <2> - - resultset execute(std::initializer_list<std::pair<string_view, param_ref>> params) &&; - template<typename T, bool Strict = false, typename ArgRange = std::initializer_list<param_ref>> - static_resultset<T, Strict> execute( - ArgRange && params, - system::error_code & ec, - error_info & ei) &&; // <1> - - template<typename T, bool Strict = false, typename ArgRange = std::initializer_list<param_ref>> - static_resultset<T, Strict> execute(ArgRange && params) &&; // <1> - - template<typename T, bool Strict = false> - static_resultset<T, Strict> execute( - std::initializer_list<std::pair<string_view, param_ref>> params, - system::error_code & ec, - error_info & ei) &&; // <2> - template<typename T, bool Strict = false> - static_resultset<T, Strict> execute(std::initializer_list<std::pair<string_view, param_ref>> params) &&; // <2> - - - template <typename ArgRange = std::initializer_list<param_ref>> - resultset execute( - ArgRange && params, - system::error_code& ec, - error_info& info) &; // <1> - - - template <typename ArgRange = std::initializer_list<param_ref>> - resultset execute(ArgRange && params) &; // <1> - - - resultset execute( - std::initializer_list<std::pair<string_view, param_ref>> params, - system::error_code& ec, - error_info& info) &; // <2> - - resultset execute(std::initializer_list<std::pair<string_view, param_ref>> params) &; // <2> - - template<typename T, bool Strict = false, typename ArgRange = std::initializer_list<param_ref>> - static_resultset<T, Strict> execute( - ArgRange && params, - system::error_code & ec, - error_info & ei) &; // <1> - - template<typename T, bool Strict = false, typename ArgRange = std::initializer_list<param_ref>> - static_resultset<T, Strict> execute(ArgRange && params) &; // <1> - - template<typename T, bool Strict = false> - static_resultset<T, Strict> execute( - std::initializer_list<std::pair<string_view, param_ref>> params, - system::error_code & ec, - error_info & ei) &; // <2> - template<typename T, bool Strict = false> - static_resultset<T, Strict> execute(std::initializer_list<std::pair<string_view, param_ref>> params) &; // <2> - - - - // Returns the sql used to construct the prepared statement. - stringe_view sql(); - - // Returns the expanded sql used to construct the prepared statement. Requires sqlite 3.14 - stringe_view expanded_sql(); - - // Returns the expanded sql used to construct the prepared statement. requiers sqlite to be compiles with SQLITE_ENABLE_NORMALIZE. - stringe_view normalized_sql(); - - // Returns the declared type of the column - string_view declared_type(int id) const; -}; ----- -<1> Executes a query with positional arguments -<2> Executes a query with named arguments (from a map-like object) - - - - - -WARNING: The `&&` overloads transfer ownership to the resultset, while the `&` keep them in the statement. -That is, this is UB: -[source,cpp] ----- -resultset get_users(sqlite::connection & conn) -{ - auto s = conn.prepare("SELECT * from users where name = ?"); - return s.execute({"allen"}); // UB, because result set points into s -} - -resultset get_users(sqlite::connection & conn) -{ - // correct, because resultset takes ownershipo - return conn.prepare("SELECT * from users where name = ?").execute({"allen"}); -} ----- - |