Rename retain to reference, and wrap to take_ownership, and update doc comments

Nao-ris · Nao-ris · commit 689883a2c36d · 2025-03-12T15:00:47.000+01:00
diff --git a/src/collection.rs b/src/collection.rs
@@ -56,23 +56,23 @@ impl Collection {
 
     //////// CONSTRUCTORS:
 
-    /// Takes ownership of the object and increase it's reference counter.
-    pub(crate) fn retain(cbl_ref: *mut CBLCollection) -> Self {
+    /// Increase the reference counter of the CBL ref, so dropping the instance will NOT free the ref.
+    pub(crate) fn reference(cbl_ref: *mut CBLCollection) -> Self {
         Self {
             cbl_ref: unsafe { retain(cbl_ref) },
         }
     }
 
-    /// References the object without taking ownership and increasing it's reference counter
-    pub(crate) const fn wrap(cbl_ref: *mut CBLCollection) -> Self {
+    /// Takes ownership of the CBL ref, the reference counter is not increased so dropping the instance will free the ref.
+    pub(crate) const fn take_ownership(cbl_ref: *mut CBLCollection) -> Self {
         Self { cbl_ref }
     }
 
     ////////
 
     /// Returns the scope of the collection.
     pub fn scope(&self) -> Scope {
-        unsafe { Scope::wrap(CBLCollection_Scope(self.get_ref())) }
+        unsafe { Scope::take_ownership(CBLCollection_Scope(self.get_ref())) }
     }
 
     /// Returns the collection name.
@@ -95,7 +95,7 @@ impl Collection {
 
     /// Returns the collection's database.
     pub fn database(&self) -> Database {
-        unsafe { Database::retain(CBLCollection_Database(self.get_ref())) }
+        unsafe { Database::reference(CBLCollection_Database(self.get_ref())) }
     }
 
     /// Returns the number of documents in the collection.
@@ -141,7 +141,7 @@ impl Drop for Collection {
 
 impl Clone for Collection {
     fn clone(&self) -> Self {
-        Self::retain(self.get_ref())
+        Self::reference(self.get_ref())
     }
 }
 
@@ -155,7 +155,7 @@ unsafe extern "C" fn c_collection_change_listener(
 ) {
     let callback = context as *const CollectionChangeListener;
     if let Some(change) = change.as_ref() {
-        let collection = Collection::retain(change.collection as *mut CBLCollection);
+        let collection = Collection::reference(change.collection as *mut CBLCollection);
         let doc_ids = std::slice::from_raw_parts(change.docIDs, change.numDocs as usize)
             .iter()
             .filter_map(|doc_id| doc_id.to_string())
diff --git a/src/database.rs b/src/database.rs
@@ -140,7 +140,7 @@ unsafe extern "C" fn c_database_change_listener(
     c_doc_ids: *mut FLString,
 ) {
     let callback = context as *const DatabaseChangeListener;
-    let database = Database::retain(db as *mut CBLDatabase);
+    let database = Database::reference(db as *mut CBLDatabase);
 
     let doc_ids = std::slice::from_raw_parts(c_doc_ids, num_docs as usize)
         .iter()
@@ -159,7 +159,7 @@ unsafe extern "C" fn c_database_buffer_notifications(
 ) {
     let callback: BufferNotifications = std::mem::transmute(context);
 
-    let database = Database::retain(db.cast::<CBLDatabase>());
+    let database = Database::reference(db.cast::<CBLDatabase>());
 
     callback(&database);
 }
@@ -180,15 +180,15 @@ impl CblRef for Database {
 impl Database {
     //////// CONSTRUCTORS:
 
-    /// Takes ownership of the object and increase it's reference counter.
-    pub(crate) fn retain(cbl_ref: *mut CBLDatabase) -> Self {
+    /// Increase the reference counter of the CBL ref, so dropping the instance will NOT free the ref.
+    pub(crate) fn reference(cbl_ref: *mut CBLDatabase) -> Self {
         Self {
             cbl_ref: unsafe { retain(cbl_ref) },
         }
     }
 
-    /// References the object without taking ownership and increasing it's reference counter
-    pub(crate) const fn wrap(cbl_ref: *mut CBLDatabase) -> Self {
+    /// Takes ownership of the CBL ref, the reference counter is not increased so dropping the instance will free the ref.
+    pub(crate) const fn take_ownership(cbl_ref: *mut CBLDatabase) -> Self {
         Self { cbl_ref }
     }
 
@@ -217,7 +217,7 @@ impl Database {
         if db_ref.is_null() {
             return failure(err);
         }
-        Ok(Self::wrap(db_ref))
+        Ok(Self::take_ownership(db_ref))
     }
 
     //////// OTHER STATIC METHODS:
@@ -418,7 +418,7 @@ impl Database {
             if scope.is_null() {
                 None
             } else {
-                Some(Scope::wrap(scope))
+                Some(Scope::take_ownership(scope))
             }
         })
     }
@@ -445,7 +445,7 @@ impl Database {
             if collection.is_null() {
                 None
             } else {
-                Some(Collection::wrap(collection))
+                Some(Collection::take_ownership(collection))
             }
         })
     }
@@ -474,7 +474,7 @@ impl Database {
             )
         };
 
-        check_error(&error).map(|()| Collection::wrap(collection))
+        check_error(&error).map(|()| Collection::take_ownership(collection))
     }
 
     /// Delete an existing collection.
@@ -499,7 +499,7 @@ impl Database {
         let mut error = CBLError::default();
         let scope = unsafe { CBLDatabase_DefaultScope(self.get_ref(), &mut error) };
 
-        check_error(&error).map(|()| Scope::wrap(scope))
+        check_error(&error).map(|()| Scope::take_ownership(scope))
     }
 
     /// Returns the default collection.
@@ -511,7 +511,7 @@ impl Database {
             if collection.is_null() {
                 None
             } else {
-                Some(Collection::wrap(collection))
+                Some(Collection::take_ownership(collection))
             }
         })
     }
@@ -526,7 +526,7 @@ impl Database {
         if collection.is_null() {
             Err(Error::cbl_error(CouchbaseLiteError::NotFound))
         } else {
-            Ok(Collection::wrap(collection))
+            Ok(Collection::take_ownership(collection))
         }
     }
 
@@ -596,6 +596,6 @@ impl Drop for Database {
 
 impl Clone for Database {
     fn clone(&self) -> Self {
-        Self::retain(self.get_ref())
+        Self::reference(self.get_ref())
     }
 }
diff --git a/src/document.rs b/src/document.rs
@@ -75,8 +75,8 @@ unsafe extern "C" fn c_conflict_handler(
     let callback: ConflictHandler = std::mem::transmute(context);
 
     callback(
-        &mut Document::retain(document_being_saved),
-        &Document::retain(conflicting_document as *mut CBLDocument),
+        &mut Document::reference(document_being_saved),
+        &Document::reference(conflicting_document as *mut CBLDocument),
     )
 }
 
@@ -92,7 +92,7 @@ unsafe extern "C" fn c_database_document_change_listener(
     c_doc_id: FLString,
 ) {
     let callback = context as *const DatabaseDocumentChangeListener;
-    let database = Database::retain(db as *mut CBLDatabase);
+    let database = Database::reference(db as *mut CBLDatabase);
     (*callback)(&database, c_doc_id.to_string());
 }
 
@@ -116,7 +116,7 @@ impl Database {
                     failure(error)
                 };
             }
-            Ok(Document::wrap(doc))
+            Ok(Document::take_ownership(doc))
         }
     }
 
@@ -315,7 +315,7 @@ unsafe extern "C" fn c_collection_document_change_listener(
 ) {
     let callback = context as *const CollectionDocumentChangeListener;
     if let Some(change) = change.as_ref() {
-        let collection = Collection::retain(change.collection as *mut CBLCollection);
+        let collection = Collection::reference(change.collection as *mut CBLCollection);
         (*callback)(collection, change.docID.to_string());
     }
 }
@@ -340,7 +340,7 @@ impl Collection {
                     failure(error)
                 };
             }
-            Ok(Document::wrap(doc))
+            Ok(Document::take_ownership(doc))
         }
     }
 
