From 6617db59fbe82517d60e45d5e2b5f0de8fccbd6a Mon Sep 17 00:00:00 2001 From: Thom Chiovoloni Date: Sun, 5 Apr 2020 22:15:27 -0700 Subject: [PATCH] Document which features are required, and add vtab usage examples (#669) --- src/backup.rs | 26 ++++++++++++---------- src/blob.rs | 10 ++++----- src/collation.rs | 8 +++---- src/functions.rs | 26 +++++++++++++++------- src/hooks.rs | 16 +++++++------- src/lib.rs | 12 +++++----- src/limits.rs | 7 +++--- src/load_extension_guard.rs | 3 ++- src/session.rs | 26 ++++++++++++---------- src/trace.rs | 15 +++++++------ src/types/from_sql.rs | 9 ++++---- src/types/to_sql.rs | 4 +++- src/vtab/array.rs | 28 +++++++++++++++++++++-- src/vtab/csvtab.rs | 23 +++++++++++++++++-- src/vtab/mod.rs | 44 ++++++++++++++++++++----------------- src/vtab/series.rs | 4 ++-- 16 files changed, 164 insertions(+), 97 deletions(-) diff --git a/src/backup.rs b/src/backup.rs index f40ad79..7cc8b02 100644 --- a/src/backup.rs +++ b/src/backup.rs @@ -1,4 +1,4 @@ -//! Online SQLite backup API. +//! `feature = "backup"` Online SQLite backup API. //! //! To create a `Backup`, you must have two distinct `Connection`s - one //! for the source (which can be used while the backup is running) and one for @@ -43,7 +43,9 @@ use crate::error::{error_from_handle, error_from_sqlite_code}; use crate::{Connection, DatabaseName, Result}; impl Connection { - /// Back up the `name` database to the given destination path. + /// `feature = "backup"` Back up the `name` database to the given + /// destination path. + /// /// If `progress` is not `None`, it will be called periodically /// until the backup completes. /// @@ -81,9 +83,9 @@ impl Connection { } } - /// Restore the given source path into the `name` database. - /// If `progress` is not `None`, it will be called periodically - /// until the restore completes. + /// `feature = "backup"` Restore the given source path into the + /// `name` database. If `progress` is not `None`, it will be + /// called periodically until the restore completes. /// /// For more fine-grained control over the restore process (e.g., /// to sleep periodically during the restore or to restore from an @@ -128,7 +130,7 @@ impl Connection { } } -/// Possible successful results of calling `Backup::step`. +/// `feature = "backup"` Possible successful results of calling `Backup::step`. #[derive(Copy, Clone, Debug, PartialEq, Eq)] pub enum StepResult { /// The backup is complete. @@ -147,11 +149,11 @@ pub enum StepResult { Locked, } -/// Struct specifying the progress of a backup. The percentage completion can -/// be calculated as `(pagecount - remaining) / pagecount`. The progress of a -/// backup is as of the last call to `step` - if the source database is -/// modified after a call to `step`, the progress value will become outdated -/// and potentially incorrect. +/// `feature = "backup"` Struct specifying the progress of a backup. The +/// percentage completion can be calculated as `(pagecount - remaining) / +/// pagecount`. The progress of a backup is as of the last call to `step` - if +/// the source database is modified after a call to `step`, the progress value +/// will become outdated and potentially incorrect. #[derive(Copy, Clone, Debug)] pub struct Progress { /// Number of pages in the source database that still need to be backed up. @@ -160,7 +162,7 @@ pub struct Progress { pub pagecount: c_int, } -/// A handle to an online backup. +/// `feature = "backup"` A handle to an online backup. pub struct Backup<'a, 'b> { phantom_from: PhantomData<&'a ()>, phantom_to: PhantomData<&'b ()>, diff --git a/src/blob.rs b/src/blob.rs index 372fc4c..2facccf 100644 --- a/src/blob.rs +++ b/src/blob.rs @@ -1,4 +1,4 @@ -//! Incremental BLOB I/O. +//! `feature = "blob"` Incremental BLOB I/O. //! //! Note that SQLite does not provide API-level access to change the size of a //! BLOB; that must be performed through SQL statements. @@ -60,7 +60,7 @@ use super::ffi; use super::types::{ToSql, ToSqlOutput}; use crate::{Connection, DatabaseName, Result}; -/// Handle to an open BLOB. +/// `feature = "blob"` Handle to an open BLOB. pub struct Blob<'conn> { conn: &'conn Connection, blob: *mut ffi::sqlite3_blob, @@ -68,8 +68,8 @@ pub struct Blob<'conn> { } impl Connection { - /// Open a handle to the BLOB located in `row_id`, `column`, `table` in - /// database `db`. + /// `feature = "blob"` Open a handle to the BLOB located in `row_id`, `column`, + /// `table` in database `db`. /// /// # Failure /// @@ -238,7 +238,7 @@ impl Drop for Blob<'_> { } } -/// BLOB of length N that is filled with zeroes. +/// `feature = "blob"` BLOB of length N that is filled with zeroes. /// /// Zeroblobs are intended to serve as placeholders for BLOBs whose content is /// later written using incremental BLOB I/O routines. diff --git a/src/collation.rs b/src/collation.rs index 1ca2b33..a95664c 100644 --- a/src/collation.rs +++ b/src/collation.rs @@ -1,4 +1,4 @@ -//! Add, remove, or modify a collation +//! `feature = "collation"` Add, remove, or modify a collation use std::cmp::Ordering; use std::os::raw::{c_char, c_int, c_void}; use std::panic::{catch_unwind, UnwindSafe}; @@ -14,7 +14,7 @@ unsafe extern "C" fn free_boxed_value(p: *mut c_void) { } impl Connection { - /// Add or modify a collation. + /// `feature = "collation"` Add or modify a collation. pub fn create_collation(&self, collation_name: &str, x_compare: C) -> Result<()> where C: Fn(&str, &str) -> Ordering + Send + UnwindSafe + 'static, @@ -24,7 +24,7 @@ impl Connection { .create_collation(collation_name, x_compare) } - /// Collation needed callback + /// `feature = "collation"` Collation needed callback pub fn collation_needed( &self, x_coll_needed: fn(&Connection, &str) -> Result<()>, @@ -32,7 +32,7 @@ impl Connection { self.db.borrow_mut().collation_needed(x_coll_needed) } - /// Remove collation. + /// `feature = "collation"` Remove collation. pub fn remove_collation(&self, collation_name: &str) -> Result<()> { self.db.borrow_mut().remove_collation(collation_name) } diff --git a/src/functions.rs b/src/functions.rs index f949559..dbf9b6a 100644 --- a/src/functions.rs +++ b/src/functions.rs @@ -1,4 +1,4 @@ -//! Create or redefine SQL functions. +//! `feature = "functions"` Create or redefine SQL functions. //! //! # Example //! @@ -115,7 +115,8 @@ unsafe extern "C" fn free_boxed_value(p: *mut c_void) { drop(Box::from_raw(p as *mut T)); } -/// Context is a wrapper for the SQLite function evaluation context. +/// `feature = "functions"` Context is a wrapper for the SQLite function +/// evaluation context. pub struct Context<'a> { ctx: *mut sqlite3_context, args: &'a [*mut sqlite3_value], @@ -205,7 +206,8 @@ impl Context<'_> { } } -/// Aggregate is the callback interface for user-defined aggregate function. +/// `feature = "functions"` Aggregate is the callback interface for user-defined +/// aggregate function. /// /// `A` is the type of the aggregation context and `T` is the type of the final /// result. Implementations should be stateless. @@ -231,8 +233,8 @@ where fn finalize(&self, _: Option) -> Result; } -/// WindowAggregate is the callback interface for user-defined aggregate window -/// function. +/// `feature = "window"` WindowAggregate is the callback interface for +/// user-defined aggregate window function. #[cfg(feature = "window")] pub trait WindowAggregate: Aggregate where @@ -270,7 +272,8 @@ impl Default for FunctionFlags { } impl Connection { - /// Attach a user-defined scalar function to this database connection. + /// `feature = "functions"` Attach a user-defined scalar function to + /// this database connection. /// /// `fn_name` is the name the function will be accessible from SQL. /// `n_arg` is the number of arguments to the function. Use `-1` for a @@ -321,7 +324,8 @@ impl Connection { .create_scalar_function(fn_name, n_arg, flags, x_func) } - /// Attach a user-defined aggregate function to this database connection. + /// `feature = "functions"` Attach a user-defined aggregate function to this + /// database connection. /// /// # Failure /// @@ -343,6 +347,11 @@ impl Connection { .create_aggregate_function(fn_name, n_arg, flags, aggr) } + /// `feature = "window"` Attach a user-defined aggregate window function to + /// this database connection. + /// + /// See https://sqlite.org/windowfunctions.html#udfwinfunc for more + /// information. #[cfg(feature = "window")] pub fn create_window_function( &self, @@ -361,7 +370,8 @@ impl Connection { .create_window_function(fn_name, n_arg, flags, aggr) } - /// Removes a user-defined function from this database connection. + /// `feature = "functions"` Removes a user-defined function from this + /// database connection. /// /// `fn_name` and `n_arg` should match the name and number of arguments /// given to `create_scalar_function` or `create_aggregate_function`. diff --git a/src/hooks.rs b/src/hooks.rs index e8efe76..531722a 100644 --- a/src/hooks.rs +++ b/src/hooks.rs @@ -1,4 +1,4 @@ -//! Commit, Data Change and Rollback Notification Callbacks +//! `feature = "hooks"` Commit, Data Change and Rollback Notification Callbacks #![allow(non_camel_case_types)] use std::os::raw::{c_char, c_int, c_void}; @@ -9,7 +9,7 @@ use crate::ffi; use crate::{Connection, InnerConnection}; -/// Action Codes +/// `feature = "hooks"` Action Codes #[derive(Clone, Copy, Debug, PartialEq)] #[repr(i32)] pub enum Action { @@ -31,8 +31,8 @@ impl From for Action { } impl Connection { - /// Register a callback function to be invoked whenever a transaction is - /// committed. + /// `feature = "hooks"` Register a callback function to be invoked whenever + /// a transaction is committed. /// /// The callback returns `true` to rollback. pub fn commit_hook(&self, hook: Option) @@ -42,8 +42,8 @@ impl Connection { self.db.borrow_mut().commit_hook(hook); } - /// Register a callback function to be invoked whenever a transaction is - /// committed. + /// `feature = "hooks"` Register a callback function to be invoked whenever + /// a transaction is committed. /// /// The callback returns `true` to rollback. pub fn rollback_hook(&self, hook: Option) @@ -53,8 +53,8 @@ impl Connection { self.db.borrow_mut().rollback_hook(hook); } - /// Register a callback function to be invoked whenever a row is updated, - /// inserted or deleted in a rowid table. + /// `feature = "hooks"` Register a callback function to be invoked whenever + /// a row is updated, inserted or deleted in a rowid table. /// /// The callback parameters are: /// diff --git a/src/lib.rs b/src/lib.rs index b17691d..432f89e 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -653,8 +653,8 @@ impl Connection { r.map_err(move |err| (self, err)) } - /// Enable loading of SQLite extensions. Strongly consider using - /// `LoadExtensionGuard` instead of this function. + /// `feature = "load_extension"` Enable loading of SQLite extensions. + /// Strongly consider using `LoadExtensionGuard` instead of this function. /// /// ## Example /// @@ -676,7 +676,7 @@ impl Connection { self.db.borrow_mut().enable_load_extension(1) } - /// Disable loading of SQLite extensions. + /// `feature = "load_extension"` Disable loading of SQLite extensions. /// /// See `load_extension_enable` for an example. /// @@ -688,9 +688,9 @@ impl Connection { self.db.borrow_mut().enable_load_extension(0) } - /// Load the SQLite extension at `dylib_path`. `dylib_path` is passed - /// through to `sqlite3_load_extension`, which may attempt OS-specific - /// modifications if the file cannot be loaded directly. + /// `feature = "load_extension"` Load the SQLite extension at `dylib_path`. + /// `dylib_path` is passed through to `sqlite3_load_extension`, which may + /// attempt OS-specific modifications if the file cannot be loaded directly. /// /// If `entry_point` is `None`, SQLite will attempt to find the entry /// point. If it is not `None`, the entry point will be passed through diff --git a/src/limits.rs b/src/limits.rs index cbb5e61..238ce56 100644 --- a/src/limits.rs +++ b/src/limits.rs @@ -1,4 +1,4 @@ -//! Run-Time Limits +//! `feature = "limits"` Run-Time Limits use std::os::raw::c_int; @@ -8,13 +8,14 @@ pub use crate::ffi::Limit; use crate::Connection; impl Connection { - /// Returns the current value of a limit. + /// `feature = "limits"` Returns the current value of a limit. pub fn limit(&self, limit: Limit) -> i32 { let c = self.db.borrow(); unsafe { ffi::sqlite3_limit(c.db(), limit as c_int, -1) } } - /// Changes the limit to `new_val`, returning the prior value of the limit. + /// `feature = "limits"` Changes the limit to `new_val`, returning the prior + /// value of the limit. pub fn set_limit(&self, limit: Limit, new_val: i32) -> i32 { let c = self.db.borrow_mut(); unsafe { ffi::sqlite3_limit(c.db(), limit as c_int, new_val) } diff --git a/src/load_extension_guard.rs b/src/load_extension_guard.rs index ee3dda3..f4f67d1 100644 --- a/src/load_extension_guard.rs +++ b/src/load_extension_guard.rs @@ -1,6 +1,7 @@ use crate::{Connection, Result}; -/// RAII guard temporarily enabling SQLite extensions to be loaded. +/// `feature = "load_extension"` RAII guard temporarily enabling SQLite +/// extensions to be loaded. /// /// ## Example /// diff --git a/src/session.rs b/src/session.rs index aff7ef9..4b5a2b0 100644 --- a/src/session.rs +++ b/src/session.rs @@ -1,4 +1,4 @@ -//! [Session Extension](https://sqlite.org/sessionintro.html) +//! `feature = "session"` [Session Extension](https://sqlite.org/sessionintro.html) #![allow(non_camel_case_types)] use std::ffi::CStr; @@ -20,7 +20,7 @@ use crate::{errmsg_to_string, str_to_cstring, Connection, DatabaseName, Result}; // https://sqlite.org/session.html -/// An instance of this object is a session that can be used to record changes +/// `feature = "session"` An instance of this object is a session that can be used to record changes /// to a database. pub struct Session<'conn> { phantom: PhantomData<&'conn ()>, @@ -211,7 +211,7 @@ impl Drop for Session<'_> { } } -/// Invert a changeset +/// `feature = "session"` Invert a changeset pub fn invert_strm(input: &mut dyn Read, output: &mut dyn Write) -> Result<()> { let input_ref = &input; let output_ref = &output; @@ -226,7 +226,7 @@ pub fn invert_strm(input: &mut dyn Read, output: &mut dyn Write) -> Result<()> { Ok(()) } -/// Combine two changesets +/// `feature = "session"` Combine two changesets pub fn concat_strm( input_a: &mut dyn Read, input_b: &mut dyn Read, @@ -248,7 +248,7 @@ pub fn concat_strm( Ok(()) } -/// Changeset or Patchset +/// `feature = "session"` Changeset or Patchset pub struct Changeset { cs: *mut c_void, n: c_int, @@ -296,7 +296,8 @@ impl Drop for Changeset { } } -/// Cursor for iterating over the elements of a changeset or patchset. +/// `feature = "session"` Cursor for iterating over the elements of a changeset +/// or patchset. pub struct ChangesetIter<'changeset> { phantom: PhantomData<&'changeset ()>, it: *mut ffi::sqlite3_changeset_iter, @@ -347,6 +348,7 @@ impl FallibleStreamingIterator for ChangesetIter<'_> { } } +/// `feature = "session"` pub struct Operation<'item> { table_name: &'item str, number_of_columns: i32, @@ -380,7 +382,7 @@ impl Drop for ChangesetIter<'_> { } } -/// An item passed to a conflict-handler by `Connection::apply`, +/// `feature = "session"` An item passed to a conflict-handler by `Connection::apply`, /// or an item generated by `ChangesetIter::next`. // TODO enum ? Delete, Insert, Update, ... pub struct ChangesetItem { @@ -493,7 +495,7 @@ impl ChangesetItem { } } -/// Used to combine two or more changesets or +/// `feature = "session"` Used to combine two or more changesets or /// patchsets pub struct Changegroup { cg: *mut ffi::sqlite3_changegroup, @@ -558,7 +560,7 @@ impl Drop for Changegroup { } impl Connection { - /// Apply a changeset to a database + /// `feature = "session"` Apply a changeset to a database pub fn apply(&self, cs: &Changeset, filter: Option, conflict: C) -> Result<()> where F: Fn(&str) -> bool + Send + RefUnwindSafe + 'static, @@ -592,7 +594,7 @@ impl Connection { Ok(()) } - /// Apply a changeset to a database + /// `feature = "session"` Apply a changeset to a database pub fn apply_strm( &self, input: &mut dyn Read, @@ -633,7 +635,7 @@ impl Connection { } } -/// Constants passed to the conflict handler +/// `feature = "session"` Constants passed to the conflict handler #[repr(i32)] #[derive(Debug, PartialEq)] pub enum ConflictType { @@ -657,7 +659,7 @@ impl From for ConflictType { } } -/// Constants returned by the conflict handler +/// `feature = "session"` Constants returned by the conflict handler #[repr(i32)] #[derive(Debug, PartialEq)] pub enum ConflictAction { diff --git a/src/trace.rs b/src/trace.rs index 1ccc55f..c034355 100644 --- a/src/trace.rs +++ b/src/trace.rs @@ -1,4 +1,4 @@ -//! Tracing and profiling functions. Error and warning log. +//! `feature = "trace"` Tracing and profiling functions. Error and warning log. use std::ffi::{CStr, CString}; use std::mem; @@ -11,7 +11,7 @@ use super::ffi; use crate::error::error_from_sqlite_code; use crate::{Connection, Result}; -/// Set up the process-wide SQLite error logging callback. +/// `feature = "trace"` Set up the process-wide SQLite error logging callback. /// /// # Safety /// @@ -56,7 +56,8 @@ pub unsafe fn config_log(callback: Option) -> Result<()> { } } -/// Write a message into the error log established by `config_log`. +/// `feature = "trace"` Write a message into the error log established by +/// `config_log`. pub fn log(err_code: c_int, msg: &str) { let msg = CString::new(msg).expect("SQLite log messages cannot contain embedded zeroes"); unsafe { @@ -65,8 +66,8 @@ pub fn log(err_code: c_int, msg: &str) { } impl Connection { - /// Register or clear a callback function that can be used for tracing the - /// execution of SQL statements. + /// `feature = "trace"` Register or clear a callback function that can be + /// used for tracing the execution of SQL statements. /// /// Prepared statement placeholders are replaced/logged with their assigned /// values. There can only be a single tracer defined for each database @@ -90,8 +91,8 @@ impl Connection { } } - /// Register or clear a callback function that can be used for profiling - /// the execution of SQL statements. + /// `feature = "trace"` Register or clear a callback function that can be + /// used for profiling the execution of SQL statements. /// /// There can only be a single profiler defined for each database /// connection. Setting a new profiler clears the old one. diff --git a/src/types/from_sql.rs b/src/types/from_sql.rs index ad3ba85..9d17778 100644 --- a/src/types/from_sql.rs +++ b/src/types/from_sql.rs @@ -13,13 +13,14 @@ pub enum FromSqlError { /// requested type. OutOfRange(i64), - /// Error returned when reading an `i128` from a blob with a size - /// other than 16. Only available when the `i128_blob` feature is enabled. + /// `feature = "i128_blob"` Error returned when reading an `i128` from a + /// blob with a size other than 16. Only available when the `i128_blob` + /// feature is enabled. #[cfg(feature = "i128_blob")] InvalidI128Size(usize), - /// Error returned when reading a `uuid` from a blob with a size - /// other than 16. Only available when the `uuid` feature is enabled. + /// `feature = "uuid"` Error returned when reading a `uuid` from a blob with + /// a size other than 16. Only available when the `uuid` feature is enabled. #[cfg(feature = "uuid")] InvalidUuidSize(usize), diff --git a/src/types/to_sql.rs b/src/types/to_sql.rs index 458d90d..446511f 100644 --- a/src/types/to_sql.rs +++ b/src/types/to_sql.rs @@ -14,10 +14,12 @@ pub enum ToSqlOutput<'a> { /// An owned SQLite-representable value. Owned(Value), - /// A BLOB of the given length that is filled with zeroes. + /// `feature = "blob"` A BLOB of the given length that is filled with + /// zeroes. #[cfg(feature = "blob")] ZeroBlob(i32), + /// `feature = "array"` #[cfg(feature = "array")] Array(Array), } diff --git a/src/vtab/array.rs b/src/vtab/array.rs index 8be185c..dcbe88c 100644 --- a/src/vtab/array.rs +++ b/src/vtab/array.rs @@ -1,6 +1,30 @@ -//! Array Virtual Table. +//! `feature = "array"` Array Virtual Table: https://www.sqlite.org/carray.html +//! +//! Note: `rarray`, not `carray` is the name of the table valued function we +//! define. //! //! Port of [carray](http://www.sqlite.org/cgi/src/finfo?name=ext/misc/carray.c) C extension. +//! +//! # Example +//! +//! ```rust,no_run +//! # use rusqlite::{types::Value, Connection, Result, params}; +//! # use std::rc::Rc; +//! fn example(db: &Connection) -> Result<()> { +//! // Note: This should be done once (usually when opening the DB). +//! rusqlite::vtab::array::load_module(&db)?; +//! let v = [1i64, 2, 3, 4]; +//! // Note: A `Rc>` must be used as the parameter. +//! let values = Rc::new(v.iter().copied().map(Value::from).collect::>()); +//! let mut stmt = db.prepare("SELECT value from rarray(?);")?; +//! let rows = stmt.query_map(params![values], |row| row.get::<_, i64>(0))?; +//! for value in rows { +//! println!("{}", value?); +//! } +//! Ok(()) +//! } +//! ``` + use std::default::Default; use std::os::raw::{c_char, c_int, c_void}; use std::rc::Rc; @@ -29,7 +53,7 @@ impl ToSql for Array { } } -/// Register the "rarray" module. +/// `feature = "array"` Register the "rarray" module. pub fn load_module(conn: &Connection) -> Result<()> { let aux: Option<()> = None; conn.create_module("rarray", &ARRAY_MODULE, aux) diff --git a/src/vtab/csvtab.rs b/src/vtab/csvtab.rs index cb6aeac..7e2441d 100644 --- a/src/vtab/csvtab.rs +++ b/src/vtab/csvtab.rs @@ -1,6 +1,25 @@ -//! CSV Virtual Table. +//! `feature = "csvtab"` CSV Virtual Table: https://www.sqlite.org/csv.html //! //! Port of [csv](http://www.sqlite.org/cgi/src/finfo?name=ext/misc/csv.c) C extension. +//! +//! # Example +//! +//! ```rust,no_run +//! # use rusqlite::{Connection, Result}; +//! fn example() -> Result<()> { +//! // Note: This should be done once (usually when opening the DB). +//! let db = Connection::open_in_memory()?; +//! rusqlite::vtab::csvtab::load_module(&db)?; +//! // Assum3e my_csv.csv +//! let schema = " +//! CREATE VIRTUAL TABLE my_csv_data +//! USING csv(filename = 'my_csv.csv') +//! "; +//! db.execute_batch(schema)?; +//! // Now the `my_csv_data` (virtual) table can be queried as normal... +//! Ok(()) +//! } +//! ``` use std::fs::File; use std::os::raw::c_int; use std::path::Path; @@ -15,7 +34,7 @@ use crate::vtab::{ }; use crate::{Connection, Error, Result}; -/// Register the "csv" module. +/// `feature = "csvtab"` Register the "csv" module. /// ```sql /// CREATE VIRTUAL TABLE vtab USING csv( /// filename=FILENAME -- Name of file containing CSV content diff --git a/src/vtab/mod.rs b/src/vtab/mod.rs index 9eab0d5..ef734d3 100644 --- a/src/vtab/mod.rs +++ b/src/vtab/mod.rs @@ -1,4 +1,4 @@ -//! Create virtual tables. +//! `feature = "vtab"` Create virtual tables. //! //! Follow these steps to create your own virtual table: //! 1. Write implemenation of `VTab` and `VTabCursor` traits. @@ -57,7 +57,7 @@ use crate::{str_to_cstring, Connection, Error, InnerConnection, Result}; // ffi::sqlite3_vtab => VTab // ffi::sqlite3_vtab_cursor => VTabCursor -/// Virtual table module +/// `feature = "vtab"` Virtual table module /// /// (See [SQLite doc](https://sqlite.org/c3ref/module.html)) #[repr(C)] @@ -77,7 +77,7 @@ fn zeroed_module() -> ffi::sqlite3_module { unsafe { std::mem::MaybeUninit::zeroed().assume_init() } } -/// Create a read-only virtual table implementation. +/// `feature = "vtab"` Create a read-only virtual table implementation. /// /// Step 2 of [Creating New Virtual Table Implementations](https://sqlite.org/vtab.html#creating_new_virtual_table_implementations). pub fn read_only_module(version: c_int) -> Module { @@ -115,7 +115,7 @@ pub fn read_only_module(version: c_int) -> Module { } } -/// Create an eponymous only virtual table implementation. +/// `feature = "vtab"` Create an eponymous only virtual table implementation. /// /// Step 2 of [Creating New Virtual Table Implementations](https://sqlite.org/vtab.html#creating_new_virtual_table_implementations). pub fn eponymous_only_module(version: c_int) -> Module { @@ -154,6 +154,7 @@ pub fn eponymous_only_module(version: c_int) -> Module { } } +/// `feature = "vtab"` pub struct VTabConnection(*mut ffi::sqlite3); impl VTabConnection { @@ -179,7 +180,7 @@ impl VTabConnection { } } -/// Virtual table instance trait. +/// `feature = "vtab"` Virtual table instance trait. /// /// Implementations must be like: /// ```rust,ignore @@ -214,7 +215,7 @@ pub trait VTab: Sized { fn open(&self) -> Result; } -/// Non-eponymous virtual table instance trait. +/// `feature = "vtab"` Non-eponymous virtual table instance trait. /// /// (See [SQLite doc](https://sqlite.org/c3ref/vtab.html)) pub trait CreateVTab: VTab { @@ -243,7 +244,7 @@ pub trait CreateVTab: VTab { } } -///Index constraint operator. +/// `feature = "vtab"` Index constraint operator. #[derive(Debug, PartialEq)] #[allow(non_snake_case, non_camel_case_types)] pub enum IndexConstraintOp { @@ -286,8 +287,8 @@ impl From for IndexConstraintOp { } } -/// Pass information into and receive the reply from the `VTab.best_index` -/// method. +/// `feature = "vtab"` Pass information into and receive the reply from the +/// `VTab.best_index` method. /// /// (See [SQLite doc](http://sqlite.org/c3ref/index_info.html)) pub struct IndexInfo(*mut ffi::sqlite3_index_info); @@ -358,6 +359,7 @@ impl IndexInfo { // TODO sqlite3_vtab_collation (http://sqlite.org/c3ref/vtab_collation.html) } +/// `feature = "vtab"` pub struct IndexConstraintIter<'a> { iter: slice::Iter<'a, ffi::sqlite3_index_constraint>, } @@ -374,7 +376,7 @@ impl<'a> Iterator for IndexConstraintIter<'a> { } } -/// WHERE clause constraint +/// `feature = "vtab"` WHERE clause constraint. pub struct IndexConstraint<'a>(&'a ffi::sqlite3_index_constraint); impl IndexConstraint<'_> { @@ -394,7 +396,7 @@ impl IndexConstraint<'_> { } } -/// Information about what parameters to pass to `VTabCursor.filter`. +/// `feature = "vtab"` Information about what parameters to pass to `VTabCursor.filter`. pub struct IndexConstraintUsage<'a>(&'a mut ffi::sqlite3_index_constraint_usage); impl IndexConstraintUsage<'_> { @@ -409,6 +411,7 @@ impl IndexConstraintUsage<'_> { } } +/// `feature = "vtab"` pub struct OrderByIter<'a> { iter: slice::Iter<'a, ffi::sqlite3_index_info_sqlite3_index_orderby>, } @@ -425,7 +428,7 @@ impl<'a> Iterator for OrderByIter<'a> { } } -/// A column of the ORDER BY clause. +/// `feature = "vtab"` A column of the ORDER BY clause. pub struct OrderBy<'a>(&'a ffi::sqlite3_index_info_sqlite3_index_orderby); impl OrderBy<'_> { @@ -440,7 +443,7 @@ impl OrderBy<'_> { } } -/// Virtual table cursor trait. +/// `feature = "vtab"` Virtual table cursor trait. /// /// Implementations must be like: /// ```rust,ignore @@ -474,7 +477,7 @@ pub trait VTabCursor: Sized { fn rowid(&self) -> Result; } -/// Context is used by `VTabCursor.column` to specify the cell value. +/// `feature = "vtab"` Context is used by `VTabCursor.column` to specify the cell value. pub struct Context(*mut ffi::sqlite3_context); impl Context { @@ -487,8 +490,8 @@ impl Context { // TODO sqlite3_vtab_nochange (http://sqlite.org/c3ref/vtab_nochange.html) } -/// Wrapper to `VTabCursor.filter` arguments, the values requested by -/// `VTab.best_index`. +/// `feature = "vtab"` Wrapper to `VTabCursor.filter` arguments, the values +/// requested by `VTab.best_index`. pub struct Values<'a> { args: &'a [*mut ffi::sqlite3_value], } @@ -576,7 +579,7 @@ impl<'a> Iterator for ValueIter<'a> { } impl Connection { - /// Register a virtual table implementation. + /// `feature = "vtab"` Register a virtual table implementation. /// /// Step 3 of [Creating New Virtual Table Implementations](https://sqlite.org/vtab.html#creating_new_virtual_table_implementations). pub fn create_module( @@ -624,7 +627,8 @@ impl InnerConnection { } } -/// Escape double-quote (`"`) character occurences by doubling them (`""`). +/// `feature = "vtab"` Escape double-quote (`"`) character occurences by +/// doubling them (`""`). pub fn escape_double_quote(identifier: &str) -> Cow<'_, str> { if identifier.contains('"') { // escape quote by doubling them @@ -633,7 +637,7 @@ pub fn escape_double_quote(identifier: &str) -> Cow<'_, str> { Borrowed(identifier) } } -/// Dequote string +/// `feature = "vtab"` Dequote string pub fn dequote(s: &str) -> &str { if s.len() < 2 { return s; @@ -646,7 +650,7 @@ pub fn dequote(s: &str) -> &str { _ => s, } } -/// The boolean can be one of: +/// `feature = "vtab"` The boolean can be one of: /// ```text /// 1 yes true on /// 0 no false off diff --git a/src/vtab/series.rs b/src/vtab/series.rs index c0d1100..c4117ca 100644 --- a/src/vtab/series.rs +++ b/src/vtab/series.rs @@ -1,4 +1,4 @@ -//! generate series virtual table. +//! `feature = "series"` Generate series virtual table: https://www.sqlite.org/series.html //! //! Port of C [generate series "function"](http://www.sqlite.org/cgi/src/finfo?name=ext/misc/series.c). use std::default::Default; @@ -12,7 +12,7 @@ use crate::vtab::{ }; use crate::{Connection, Result}; -/// Register the "generate_series" module. +/// `feature = "series"` Register the "generate_series" module. pub fn load_module(conn: &Connection) -> Result<()> { let aux: Option<()> = None; conn.create_module("generate_series", &SERIES_MODULE, aux)