(DOCSP-29739): C++: Add documentation for Set data type (#3065)

## Pull Request Info

### Jira

- https://jira.mongodb.org/browse/DOCSP-29739

### Staged Changes

- [Supported
Types](https://preview-mongodbdacharyc.gatsbyjs.io/realm/DOCSP-29739/sdk/cpp/model-data/supported-types/#set)
-
[CRUD/Create](https://preview-mongodbdacharyc.gatsbyjs.io/realm/DOCSP-29739/sdk/cpp/crud/create/#create-an-object-with-a-set-property)
-
[CRUD/Read](https://preview-mongodbdacharyc.gatsbyjs.io/realm/DOCSP-29739/sdk/cpp/crud/read/#read-a-set-property)
-
[CRUD/Update](https://preview-mongodbdacharyc.gatsbyjs.io/realm/DOCSP-29739/sdk/cpp/crud/update/#update-a-set-property)
-
[CRUD/Delete](https://preview-mongodbdacharyc.gatsbyjs.io/realm/DOCSP-29739/sdk/cpp/crud/delete/#delete-set-values)
- [React to
Changes](https://preview-mongodbdacharyc.gatsbyjs.io/realm/DOCSP-29739/sdk/cpp/react-to-changes/#register-a-collection-change-listener)

### Reminder Checklist

If your PR modifies the docs, you might need to also update some
corresponding
pages. Check if completed or N/A.

- [x] Create Jira ticket for corresponding docs-app-services update(s),
if any
- [x] Checked/updated Admin API
- [x] Checked/updated CLI reference

### Review Guidelines


[REVIEWING.md](https://github.com/mongodb/docs-realm/blob/master/REVIEWING.md)

examples/cpp/beta/local/CMakeLists.txt

@@ -14,7 +14,7 @@ FetchContent_Declare(
 FetchContent_Declare(
   cpprealm
   GIT_REPOSITORY https://github.com/realm/realm-cpp.git
-  GIT_TAG        v0.3.0-preview
+  GIT_TAG        v0.4.0-preview
 )
 
 FetchContent_MakeAvailable(Catch2 cpprealm)

examples/cpp/beta/local/crud.cpp

@@ -7,7 +7,8 @@
 // :replace-start: {
 //   "terms": {
 //     "Beta_": "",
-//     "Beta_Map_": ""
+//     "Beta_Map_": "",
+//     "Beta_Set_": ""
 //   }
 // }
 
@@ -82,6 +83,14 @@ struct Beta_Map_Employee {
 REALM_SCHEMA(Beta_Map_Employee, _id, firstName, lastName, locationByDay)
 // :snippet-end:
 
+// :snippet-start: beta-model-with-set-property
+struct Beta_Set_Repository {
+    std::string ownerAndName;
+    std::set<int64_t> openPullRequestNumbers;
+};
+REALM_SCHEMA(Beta_Set_Repository, ownerAndName, openPullRequestNumbers)
+// :snippet-end:
+
 TEST_CASE("Beta define model example", "[write]") {
     auto relative_realm_path_directory = "beta_dog/";
     std::filesystem::create_directories(relative_realm_path_directory);
@@ -486,4 +495,135 @@ TEST_CASE("test map object with percent-encoded map key", "[write]") {
         });
     }
 }
+
+TEST_CASE("Test Set Object", "[write]") {
+    auto relative_realm_path_directory = "beta_set_repository/";
+    std::filesystem::create_directories(relative_realm_path_directory);
+    std::filesystem::path path = std::filesystem::current_path().append(relative_realm_path_directory);
+    path = path.append("repository_objects");
+    path = path.replace_extension("realm");
+    auto config = realm::db_config();
+    config.set_path(path);
+
+    // :snippet-start: write-set-object
+    auto realm = db(std::move(config));
+
+    // Create an object that has a set property
+    auto docsRealmRepo = Beta_Set_Repository {
+        .ownerAndName = "mongodb/docs-realm"
+    };
+
+    // Add the object to the realm and get the managed object
+    auto managedDocsRealm = realm.write([&]() {
+        return realm.add(std::move(docsRealmRepo));
+    });
+
+    // Insert items into the set
+    auto openPullRequestNumbers = { 3059, 3062, 3064 };
+
+    realm.write([&] {
+        for (auto number: openPullRequestNumbers) {
+            // You can only mutate the set in a write transaction.
+            // This means you can't set values at initialization,
+            // but must do it during a write.
+            managedDocsRealm.openPullRequestNumbers.insert(number);
+        }
+    });
+    // :snippet-end:
+
+    auto it3059 = managedDocsRealm.openPullRequestNumbers.find(3059);
+    REQUIRE(*it3059 == static_cast<long long>(3059));
+
+//    auto it3062 = managedDocsRealm.openPullRequestNumbers.find(3062);
+//    REQUIRE(*it3062 == static_cast<long long>(3062));
+
+//    auto it3064 = managedDocsRealm.openPullRequestNumbers.find(3064);
+//    REQUIRE(it3064 != managedDocsRealm.openPullRequestNumbers.end());
+//    REQUIRE(*it3064 == static_cast<long long>(3064));
+
+    // :snippet-start: read-set
+    auto repositories = realm.objects<Beta_Set_Repository>();
+
+    auto repositoriesNamedDocsRealm = repositories.where([](auto &repository) {
+        return repository.ownerAndName == "mongodb/docs-realm";
+    });
+
+    auto docsRealm = repositoriesNamedDocsRealm[0];
+
+    // You can check the size of the set
+    auto numberOfPullRequests = docsRealm.openPullRequestNumbers.size();
+    CHECK(numberOfPullRequests == 3); // :remove:
+
+    // Find an element in the set whose value is 3064
+    auto it = managedDocsRealm.openPullRequestNumbers.find(3064);
+    // :remove-start:
+    CHECK(it != managedDocsRealm.openPullRequestNumbers.end());
+    CHECK(*it == static_cast<long long>(3064));
+    // :remove-end:
+
+    // Get a copy of the set that exists independent of the managed set
+    auto openRealmPullRequests = docsRealm.openPullRequestNumbers.detach();
+    // :snippet-end:
+
+    CHECK(openRealmPullRequests == std::set<int64_t>({ 3059, 3062, 3064 }));
+    CHECK(openRealmPullRequests.size() == 3);
+    CHECK(docsRealm.openPullRequestNumbers.size() == 3);
+
+    // After clearing the copy of the set, the managed set is unchanged
+    openRealmPullRequests.clear();
+    CHECK(openRealmPullRequests.size() == 0);
+    CHECK(docsRealm.openPullRequestNumbers.size() == 3);
+
+    // :snippet-start: update-set
+    // Add elements to the set in a write transaction
+    realm.write([&] {
+        managedDocsRealm.openPullRequestNumbers.insert(3066);
+    });
+    CHECK(managedDocsRealm.openPullRequestNumbers.size() == 4);
+
+    // Use std::set algorithms to update a set
+    // In this example, use std::set_union to add elements to the set
+    // 3064 already exists, so it won't be added, but 3065 and 3067 are unique
+    // values and will be added to the set.
+    auto newOpenPullRequests = std::set<int64_t>({ 3064, 3065, 3067 });
+    realm.write([&] {
+        std::set_union(
+                       docsRealm.openPullRequestNumbers.begin(),
+                       docsRealm.openPullRequestNumbers.end(),
+                       newOpenPullRequests.begin(),
+                       newOpenPullRequests.end(),
+                       std::inserter(
+                                     managedDocsRealm.openPullRequestNumbers,
+                                     managedDocsRealm.openPullRequestNumbers.end()));
+    });
+    CHECK(managedDocsRealm.openPullRequestNumbers.size() == 6);
+
+    // Erase elements from a set
+    auto it3065 = managedDocsRealm.openPullRequestNumbers.find(3065);
+    CHECK(it3065 != managedDocsRealm.openPullRequestNumbers.end());
+    realm.write([&] {
+        managedDocsRealm.openPullRequestNumbers.erase(it3065);
+    });
+    // :snippet-end:
+    CHECK(managedDocsRealm.openPullRequestNumbers.size() == 5);
+    // :snippet-start: delete-set
+    // Remove an element from the set with erase()
+    auto it3064 = managedDocsRealm.openPullRequestNumbers.find(3064);
+    CHECK(it3064 != managedDocsRealm.openPullRequestNumbers.end());
+    realm.write([&] {
+        managedDocsRealm.openPullRequestNumbers.erase(it3065);
+    });
+    CHECK(managedDocsRealm.openPullRequestNumbers.size() == 4);
+
+    // Clear the entire contents of the set
+    realm.write([&] {
+        managedDocsRealm.openPullRequestNumbers.clear();
+    });
+    CHECK(managedDocsRealm.openPullRequestNumbers.size() == 0);
+    // :snippet-end:
+
+    realm.write([&] {
+        realm.remove(docsRealm);
+    });
+}
 // :replace-end:

examples/cpp/beta/local/supported-types.cpp

@@ -90,12 +90,15 @@ struct Beta_AllTypesObject {
     // :snippet-start: beta-required-list
     std::vector<SomeType> listTypeName;
     // :snippet-end:
+    // :snippet-start: beta-required-set
+    std::set<std::string> setTypeName;
+    // :snippet-end:
 };
 REALM_SCHEMA(Beta_AllTypesObject, boolName, optBoolName, intName, optIntName,
     doubleName, optDoubleName, stringName, optStringName, enumName,
     optEnumName, binaryDataName, optBinaryDataName, dateName, optDateName,
     decimal128Name, optDecimal128Name, uuidName, optUuidName, objectIdName, 
-    optObjectIdName, mixedName, mapName, listTypeName
+    optObjectIdName, mixedName, mapName, listTypeName, setTypeName
 )
 
 // :snippet-start: beta-dog-map-model
@@ -135,7 +138,8 @@ TEST_CASE("Test supported types", "[model][write]") {
             .objectIdName = objectId,
             .mixedName = realm::mixed("mixed data"),
             .mapName = std::map<std::string, std::string>({{"foo", "bar"}}),
-            .listTypeName = std::vector<std::string>({"bar", "baz"})
+            .listTypeName = std::vector<std::string>({"bar", "baz"}),
+            .setTypeName = { "Lita", "Maui", "Ash" }
         };
 
         realm.write([&] {
@@ -159,6 +163,10 @@ TEST_CASE("Test supported types", "[model][write]") {
         REQUIRE(specificAllTypeObjects.mapName["foo"] == "bar");
         REQUIRE(specificAllTypeObjects.listTypeName[0] == "bar");
 
+        auto it = specificAllTypeObjects.setTypeName.find("Lita");
+        REQUIRE(it != specificAllTypeObjects.setTypeName.end());
+        REQUIRE(*it == "Lita");
+
         realm.write([&] {
             realm.remove(specificAllTypeObjects);
         });

source/examples/generated/cpp/crud.snippet.beta-model-with-set-property.cpp

@@ -0,0 +1,5 @@
+struct Repository {
+    std::string ownerAndName;
+    std::set<int64_t> openPullRequestNumbers;
+};
+REALM_SCHEMA(Repository, ownerAndName, openPullRequestNumbers)

source/examples/generated/cpp/crud.snippet.delete-set.cpp

@@ -0,0 +1,13 @@
+// Remove an element from the set with erase()
+auto it3064 = managedDocsRealm.openPullRequestNumbers.find(3064);
+CHECK(it3064 != managedDocsRealm.openPullRequestNumbers.end());
+realm.write([&] {
+    managedDocsRealm.openPullRequestNumbers.erase(it3065);
+});
+CHECK(managedDocsRealm.openPullRequestNumbers.size() == 4);
+
+// Clear the entire contents of the set
+realm.write([&] {
+    managedDocsRealm.openPullRequestNumbers.clear();
+});
+CHECK(managedDocsRealm.openPullRequestNumbers.size() == 0);

source/examples/generated/cpp/crud.snippet.read-set.cpp

@@ -0,0 +1,16 @@
+auto repositories = realm.objects<Repository>();
+
+auto repositoriesNamedDocsRealm = repositories.where([](auto &repository) {
+    return repository.ownerAndName == "mongodb/docs-realm";
+});
+
+auto docsRealm = repositoriesNamedDocsRealm[0];
+
+// You can check the size of the set
+auto numberOfPullRequests = docsRealm.openPullRequestNumbers.size();
+
+// Find an element in the set whose value is 3064
+auto it = managedDocsRealm.openPullRequestNumbers.find(3064);
+
+// Get a copy of the set that exists independent of the managed set
+auto openRealmPullRequests = docsRealm.openPullRequestNumbers.detach();

source/examples/generated/cpp/crud.snippet.update-set.cpp

@@ -0,0 +1,29 @@
+// Add elements to the set in a write transaction
+realm.write([&] {
+    managedDocsRealm.openPullRequestNumbers.insert(3066);
+});
+CHECK(managedDocsRealm.openPullRequestNumbers.size() == 4);
+
+// Use std::set algorithms to update a set
+// In this example, use std::set_union to add elements to the set
+// 3064 already exists, so it won't be added, but 3065 and 3067 are unique
+// values and will be added to the set.
+auto newOpenPullRequests = std::set<int64_t>({ 3064, 3065, 3067 });
+realm.write([&] {
+    std::set_union(
+                   docsRealm.openPullRequestNumbers.begin(),
+                   docsRealm.openPullRequestNumbers.end(),
+                   newOpenPullRequests.begin(),
+                   newOpenPullRequests.end(),
+                   std::inserter(
+                                 managedDocsRealm.openPullRequestNumbers,
+                                 managedDocsRealm.openPullRequestNumbers.end()));
+});
+CHECK(managedDocsRealm.openPullRequestNumbers.size() == 6);
+
+// Erase elements from a set
+auto it3065 = managedDocsRealm.openPullRequestNumbers.find(3065);
+CHECK(it3065 != managedDocsRealm.openPullRequestNumbers.end());
+realm.write([&] {
+    managedDocsRealm.openPullRequestNumbers.erase(it3065);
+});

source/examples/generated/cpp/crud.snippet.write-set-object.cpp

@@ -0,0 +1,23 @@
+auto realm = db(std::move(config));
+
+// Create an object that has a set property
+auto docsRealmRepo = Repository {
+    .ownerAndName = "mongodb/docs-realm"
+};
+
+// Add the object to the realm and get the managed object
+auto managedDocsRealm = realm.write([&]() {
+    return realm.add(std::move(docsRealmRepo));
+});
+
+// Insert items into the set
+auto openPullRequestNumbers = { 3059, 3062, 3064 };
+
+realm.write([&] {
+    for (auto number: openPullRequestNumbers) {
+        // You can only mutate the set in a write transaction.
+        // This means you can't set values at initialization,
+        // but must do it during a write.
+        managedDocsRealm.openPullRequestNumbers.insert(number);
+    }
+});

source/examples/generated/cpp/supported-types.snippet.beta-required-set.cpp

@@ -0,0 +1 @@
+std::set<std::string> setTypeName;

source/sdk/cpp/crud/create.txt

@@ -436,6 +436,35 @@ For more information about supported map data types, refer to:
       .. literalinclude:: /examples/generated/cpp/define-object-model.snippet.model-with-map-property.cpp
          :language: cpp
 
+.. _cpp-create-object-set-property:
+
+Create an Object with a Set Property
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. versionadded:: v0.4.0-preview
+
+You can create objects that contain :cpp-sdk:`set 
+<structrealm_1_1experimental_1_1managed_3_01std_1_1set_3_01T_01_5_01_4_01_4.html>` 
+properties as you would any Realm object, but you can only mutate a set 
+property within a write transaction. This means you can only set the value(s) 
+of a set property within a write transaction.
+
+.. literalinclude:: /examples/generated/cpp/crud.snippet.write-set-object.cpp
+   :language: cpp
+
+.. include:: /includes/tip-cpp-beta-experimental-features.rst
+
+Model
+`````
+
+For more information about supported set data types, refer to: 
+:ref:`cpp-set-collections`.
+
+.. literalinclude:: /examples/generated/cpp/crud.snippet.beta-model-with-set-property.cpp
+   :language: cpp
+
+.. include:: /includes/tip-cpp-beta-experimental-features.rst
+
 .. _cpp-create-asymmetric-object:
 
 Create an Asymmetric Object

source/sdk/cpp/crud/delete.txt

@@ -100,3 +100,19 @@ pass the key name to ``erase()``:
 
       .. literalinclude:: /examples/generated/cpp/define-object-model.snippet.delete-map-value.cpp
          :language: cpp
+
+.. _cpp-delete-set-values:
+
+Delete Set Values
+~~~~~~~~~~~~~~~~~
+
+.. versionadded:: v0.4.0-preview
+
+You can delete a :cpp-sdk:`set element 
+<structrealm_1_1experimental_1_1managed_3_01std_1_1set_3_01T_01_5_01_4_01_4.html>` 
+with ``erase()``, or remove all elements from a set with ``clear()``.
+
+.. literalinclude:: /examples/generated/cpp/crud.snippet.delete-set.cpp
+   :language: cpp
+
+.. include:: /includes/tip-cpp-beta-experimental-features.rst

source/sdk/cpp/crud/read.txt

@@ -178,3 +178,16 @@ as you would a standard C++ `map <https://en.cppreference.com/w/cpp/container/ma
 
 .. literalinclude:: /examples/generated/cpp/define-object-model.snippet.read-map-value.cpp
     :language: cpp
+
+.. _cpp-read-and-iterate-set:
+
+Read a Set Property
+~~~~~~~~~~~~~~~~~~~
+
+.. versionadded:: v0.4.0-preview
+
+You can iterate, check the size of a set, and find values in a :cpp-sdk:`set property
+<structrealm_1_1experimental_1_1managed_3_01std_1_1set_3_01T_01_5_01_4_01_4.html>`:
+
+.. literalinclude:: /examples/generated/cpp/crud.snippet.read-set.cpp
+    :language: cpp