change/add copy api and simple test

Objective-C/CBLMutableDocument.h

@@ -110,6 +110,12 @@ NS_ASSUME_NONNULL_BEGIN
                                 json: (NSString*)json
                                error: (NSError**)error;
 
+/**
+ Returns a mutable copy of the document.
+ 
+ @return The CBLMutableDocument object.
+ */
+- (CBLMutableDocument*) copy;
 @end
 
 NS_ASSUME_NONNULL_END

Objective-C/CBLMutableDocument.mm

@@ -120,6 +120,10 @@ - (CBLMutableDocument*) mutableCopyWithZone: (NSZone *)zone {
     return [[CBLMutableDocument alloc] initAsCopyWithDocument: self dict: _dict];
 }
 
+- (CBLMutableDocument*) copy {
+    return [self mutableCopyWithZone: nil];
+}
+
 #pragma mark - CBLMutableDictionary
 
 - (void) setValue: (nullable id)value forKey: (NSString*)key {

Objective-C/Tests/DocumentTest.m

@@ -2262,6 +2262,22 @@ - (void) testDocumentResaveInAnotherCollection {
     }];
 }
 
+- (void) testMutableDocumentCopy {
+    NSError* err;
+    CBLCollection* defaultCollection = [self.db defaultCollection: &err];
+
+    CBLMutableDocument* doc = [[CBLMutableDocument alloc] initWithID: @"doc1"];
+    [doc setString: @"first" forKey: @"one"];
+    CBLMutableDocument* docCopy = [doc copy];
+    AssertEqual([docCopy stringForKey:@"one"], @"first");
+
+    [doc setString: @"second" forKey: @"two"];
+    Assert([defaultCollection saveDocument:doc error: &err]);
+    docCopy = [[[defaultCollection documentWithID: @"doc1" error: &err] toMutable] copy];
+    AssertEqual([docCopy stringForKey:@"one"], @"first");
+    AssertEqual([docCopy stringForKey:@"two"], @"second");
+}
+
 #pragma clang diagnostic pop
 
 @end

Swift/MutableDocument.swift

@@ -97,10 +97,18 @@ public final class MutableDocument : Document, MutableDictionaryProtocol {
     /// Returns the same MutableDocument object.
     ///
     /// - Returns: The MutableDocument object.
+    @available(*, deprecated, message: "Use mutableDocument.copy() instead.")
     public override func toMutable() -> MutableDocument {
         return self;
     }
 
+    /// Returns the same MutableDocument object.
+    ///
+    /// - Returns: The MutableDocument object.
+    public func copy() -> MutableDocument {
+        return self;
+    }
+
     // MARK: Type Setters
 
     /// Set a value for the given key. Allowed value types are Array, Date, Dictionary,

Swift/Tests/DocumentTest.swift

@@ -1855,4 +1855,17 @@ class DocumentTest: CBLTestCase {
             }
         }
     }
+
+    func testCopy() throws {
+        let doc = MutableDocument(id: "doc1")
+        doc.setValue("first", forKey: "one")
+        var docCopy = doc.copy()
+        assert(docCopy.value(forKey: "one") as! String == "first")
+
+        doc.setValue("second", forKey: "two")
+        try defaultCollection!.save(document: doc)
+        docCopy = try defaultCollection!.document(id: "doc1")!.toMutable().copy()
+        assert(docCopy.value(forKey: "one") as! String == "first")
+        assert(docCopy.value(forKey: "two") as! String == "second")
+    }
 }