@@ -515,26 +515,26 @@ impl Document {
     /// Creates a new, empty document in memory, with an automatically generated unique ID.
     /// It will not be added to a database until saved.
     pub fn new() -> Self {
-        unsafe { Self::wrap(CBLDocument_Create()) }
+        unsafe { Self::take_ownership(CBLDocument_Create()) }
     }
 
     /// Creates a new, empty document in memory, with the given ID.
     /// It will not be added to a database until saved.
     pub fn new_with_id(id: &str) -> Self {
-        unsafe { Self::wrap(CBLDocument_CreateWithID(from_str(id).get_ref())) }
+        unsafe { Self::take_ownership(CBLDocument_CreateWithID(from_str(id).get_ref())) }
     }
 
-    /// Takes ownership of the object and increase it's reference counter.
-    pub(crate) fn retain(cbl_ref: *mut CBLDocument) -> Self {
+    /// Increase the reference counter of the CBL ref, so dropping the instance will NOT free the ref.
+    pub(crate) fn reference(cbl_ref: *mut CBLDocument) -> Self {
         unsafe {
             Self {
                 cbl_ref: retain(cbl_ref),
             }
         }
     }
 
-    /// References the object without taking ownership and increasing it's reference counter
-    pub(crate) const fn wrap(cbl_ref: *mut CBLDocument) -> Self {
+    /// Takes ownership of the CBL ref, the reference counter is not increased so dropping the instance will free the ref.
+    pub(crate) const fn take_ownership(cbl_ref: *mut CBLDocument) -> Self {
         Self { cbl_ref }
     }
 
@@ -607,6 +607,6 @@ impl Drop for Document {
 
 impl Clone for Document {
     fn clone(&self) -> Self {
-        Self::retain(self.get_ref())
+        Self::reference(self.get_ref())
     }
 }
diff --git a/src/encryptable.rs b/src/encryptable.rs
@@ -66,15 +66,15 @@ impl CblRef for Encryptable {
 
 impl From<*mut CBLEncryptable> for Encryptable {
     fn from(cbl_ref: *mut CBLEncryptable) -> Self {
-        Self::retain(cbl_ref)
+        Self::reference(cbl_ref)
     }
 }
 
 impl Encryptable {
     //////// CONSTRUCTORS:
 
-    /// Takes ownership of the object and increase it's reference counter.
-    pub(crate) fn retain(cbl_ref: *mut CBLEncryptable) -> Self {
+    /// Increase the reference counter of the CBL ref, so dropping the instance will NOT free the ref.
+    pub(crate) fn reference(cbl_ref: *mut CBLEncryptable) -> Self {
         Self {
             cbl_ref: unsafe { retain(cbl_ref) },
         }
diff --git a/src/fleece.rs b/src/fleece.rs
@@ -323,7 +323,7 @@ impl Value {
     pub fn get_encryptable_value(&self) -> Encryptable {
         unsafe {
             let encryptable = FLDict_GetEncryptableValue(FLValue_AsDict(self.get_ref()));
-            Encryptable::retain(encryptable as *mut CBLEncryptable)
+            Encryptable::reference(encryptable as *mut CBLEncryptable)
         }
     }
 
@@ -598,7 +598,7 @@ impl Dict {
     pub fn get_encryptable_value(&self) -> Encryptable {
         unsafe {
             let encryptable = FLDict_GetEncryptableValue(self.get_ref());
-            Encryptable::retain(encryptable as *mut CBLEncryptable)
+            Encryptable::reference(encryptable as *mut CBLEncryptable)
         }
     }
 
diff --git a/src/index.rs b/src/index.rs
@@ -148,16 +148,16 @@ impl CblRef for QueryIndex {
 impl QueryIndex {
     //////// CONSTRUCTORS:
 
-    /// Takes ownership of the object and increase it's reference counter.
+    /// Increase the reference counter of the CBL ref, so dropping the instance will NOT free the ref.
     #[allow(dead_code)]
-    pub(crate) fn retain(cbl_ref: *mut CBLQueryIndex) -> Self {
+    pub(crate) fn reference(cbl_ref: *mut CBLQueryIndex) -> Self {
         Self {
             cbl_ref: unsafe { retain(cbl_ref) },
         }
     }
 
-    /// References the object without taking ownership and increasing it's reference counter
-    pub(crate) const fn wrap(cbl_ref: *mut CBLQueryIndex) -> Self {
+    /// Takes ownership of the CBL ref, the reference counter is not increased so dropping the instance will free the ref.
+    pub(crate) const fn take_ownership(cbl_ref: *mut CBLQueryIndex) -> Self {
         Self { cbl_ref }
     }
 
@@ -174,7 +174,7 @@ impl QueryIndex {
 
     /// Returns the collection that the index belongs to.
     pub fn collection(&self) -> Collection {
-        unsafe { Collection::retain(CBLQueryIndex_Collection(self.get_ref())) }
+        unsafe { Collection::reference(CBLQueryIndex_Collection(self.get_ref())) }
     }
 }
 
@@ -292,7 +292,7 @@ impl Collection {
         let slice = from_str(name);
         let index = unsafe { CBLCollection_GetIndex(self.get_ref(), slice.get_ref(), &mut err) };
         if !err {
-            return Ok(QueryIndex::wrap(index));
+            return Ok(QueryIndex::take_ownership(index));
         }
         failure(err)
     }
diff --git a/src/query.rs b/src/query.rs
@@ -48,7 +48,7 @@ unsafe extern "C" fn c_query_change_listener(
     token: *mut CBLListenerToken,
 ) {
     let callback = context as *const ChangeListener;
-    let query = Query::wrap(query.cast::<CBLQuery>());
+    let query = Query::reference(query.cast::<CBLQuery>());
     let token = ListenerToken::new(token);
 
     (*callback)(&query, &token);
@@ -88,16 +88,22 @@ impl Query {
                 return failure(err);
             }
 
-            Ok(Self { cbl_ref: q })
+            Ok(Self::take_ownership(q))
         }
     }
 
-    pub(crate) fn wrap(cbl_ref: *mut CBLQuery) -> Self {
+    /// Increase the reference counter of the CBL ref, so dropping the instance will NOT free the ref.
+    pub(crate) fn reference(cbl_ref: *mut CBLQuery) -> Self {
         Self {
             cbl_ref: unsafe { retain(cbl_ref) },
         }
     }
 
+    /// Takes ownership of the CBL ref, the reference counter is not increased so dropping the instance will free the ref.
+    pub(crate) const fn take_ownership(cbl_ref: *mut CBLQuery) -> Self {
+        Self { cbl_ref }
+    }
+
     /** Assigns values to the query's parameters.
     These values will be substited for those parameters whenever the query is executed,
     until they are next assigned.
diff --git a/src/replicator.rs b/src/replicator.rs
@@ -262,7 +262,7 @@ unsafe extern "C" fn c_replication_push_filter(
     flags: CBLDocumentFlags,
 ) -> bool {
     let repl_conf_context = context as *const ReplicationConfigurationContext;
-    let document = Document::retain(document.cast::<CBLDocument>());
+    let document = Document::reference(document.cast::<CBLDocument>());
     let (is_deleted, is_access_removed) = read_document_flags(flags);
 
     (*repl_conf_context)
@@ -276,7 +276,7 @@ unsafe extern "C" fn c_replication_pull_filter(
     flags: CBLDocumentFlags,
 ) -> bool {
     let repl_conf_context = context as *const ReplicationConfigurationContext;
-    let document = Document::retain(document.cast::<CBLDocument>());
+    let document = Document::reference(document.cast::<CBLDocument>());
     let (is_deleted, is_access_removed) = read_document_flags(flags);
 
     (*repl_conf_context)
@@ -307,12 +307,12 @@ unsafe extern "C" fn c_replication_conflict_resolver(
     let local_document = if local_document.is_null() {
         None
     } else {
-        Some(Document::retain(local_document as *mut CBLDocument))
+        Some(Document::reference(local_document as *mut CBLDocument))
     };
     let remote_document = if remote_document.is_null() {
         None
     } else {
-        Some(Document::retain(remote_document as *mut CBLDocument))
+        Some(Document::reference(remote_document as *mut CBLDocument))
     };
 
     (*repl_conf_context)
diff --git a/src/scope.rs b/src/scope.rs
diff --git a/src/slice.rs b/src/slice.rs

Original file line number	Diff line number	Diff line change
`@@ -140,7 +140,7 @@ unsafe extern "C" fn c_database_change_listener(`
`140`	`140`	`c_doc_ids: *mut FLString,`
`141`	`141`	`) {`
`142`	`142`	`let callback = context as *const DatabaseChangeListener;`
`143`		`- let database = Database::retain(db as *mut CBLDatabase);`
	`143`	`+ let database = Database::reference(db as *mut CBLDatabase);`
`144`	`144`
`145`	`145`	`let doc_ids = std::slice::from_raw_parts(c_doc_ids, num_docs as usize)`
`146`	`146`	`.iter()`
`@@ -159,7 +159,7 @@ unsafe extern "C" fn c_database_buffer_notifications(`
`159`	`159`	`) {`
`160`	`160`	`let callback: BufferNotifications = std::mem::transmute(context);`
`161`	`161`
`162`		`- let database = Database::retain(db.cast::<CBLDatabase>());`
	`162`	`+ let database = Database::reference(db.cast::<CBLDatabase>());`
`163`	`163`
`164`	`164`	`callback(&database);`
`165`	`165`	`}`
`@@ -180,15 +180,15 @@ impl CblRef for Database {`
`180`	`180`	`impl Database {`
`181`	`181`	`//////// CONSTRUCTORS:`
`182`	`182`
`183`		`- /// Takes ownership of the object and increase it's reference counter.`
`184`		`- pub(crate) fn retain(cbl_ref: *mut CBLDatabase) -> Self {`
	`183`	`+ /// Increase the reference counter of the CBL ref, so dropping the instance will NOT free the ref.`
	`184`	`+ pub(crate) fn reference(cbl_ref: *mut CBLDatabase) -> Self {`
`185`	`185`	`Self {`
`186`	`186`	`cbl_ref: unsafe { retain(cbl_ref) },`
`187`	`187`	`}`
`188`	`188`	`}`
`189`	`189`
`190`		`- /// References the object without taking ownership and increasing it's reference counter`
`191`		`- pub(crate) const fn wrap(cbl_ref: *mut CBLDatabase) -> Self {`
	`190`	`+ /// Takes ownership of the CBL ref, the reference counter is not increased so dropping the instance will free the ref.`
	`191`	`+ pub(crate) const fn take_ownership(cbl_ref: *mut CBLDatabase) -> Self {`
`192`	`192`	`Self { cbl_ref }`
`193`	`193`	`}`
`194`	`194`
`@@ -217,7 +217,7 @@ impl Database {`
`217`	`217`	`if db_ref.is_null() {`
`218`	`218`	`return failure(err);`
`219`	`219`	`}`
`220`		`- Ok(Self::wrap(db_ref))`
	`220`	`+ Ok(Self::take_ownership(db_ref))`
`221`	`221`	`}`
`222`	`222`
`223`	`223`	`//////// OTHER STATIC METHODS:`
`@@ -418,7 +418,7 @@ impl Database {`
`418`	`418`	`if scope.is_null() {`
`419`	`419`	`None`
`420`	`420`	`} else {`
`421`		`- Some(Scope::wrap(scope))`
	`421`	`+ Some(Scope::take_ownership(scope))`
`422`	`422`	`}`
`423`	`423`	`})`
`424`	`424`	`}`
`@@ -445,7 +445,7 @@ impl Database {`
`445`	`445`	`if collection.is_null() {`
`446`	`446`	`None`
`447`	`447`	`} else {`
`448`		`- Some(Collection::wrap(collection))`
	`448`	`+ Some(Collection::take_ownership(collection))`
`449`	`449`	`}`
`450`	`450`	`})`
`451`	`451`	`}`
`@@ -474,7 +474,7 @@ impl Database {`
`474`	`474`	`)`
`475`	`475`	`};`
`476`	`476`
`477`		`- check_error(&error).map(\|()\| Collection::wrap(collection))`
	`477`	`+ check_error(&error).map(\|()\| Collection::take_ownership(collection))`
`478`	`478`	`}`
`479`	`479`
`480`	`480`	`/// Delete an existing collection.`
`@@ -499,7 +499,7 @@ impl Database {`
`499`	`499`	`let mut error = CBLError::default();`
`500`	`500`	`let scope = unsafe { CBLDatabase_DefaultScope(self.get_ref(), &mut error) };`
`501`	`501`
`502`		`- check_error(&error).map(\|()\| Scope::wrap(scope))`
	`502`	`+ check_error(&error).map(\|()\| Scope::take_ownership(scope))`
`503`	`503`	`}`
`504`	`504`
`505`	`505`	`/// Returns the default collection.`
`@@ -511,7 +511,7 @@ impl Database {`
`511`	`511`	`if collection.is_null() {`
`512`	`512`	`None`
`513`	`513`	`} else {`
`514`		`- Some(Collection::wrap(collection))`
	`514`	`+ Some(Collection::take_ownership(collection))`
`515`	`515`	`}`
`516`	`516`	`})`
`517`	`517`	`}`
`@@ -526,7 +526,7 @@ impl Database {`
`526`	`526`	`if collection.is_null() {`
`527`	`527`	`Err(Error::cbl_error(CouchbaseLiteError::NotFound))`
`528`	`528`	`} else {`
`529`		`- Ok(Collection::wrap(collection))`
	`529`	`+ Ok(Collection::take_ownership(collection))`
`530`	`530`	`}`
`531`	`531`	`}`
`532`	`532`
`@@ -596,6 +596,6 @@ impl Drop for Database {`
`596`	`596`
`597`	`597`	`impl Clone for Database {`
`598`	`598`	`fn clone(&self) -> Self {`
`599`		`- Self::retain(self.get_ref())`
	`599`	`+ Self::reference(self.get_ref())`
`600`	`600`	`}`
`601`	`601`	`}`
Original file line number	Diff line number	Diff line change
`@@ -75,8 +75,8 @@ unsafe extern "C" fn c_conflict_handler(`
`75`	`75`	`let callback: ConflictHandler = std::mem::transmute(context);`
`76`	`76`
`77`	`77`	`callback(`
`78`		`- &mut Document::retain(document_being_saved),`
`79`		`- &Document::retain(conflicting_document as *mut CBLDocument),`
	`78`	`+ &mut Document::reference(document_being_saved),`
	`79`	`+ &Document::reference(conflicting_document as *mut CBLDocument),`
`80`	`80`	`)`
`81`	`81`	`}`
`82`	`82`
`@@ -92,7 +92,7 @@ unsafe extern "C" fn c_database_document_change_listener(`
`92`	`92`	`c_doc_id: FLString,`
`93`	`93`	`) {`
`94`	`94`	`let callback = context as *const DatabaseDocumentChangeListener;`
`95`		`- let database = Database::retain(db as *mut CBLDatabase);`
	`95`	`+ let database = Database::reference(db as *mut CBLDatabase);`
`96`	`96`	`(*callback)(&database, c_doc_id.to_string());`
`97`	`97`	`}`
`98`	`98`
`@@ -116,7 +116,7 @@ impl Database {`
`116`	`116`	`failure(error)`
`117`	`117`	`};`
`118`	`118`	`}`
`119`		`- Ok(Document::wrap(doc))`
	`119`	`+ Ok(Document::take_ownership(doc))`
`120`	`120`	`}`
`121`	`121`	`}`
`122`	`122`
`@@ -315,7 +315,7 @@ unsafe extern "C" fn c_collection_document_change_listener(`
`315`	`315`	`) {`
`316`	`316`	`let callback = context as *const CollectionDocumentChangeListener;`
`317`	`317`	`if let Some(change) = change.as_ref() {`
`318`		`- let collection = Collection::retain(change.collection as *mut CBLCollection);`
	`318`	`+ let collection = Collection::reference(change.collection as *mut CBLCollection);`
`319`	`319`	`(*callback)(collection, change.docID.to_string());`
`320`	`320`	`}`
`321`	`321`	`}`
`@@ -340,7 +340,7 @@ impl Collection {`
`340`	`340`	`failure(error)`
`341`	`341`	`};`
`342`	`342`	`}`
`343`		`- Ok(Document::wrap(doc))`
	`343`	`+ Ok(Document::take_ownership(doc))`
`344`	`344`	`}`
`345`	`345`	`}`
`346`	`346`
`@@ -515,26 +515,26 @@ impl Document {`
`515`	`515`	`/// Creates a new, empty document in memory, with an automatically generated unique ID.`
`516`	`516`	`/// It will not be added to a database until saved.`
`517`	`517`	`pub fn new() -> Self {`
`518`		`- unsafe { Self::wrap(CBLDocument_Create()) }`
	`518`	`+ unsafe { Self::take_ownership(CBLDocument_Create()) }`
`519`	`519`	`}`
`520`	`520`
`521`	`521`	`/// Creates a new, empty document in memory, with the given ID.`
`522`	`522`	`/// It will not be added to a database until saved.`
`523`	`523`	`pub fn new_with_id(id: &str) -> Self {`
`524`		`- unsafe { Self::wrap(CBLDocument_CreateWithID(from_str(id).get_ref())) }`
	`524`	`+ unsafe { Self::take_ownership(CBLDocument_CreateWithID(from_str(id).get_ref())) }`
`525`	`525`	`}`
`526`	`526`
`527`		`- /// Takes ownership of the object and increase it's reference counter.`
`528`		`- pub(crate) fn retain(cbl_ref: *mut CBLDocument) -> Self {`
	`527`	`+ /// Increase the reference counter of the CBL ref, so dropping the instance will NOT free the ref.`
	`528`	`+ pub(crate) fn reference(cbl_ref: *mut CBLDocument) -> Self {`
`529`	`529`	`unsafe {`
`530`	`530`	`Self {`
`531`	`531`	`cbl_ref: retain(cbl_ref),`
`532`	`532`	`}`
`533`	`533`	`}`
`534`	`534`	`}`
`535`	`535`
`536`		`- /// References the object without taking ownership and increasing it's reference counter`
`537`		`- pub(crate) const fn wrap(cbl_ref: *mut CBLDocument) -> Self {`
	`536`	`+ /// Takes ownership of the CBL ref, the reference counter is not increased so dropping the instance will free the ref.`
	`537`	`+ pub(crate) const fn take_ownership(cbl_ref: *mut CBLDocument) -> Self {`
`538`	`538`	`Self { cbl_ref }`
`539`	`539`	`}`
`540`	`540`
`@@ -607,6 +607,6 @@ impl Drop for Document {`
`607`	`607`
`608`	`608`	`impl Clone for Document {`
`609`	`609`	`fn clone(&self) -> Self {`
`610`		`- Self::retain(self.get_ref())`
	`610`	`+ Self::reference(self.get_ref())`
`611`	`611`	`}`
`612`	`612`	`}`
Original file line number	Diff line number	Diff line change
`@@ -66,15 +66,15 @@ impl CblRef for Encryptable {`
`66`	`66`
`67`	`67`	`impl From<*mut CBLEncryptable> for Encryptable {`
`68`	`68`	`fn from(cbl_ref: *mut CBLEncryptable) -> Self {`
`69`		`- Self::retain(cbl_ref)`
	`69`	`+ Self::reference(cbl_ref)`
`70`	`70`	`}`
`71`	`71`	`}`
`72`	`72`
`73`	`73`	`impl Encryptable {`
`74`	`74`	`//////// CONSTRUCTORS:`
`75`	`75`
`76`		`- /// Takes ownership of the object and increase it's reference counter.`
`77`		`- pub(crate) fn retain(cbl_ref: *mut CBLEncryptable) -> Self {`
	`76`	`+ /// Increase the reference counter of the CBL ref, so dropping the instance will NOT free the ref.`
	`77`	`+ pub(crate) fn reference(cbl_ref: *mut CBLEncryptable) -> Self {`
`78`	`78`	`Self {`
`79`	`79`	`cbl_ref: unsafe { retain(cbl_ref) },`
`80`	`80`	`}`
Original file line number	Diff line number	Diff line change
`@@ -323,7 +323,7 @@ impl Value {`
`323`	`323`	`pub fn get_encryptable_value(&self) -> Encryptable {`
`324`	`324`	`unsafe {`
`325`	`325`	`let encryptable = FLDict_GetEncryptableValue(FLValue_AsDict(self.get_ref()));`
`326`		`- Encryptable::retain(encryptable as *mut CBLEncryptable)`
	`326`	`+ Encryptable::reference(encryptable as *mut CBLEncryptable)`
`327`	`327`	`}`
`328`	`328`	`}`
`329`	`329`
`@@ -598,7 +598,7 @@ impl Dict {`
`598`	`598`	`pub fn get_encryptable_value(&self) -> Encryptable {`
`599`	`599`	`unsafe {`
`600`	`600`	`let encryptable = FLDict_GetEncryptableValue(self.get_ref());`
`601`		`- Encryptable::retain(encryptable as *mut CBLEncryptable)`
	`601`	`+ Encryptable::reference(encryptable as *mut CBLEncryptable)`
`602`	`602`	`}`
`603`	`603`	`}`
`604`	`604`
Original file line number	Diff line number	Diff line change
`@@ -148,16 +148,16 @@ impl CblRef for QueryIndex {`
`148`	`148`	`impl QueryIndex {`
`149`	`149`	`//////// CONSTRUCTORS:`
`150`	`150`
`151`		`- /// Takes ownership of the object and increase it's reference counter.`
	`151`	`+ /// Increase the reference counter of the CBL ref, so dropping the instance will NOT free the ref.`
`152`	`152`	`#[allow(dead_code)]`
`153`		`- pub(crate) fn retain(cbl_ref: *mut CBLQueryIndex) -> Self {`
	`153`	`+ pub(crate) fn reference(cbl_ref: *mut CBLQueryIndex) -> Self {`
`154`	`154`	`Self {`
`155`	`155`	`cbl_ref: unsafe { retain(cbl_ref) },`
`156`	`156`	`}`
`157`	`157`	`}`
`158`	`158`
`159`		`- /// References the object without taking ownership and increasing it's reference counter`
`160`		`- pub(crate) const fn wrap(cbl_ref: *mut CBLQueryIndex) -> Self {`
	`159`	`+ /// Takes ownership of the CBL ref, the reference counter is not increased so dropping the instance will free the ref.`
	`160`	`+ pub(crate) const fn take_ownership(cbl_ref: *mut CBLQueryIndex) -> Self {`
`161`	`161`	`Self { cbl_ref }`
`162`	`162`	`}`
`163`	`163`
`@@ -174,7 +174,7 @@ impl QueryIndex {`
`174`	`174`
`175`	`175`	`/// Returns the collection that the index belongs to.`
`176`	`176`	`pub fn collection(&self) -> Collection {`
`177`		`- unsafe { Collection::retain(CBLQueryIndex_Collection(self.get_ref())) }`
	`177`	`+ unsafe { Collection::reference(CBLQueryIndex_Collection(self.get_ref())) }`
`178`	`178`	`}`
`179`	`179`	`}`
`180`	`180`
`@@ -292,7 +292,7 @@ impl Collection {`
`292`	`292`	`let slice = from_str(name);`
`293`	`293`	`let index = unsafe { CBLCollection_GetIndex(self.get_ref(), slice.get_ref(), &mut err) };`
`294`	`294`	`if !err {`
`295`		`- return Ok(QueryIndex::wrap(index));`
	`295`	`+ return Ok(QueryIndex::take_ownership(index));`
`296`	`296`	`}`
`297`	`297`	`failure(err)`
`298`	`298`	`}`
Original file line number	Diff line number	Diff line change
`@@ -48,7 +48,7 @@ unsafe extern "C" fn c_query_change_listener(`
`48`	`48`	`token: *mut CBLListenerToken,`
`49`	`49`	`) {`
`50`	`50`	`let callback = context as *const ChangeListener;`
`51`		`- let query = Query::wrap(query.cast::<CBLQuery>());`
	`51`	`+ let query = Query::reference(query.cast::<CBLQuery>());`
`52`	`52`	`let token = ListenerToken::new(token);`
`53`	`53`
`54`	`54`	`(*callback)(&query, &token);`
`@@ -88,16 +88,22 @@ impl Query {`
`88`	`88`	`return failure(err);`
`89`	`89`	`}`
`90`	`90`
`91`		`- Ok(Self { cbl_ref: q })`
	`91`	`+ Ok(Self::take_ownership(q))`
`92`	`92`	`}`
`93`	`93`	`}`
`94`	`94`
`95`		`- pub(crate) fn wrap(cbl_ref: *mut CBLQuery) -> Self {`
	`95`	`+ /// Increase the reference counter of the CBL ref, so dropping the instance will NOT free the ref.`
	`96`	`+ pub(crate) fn reference(cbl_ref: *mut CBLQuery) -> Self {`
`96`	`97`	`Self {`
`97`	`98`	`cbl_ref: unsafe { retain(cbl_ref) },`
`98`	`99`	`}`
`99`	`100`	`}`
`100`	`101`
	`102`	`+ /// Takes ownership of the CBL ref, the reference counter is not increased so dropping the instance will free the ref.`
	`103`	`+ pub(crate) const fn take_ownership(cbl_ref: *mut CBLQuery) -> Self {`
	`104`	`+ Self { cbl_ref }`
	`105`	`+ }`
	`106`	`+`
`101`	`107`	`/** Assigns values to the query's parameters.`
`102`	`108`	`These values will be substited for those parameters whenever the query is executed,`
`103`	`109`	`until they are next assigned.`