From 3c56489dcaa19f9a1a011abec10a523bb54d2095 Mon Sep 17 00:00:00 2001 From: Thijs Cadier Date: Sat, 26 Dec 2015 13:34:39 +0100 Subject: [PATCH] Documentation for collection --- src/collection.rs | 95 +++++++++++++++++++++++++++++++++++++---------- src/lib.rs | 8 ++++ 2 files changed, 83 insertions(+), 20 deletions(-) diff --git a/src/collection.rs b/src/collection.rs index 01dc8ef..e969592 100644 --- a/src/collection.rs +++ b/src/collection.rs @@ -1,3 +1,7 @@ +//! Access to a MongoDB collection +//! +//! Collection is the main type used when accessing collections. + use std::ptr; use std::ffi::CStr; use std::borrow::Cow; @@ -20,6 +24,7 @@ use super::flags::{Flags,FlagsValue,InsertFlag,QueryFlag,RemoveFlag,UpdateFlag}; use super::write_concern::WriteConcern; use super::read_prefs::ReadPrefs; +#[doc(hidden)] pub enum CreatedBy<'a> { BorrowedClient(&'a Client<'a>), OwnedClient(Client<'a>), @@ -27,14 +32,18 @@ pub enum CreatedBy<'a> { OwnedDatabase(Database<'a>) } +/// Provides access to a collection for most CRUD operations, I.e. insert, update, delete, find, etc. +/// +/// A collection instance can be created by calling `get_collection` on a `Client` or `Database` +/// instance. pub struct Collection<'a> { _created_by: CreatedBy<'a>, inner: *mut bindings::mongoc_collection_t } -/// Options to configure a `BulkOperation`. +/// Options to configure a bulk operation. pub struct BulkOperationOptions { - /// If the operations must be performed in order. + /// If the operations must be performed in order pub ordered: bool, /// `WriteConcern` to use pub write_concern: WriteConcern @@ -51,13 +60,18 @@ impl BulkOperationOptions { } } +/// Options to configure a find and modify operation. pub struct FindAndModifyOptions { + /// Sort order for the query pub sort: Option, + /// If the new version of the document should be returned pub new: bool, + /// The fields to return pub fields: Option } impl FindAndModifyOptions { + /// Default options used if none are provided. pub fn default() -> FindAndModifyOptions { FindAndModifyOptions { sort: None, @@ -74,21 +88,32 @@ impl FindAndModifyOptions { } } +/// Possible find and modify operations. pub enum FindAndModifyOperation<'a> { + /// Update the matching documents Update(&'a Document), + /// Upsert the matching documents Upsert(&'a Document), + /// Remove the matching documents Remove } +/// Options to configure a count operation. pub struct CountOptions { + /// The query flags to use pub query_flags: Flags, + /// Number of results to skip, zero to ignore pub skip: u32, + /// Limit to the number of results, zero to ignore pub limit: u32, + /// Optional extra keys to add to the count pub opts: Option, + /// Read prefs to use pub read_prefs: Option } impl CountOptions { + /// Default options used if none are provided. pub fn default() -> CountOptions { CountOptions { query_flags: Flags::new(), @@ -100,12 +125,16 @@ impl CountOptions { } } +/// Options to configure an insert operation. pub struct InsertOptions { + /// Flags to use pub insert_flags: Flags, + /// Write concern to use pub write_concern: WriteConcern } impl InsertOptions { + /// Default options used if none are provided. pub fn default() -> InsertOptions { InsertOptions { insert_flags: Flags::new(), @@ -114,12 +143,16 @@ impl InsertOptions { } } +/// Options to configure a remove operation. pub struct RemoveOptions { + /// Flags to use pub remove_flags: Flags, + /// Write concern to use pub write_concern: WriteConcern } impl RemoveOptions { + /// Default options used if none are provided. pub fn default() -> RemoveOptions { RemoveOptions { remove_flags: Flags::new(), @@ -128,12 +161,16 @@ impl RemoveOptions { } } +/// Options to configure an update operation. pub struct UpdateOptions { + /// Flags to use pub update_flags: Flags, + /// Write concern to use pub write_concern: WriteConcern } impl UpdateOptions { + /// Default options used if none are provided. pub fn default() -> UpdateOptions { UpdateOptions { update_flags: Flags::new(), @@ -142,12 +179,16 @@ impl UpdateOptions { } } +/// Options to configure a tailing query. pub struct TailOptions { + /// Duration to wait before checking for new results pub wait_duration: Duration, + /// Maximum number of retries if there is an error pub max_retries: u32 } impl TailOptions { + /// Default options used if none are provided. pub fn default() -> TailOptions { TailOptions { wait_duration: Duration::from_millis(500), @@ -157,6 +198,7 @@ impl TailOptions { } impl<'a> Collection<'a> { + #[doc(hidden)] pub fn new( created_by: CreatedBy<'a>, inner: *mut bindings::mongoc_collection_t @@ -169,8 +211,7 @@ impl<'a> Collection<'a> { } /// Execute a command on the collection - /// - /// See: http://api.mongodb.org/c/current/mongoc_collection_command.html + /// This is performed lazily and therefore requires calling `next` on the resulting cursor. pub fn command( &'a self, command: Document, @@ -212,19 +253,14 @@ impl<'a> Collection<'a> { )) } - /// Simplified version of command that returns the first document - /// - /// See: http://api.mongodb.org/c/current/mongoc_database_command_simple.html + /// Simplified version of `command` that returns the first document immediately. pub fn command_simple( &'a self, command: Document, - options: Option<&CommandAndFindOptions> + read_prefs: Option<&ReadPrefs> ) -> Result { assert!(!self.inner.is_null()); - let default_options = CommandAndFindOptions::default(); - let options = options.unwrap_or(&default_options); - // Bsonc to store the reply let mut reply = Bsonc::new(); // Empty error that might be filled @@ -234,7 +270,7 @@ impl<'a> Collection<'a> { bindings::mongoc_collection_command_simple( self.inner, try!(Bsonc::from_document(&command)).inner(), - match options.read_prefs { + match read_prefs { Some(ref prefs) => prefs.inner(), None => ptr::null() }, @@ -253,6 +289,10 @@ impl<'a> Collection<'a> { } } + /// Execute a count query on the underlying collection. + /// The `query` bson is not validated, simply passed along to the server. As such, compatibility and errors should be validated in the appropriate server documentation. + /// + /// For more information, see the [query reference](https://docs.mongodb.org/manual/reference/operator/query/) at the MongoDB website. pub fn count( &self, query: &Document, @@ -294,6 +334,9 @@ impl<'a> Collection<'a> { } } + /// Create a bulk operation. After creating call various functions such as `update`, + /// `insert` and others. When calling `execute` these operations will be executed in + /// batches. pub fn create_bulk_operation( &'a self, options: Option<&BulkOperationOptions> @@ -314,6 +357,7 @@ impl<'a> Collection<'a> { BulkOperation::new(self, inner) } + /// Request that a collection be dropped, including all indexes associated with the collection. pub fn drop(&mut self) -> Result<()> { assert!(!self.inner.is_null()); let mut error = BsoncError::empty(); @@ -330,6 +374,10 @@ impl<'a> Collection<'a> { Ok(()) } + /// Execute a query on the underlying collection. + /// If no options are necessary, query can simply contain a query such as `{a:1}`. + /// If you would like to specify options such as a sort order, the query must be placed inside of `{"$query": {}}` + /// as specified by the server documentation. See the example below for how to properly specify additional options to query. pub fn find( &'a self, query: &Document, @@ -371,10 +419,9 @@ impl<'a> Collection<'a> { )) } - // Update and return an object. - // - // This is a thin wrapper around the findAndModify command. Pass in - // an operation that either updates, upserts or removes. + /// Update and return an object. + /// This is a thin wrapper around the findAndModify command. Pass in + /// an operation that either updates, upserts or removes. pub fn find_and_modify( &'a self, query: &Document, @@ -447,6 +494,7 @@ impl<'a> Collection<'a> { } } + /// Get the name of the collection. pub fn get_name(&self) -> Cow { let cstr = unsafe { CStr::from_ptr(bindings::mongoc_collection_get_name(self.inner)) @@ -454,6 +502,9 @@ impl<'a> Collection<'a> { String::from_utf8_lossy(cstr.to_bytes()) } + /// Insert document into collection. + /// If no `_id` element is found in document, then an id will be generated locally and added to the document. + // TODO: You can retrieve a generated _id from mongoc_collection_get_last_error(). pub fn insert( &'a self, document: &Document, @@ -482,6 +533,9 @@ impl<'a> Collection<'a> { } } + /// Remove documents in the given collection that match selector. + /// The bson `selector` is not validated, simply passed along as appropriate to the server. As such, compatibility and errors should be validated in the appropriate server documentation. + /// If you want to limit deletes to a single document, add the `SingleRemove` flag. pub fn remove( &self, selector: &Document, @@ -510,6 +564,8 @@ impl<'a> Collection<'a> { } } + /// Save a document into the collection. If the document has an `_id` field it will be updated. + /// Otherwise it will be inserted. pub fn save( &self, document: &Document, @@ -537,9 +593,8 @@ impl<'a> Collection<'a> { } } - /// This function shall update documents in collection that match selector. - /// - /// See: http://api.mongodb.org/c/current/mongoc_collection_update.html + /// This function updates documents in collection that match selector. + /// By default, updates only a single document. Add `MultiUpdate` flag to update multiple documents. pub fn update( &self, selector: &Document, @@ -616,7 +671,7 @@ impl<'a> Drop for Collection<'a> { /// /// Create a `BulkOperation` by calling `create_bulk_operation` on a `Collection`. After adding all of /// the write operations using the functions on this struct, `execute` to execute the operation on -/// the server. After executing the bulk operation is consumed and cannot be used anymore. +/// the server in batches. After executing the bulk operation is consumed and cannot be used anymore. pub struct BulkOperation<'a> { _collection: &'a Collection<'a>, inner: *mut bindings::mongoc_bulk_operation_t diff --git a/src/lib.rs b/src/lib.rs index f2f3a04..1bbdb08 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -96,16 +96,24 @@ unsafe extern "C" fn mongoc_log_handler( } } +/// Options to configure both command and find operations. pub struct CommandAndFindOptions { + /// Flags to use pub query_flags: flags::Flags, + /// Number of documents to skip, zero to ignore pub skip: u32, + /// Max number of documents to return, zero to ignore pub limit: u32, + /// Number of documents in each batch, zero to ignore (default is 100) pub batch_size: u32, + /// Fields to return, not all commands support this option pub fields: Option, + /// Read prefs to use pub read_prefs: Option } impl CommandAndFindOptions { + /// Default options used if none are provided. pub fn default() -> CommandAndFindOptions { CommandAndFindOptions { query_flags: flags::Flags::new(),