CollectionDocument::modify allows returning values

Closes #312

CHANGELOG.md

@@ -8,6 +8,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## Unreleased
 
+### Breaking Changes
+
+- `CollectionDocument::modify`/`CollectionDocument::modify_async` now take an
+  additional parameter: the return type of the callback function. This result
+  from the call that succeeds in updating will be returned in `Ok`.
+
 ### Added
 
 - `bonsaidb::client::Error` now implements

crates/bonsaidb-core/src/document/collection.rs

@@ -144,18 +144,20 @@ where
     /// Modifies `self`, automatically retrying the modification if the document
     /// has been updated on the server.
     ///
+    /// The contents of `Ok` will be the last value returned from `modifier`.
+    ///
     /// ## Data loss warning
     ///
     /// If you've modified `self` before calling this function and a conflict
     /// occurs, all changes to self will be lost when the current document is
     /// fetched before retrying the process again. When you use this function,
     /// you should limit the edits to the value to within the `modifier`
     /// callback.
-    pub fn modify<Cn: Connection, Modifier: FnMut(&mut Self) + Send + Sync>(
+    pub fn modify<R, Cn: Connection, Modifier: FnMut(&mut Self) -> R + Send + Sync>(
         &mut self,
         connection: &Cn,
         mut modifier: Modifier,
-    ) -> Result<(), Error>
+    ) -> Result<R, Error>
     where
         C::Contents: Clone,
     {
@@ -176,29 +178,35 @@ where
                         }
                     })?;
             }
-            modifier(&mut *self);
+            let result = modifier(&mut *self);
             match self.update(connection) {
                 Err(Error::DocumentConflict(..)) => {}
-                other => return other,
+                other => return other.map(|()| result),
             }
         }
     }
 
     /// Modifies `self`, automatically retrying the modification if the document
     /// has been updated on the server.
     ///
+    /// The contents of `Ok` will be the last value returned from `modifier`.
+    ///
     /// ## Data loss warning
     ///
     /// If you've modified `self` before calling this function and a conflict
     /// occurs, all changes to self will be lost when the current document is
     /// fetched before retrying the process again. When you use this function,
     /// you should limit the edits to the value to within the `modifier`
     /// callback.
-    pub async fn modify_async<Cn: AsyncConnection, Modifier: FnMut(&mut Self) + Send + Sync>(
+    pub async fn modify_async<
+        R,
+        Cn: AsyncConnection,
+        Modifier: FnMut(&mut Self) -> R + Send + Sync,
+    >(
         &mut self,
         connection: &Cn,
         mut modifier: Modifier,
-    ) -> Result<(), Error>
+    ) -> Result<R, Error>
     where
         C::Contents: Clone,
     {
@@ -218,10 +226,10 @@ where
                         Err(err) => err,
                     })?;
             }
-            modifier(&mut *self);
+            let result = modifier(&mut *self);
             match self.update_async(connection).await {
                 Err(Error::DocumentConflict(..)) => {}
-                other => return other,
+                other => return other.map(|()| result),
             }
         }
     }