diff --git a/examples/kotlin/shared/src/commonTest/kotlin/com/mongodb/realm/realmkmmapp/CreateTest.kt b/examples/kotlin/shared/src/commonTest/kotlin/com/mongodb/realm/realmkmmapp/CreateTest.kt index 2effcc15c2..2e20ce56c7 100644 --- a/examples/kotlin/shared/src/commonTest/kotlin/com/mongodb/realm/realmkmmapp/CreateTest.kt +++ b/examples/kotlin/shared/src/commonTest/kotlin/com/mongodb/realm/realmkmmapp/CreateTest.kt @@ -4,17 +4,20 @@ import io.realm.kotlin.Realm import io.realm.kotlin.RealmConfiguration import io.realm.kotlin.ext.query import io.realm.kotlin.ext.realmDictionaryOf +import io.realm.kotlin.ext.realmSetOf import io.realm.kotlin.internal.platform.runBlocking import io.realm.kotlin.query.RealmResults import io.realm.kotlin.types.RealmDictionary import io.realm.kotlin.types.RealmObject +import io.realm.kotlin.types.RealmSet import org.mongodb.kbson.ObjectId import kotlin.test.Test import kotlin.test.assertEquals // :replace-start: { // "terms": { -// "CreateTest_": "" +// "CreateTest_": "", +// "RealmSet_": "" // } // } @@ -26,7 +29,75 @@ class CreateTest_Frog : RealmObject { } // :snippet-end: +// :snippet-start: define-a-realm-set +class RealmSet_Frog : RealmObject { + var _id: ObjectId = ObjectId() + var name: String = "" + var favoriteSnacks: RealmSet = realmSetOf() +} + +class Snack : RealmObject { + var _id: ObjectId = ObjectId() + var name: String = "" +} +// :snippet-end: + class CreateTest: RealmTest() { + + @Test + fun createRealmSetType() { + runBlocking { + val config = RealmConfiguration.Builder(setOf(RealmSet_Frog::class, Snack::class)) + .inMemory() + .build() + val realm = Realm.open(config) + Log.v("Successfully opened realm: ${realm.configuration.path}") + + // :snippet-start: create-realm-set + realm.write { + // Create a Frog object named 'Kermit' + // Add item to the RealmSet using the add() method + val frog = copyToRealm( + RealmSet_Frog().apply { + name = "Kermit" + favoriteSnacks.add(Snack().apply { name = "flies" }) + } + ) + assertEquals(1, frog.favoriteSnacks.size) // :remove: + assertEquals("flies", frog.favoriteSnacks.first().name) // :remove: + println(frog.favoriteSnacks.first().name) // prints "flies" + } + // :snippet-end: + // :snippet-start: add-all-to-realm-set + realm.write { + val frog = query().find().first() + val snackSet = frog.favoriteSnacks + + // Create two more Snack objects + val cricketsSnack = copyToRealm( + Snack().apply { + name = "crickets" + } + ) + val wormsSnack = copyToRealm( + Snack().apply { + name = "worms" + } + ) + + // Add multiple items to the RealmSet using the addAll() method + snackSet.addAll(setOf(cricketsSnack, wormsSnack)) + assertEquals(3, snackSet.size) // :remove: + } + // :snippet-end: + realm.writeBlocking { + val frogs = query().find().first() + delete(frogs) + } + realm.close() + } + } + @Test fun createRealmDictionaryType() { runBlocking { diff --git a/examples/kotlin/shared/src/commonTest/kotlin/com/mongodb/realm/realmkmmapp/DeleteTest.kt b/examples/kotlin/shared/src/commonTest/kotlin/com/mongodb/realm/realmkmmapp/DeleteTest.kt index ef39c29a53..1037f84a1c 100644 --- a/examples/kotlin/shared/src/commonTest/kotlin/com/mongodb/realm/realmkmmapp/DeleteTest.kt +++ b/examples/kotlin/shared/src/commonTest/kotlin/com/mongodb/realm/realmkmmapp/DeleteTest.kt @@ -11,12 +11,13 @@ import io.realm.kotlin.types.RealmObject import org.mongodb.kbson.ObjectId import kotlin.test.Test import kotlin.test.assertEquals -import kotlin.test.assertTrue import kotlin.test.assertFalse +import kotlin.test.assertTrue // :replace-start: { // "terms": { -// "UpdateTest_": "" +// "UpdateTest_": "", +// "RealmSet_": "" // } // } @@ -27,7 +28,71 @@ class DeleteTest_Frog : RealmObject { } class DeleteTest: RealmTest() { + @Test + fun deleteRealmSetType() { + runBlocking { + val config = RealmConfiguration.Builder(setOf(RealmSet_Frog::class, Snack::class)) + .inMemory() + .build() + val realm = Realm.open(config) + Log.v("Successfully opened realm: ${realm.configuration.path}") + + realm.write { copyToRealm( + RealmSet_Frog().apply { + name = "Kermit" + favoriteSnacks.add(Snack().apply { name = "Flies" }) + favoriteSnacks.add(Snack().apply { name = "Crickets" }) + favoriteSnacks.add(Snack().apply { name = "Worms" }) + }) + } + // :snippet-start: remove-item-from-set + realm.write { + val myFrog = realm.query("name == $0", "Kermit").find().first() + val snackSet = findLatest(myFrog)!!.favoriteSnacks + + // Remove the Flies snack from the set + val fliesSnack = snackSet.first { it.name == "Flies" } + snackSet.remove(fliesSnack) + assertFalse(snackSet.contains(fliesSnack)) // :remove: + + // Remove all snacks from the set + val allSnacks = findLatest(myFrog)!!.favoriteSnacks + snackSet.removeAll(allSnacks) + // :remove-start: + // TODO update test once https://github.com/realm/realm-kotlin/issues/1097 is fixed in v1.11.0 + // assertTrue(set.isEmpty()) + snackSet.removeAll(allSnacks) // have to call twice to actually remove all items until bug is fixed + // :remove-end: + } + // :snippet-end: + realm.write { + val myFrog = realm.query("name == $0", "Kermit").find().first() + val snackSet = findLatest(myFrog)!!.favoriteSnacks + val snack1 = this.copyToRealm(Snack().apply { + name = "snack1" + }) + val snack2 = this.copyToRealm(Snack().apply { + name = "snack2" + }) + val snack3 = this.copyToRealm(Snack().apply { + name = "snack3" + }) + + snackSet.addAll(setOf(snack1, snack2, snack3)) + assertEquals(3, snackSet.size) + + // :snippet-start: clear-set + // Clear all snacks from the set + snackSet.clear() + // :snippet-end: + assertTrue(snackSet.isEmpty()) + } + realm.close() + } + } + + @Test fun deleteRealmDictionaryType() { runBlocking { val config = RealmConfiguration.Builder( diff --git a/examples/kotlin/shared/src/commonTest/kotlin/com/mongodb/realm/realmkmmapp/ReadTest.kt b/examples/kotlin/shared/src/commonTest/kotlin/com/mongodb/realm/realmkmmapp/ReadTest.kt index 1238fc7b55..c3feb43486 100644 --- a/examples/kotlin/shared/src/commonTest/kotlin/com/mongodb/realm/realmkmmapp/ReadTest.kt +++ b/examples/kotlin/shared/src/commonTest/kotlin/com/mongodb/realm/realmkmmapp/ReadTest.kt @@ -13,11 +13,13 @@ import io.realm.kotlin.types.annotations.PrimaryKey import org.mongodb.kbson.ObjectId import kotlin.test.Test import kotlin.test.assertEquals +import kotlin.test.assertNotNull import kotlin.test.assertTrue // :replace-start: { // "terms": { -// "ReadTest_": "" +// "ReadTest_": "", +// "RealmSet_": "" // } // } @@ -28,6 +30,61 @@ class ReadTest_Frog : RealmObject { } class ReadTest: RealmTest() { + + @Test + fun readRealmSetType() { + runBlocking { + val config = RealmConfiguration.Builder(setOf(RealmSet_Frog::class, Snack::class)) + .inMemory() + .build() + val realm = Realm.open(config) + Log.v("Successfully opened realm: ${realm.configuration.path}") + + // :snippet-start: read-realm-set + realm.write { + // Create a Frog object named 'Kermit' + // with a RealmSet of favorite snacks + val frog = copyToRealm( + RealmSet_Frog().apply { + name = "Kermit" + favoriteSnacks.add(Snack().apply { name = "Flies" }) + favoriteSnacks.add(Snack().apply { name = "Crickets" }) + favoriteSnacks.add(Snack().apply { name = "Worms" }) + } + ) + // Query for frogs that have worms as a favorite snack + val frogs = query("favoriteSnacks.name == $0", "Worms").find().first() + assertEquals("Kermit", frogs.name) // :remove: + + // Query for specific snacks + val wormsSnack = frog.favoriteSnacks.first { it.name == "Worms" } + assertNotNull(wormsSnack) // :remove: + } + // :snippet-end: + realm.write { + // :snippet-start: realm-set-contains + val frog = query("name == $0", "Kermit").find().first() + val snackSet = findLatest(frog)?.favoriteSnacks + + // Check if the set contains a particular value + val wormSnack = snackSet?.first { it.name == "Worms" } + Log.v("Does Kermit eat worms?: ${snackSet?.contains(wormSnack)}") // true + + // Check if the set contains multiple values + val containsAllSnacks = snackSet?.containsAll(snackSet) + Log.v("Does Kermit eat flies, crickets, and worms?: $containsAllSnacks") // true + // :snippet-end: + assertTrue(snackSet?.contains(wormSnack)?: false) + assertTrue(containsAllSnacks?: false) + } + realm.writeBlocking { + val frogs = query().find().first() + delete(frogs) + } + realm.close() + } + } + @Test fun readRealmDictionaryType() { runBlocking { diff --git a/examples/kotlin/shared/src/commonTest/kotlin/com/mongodb/realm/realmkmmapp/SchemaTest.kt b/examples/kotlin/shared/src/commonTest/kotlin/com/mongodb/realm/realmkmmapp/SchemaTest.kt index 26fd176fc9..de58c0cb45 100644 --- a/examples/kotlin/shared/src/commonTest/kotlin/com/mongodb/realm/realmkmmapp/SchemaTest.kt +++ b/examples/kotlin/shared/src/commonTest/kotlin/com/mongodb/realm/realmkmmapp/SchemaTest.kt @@ -14,13 +14,9 @@ import io.realm.kotlin.types.annotations.Ignore import io.realm.kotlin.types.annotations.Index import io.realm.kotlin.types.annotations.PersistedName import io.realm.kotlin.types.annotations.PrimaryKey -import kotlinx.coroutines.CoroutineScope -import kotlinx.coroutines.Dispatchers -import kotlinx.coroutines.launch import kotlinx.datetime.Instant import org.mongodb.kbson.ObjectId import kotlin.test.Test -import kotlin.test.assertEquals // :replace-start: { // "terms": { @@ -69,16 +65,14 @@ class Post: RealmObject { } // :snippet-end: -// :snippet-start: define-a-realm-set class Frog2 : RealmObject { var name: String = "" - var favoriteSnacks: RealmSet = realmSetOf() + var favoriteSnacks: RealmSet = realmSetOf() } -class Snack : RealmObject { +class Snack2 : RealmObject { var name: String? = null } -// :snippet-end: // :snippet-start: uuid class Cat: RealmObject { @@ -221,93 +215,6 @@ class SchemaTest: RealmTest() { realm.close() } } - @Test - @kotlin.test.Ignore // ignored until bugfix in 1.7.1 release - fun createRealmSetTypes() { - runBlocking { - val config = RealmConfiguration.Builder(setOf(Frog2::class, Snack::class)) - .build() - val realm = Realm.open(config) - Log.v("Successfully opened realm: ${realm.configuration.path}") - - // :snippet-start: add-item-to-realm-set - realm.write { - // Create a Frog object named 'Kermit' that will have a RealmSet of favorite snacks - val frog = this.copyToRealm(Frog2().apply { - name = "Kermit" - }) - // Get the RealmSet of favorite snacks from the Frog object we just created - val set = frog.favoriteSnacks - - // Create a Snack object for the Frog to add to Kermit's favorite snacks - val fliesSnack = this.copyToRealm(Snack().apply { - name = "flies" - }) - - // Add the flies to the RealmSet of Kermit's favorite snacks - set.add(fliesSnack) - assertEquals(1, set.size) // :remove: - } - // :snippet-end: - - // :snippet-start: add-all-to-realm-set - realm.write { - val myFrog: Frog2 = realm.query("name = 'Kermit'").first().find()!! - val set = findLatest(myFrog)!!.favoriteSnacks - - val cricketsSnack = this.copyToRealm(Snack().apply { - name = "crickets" - }) - val earthWormsSnack = this.copyToRealm(Snack().apply { - name = "earthworms" - }) - val waxWormsSnack = this.copyToRealm(Snack().apply { - name = "waxworms" - }) - - set.addAll(setOf(cricketsSnack, earthWormsSnack, waxWormsSnack)) - println("$set") // :remove: - assertEquals(4, set.size) // :remove: - // :uncomment-start: - //} - // :uncomment-end: - // :snippet-end: - - // :snippet-start: set-contains - Log.v("Does Kermit eat earthworms?: ${set.contains(earthWormsSnack)}") // true - // :snippet-end: - - // :snippet-start: set-contains-multiple-items - val containsAllSnacks = set.containsAll(set) - Log.v("Does Kermit eat crickets, earthworms, and wax worms?: $containsAllSnacks") // true - // :snippet-end: - - // :snippet-start: remove-item-from-set - val fliesSnack = realm.query("name = 'flies'").first().find() - - set.remove(fliesSnack) - // :snippet-end: - - // :snippet-start: remove-multiple-items-from-set - set.removeAll(set) - // :snippet-end: - } - - - // :snippet-start: react-to-changes-from-the-set - val kermitFrog = realm.query("name = 'Kermit'").first().find() - val job = CoroutineScope(Dispatchers.Default).launch { - kermitFrog?.favoriteSnacks - ?.asFlow() - ?.collect() { - // Listen for changes to the RealmSet - } - } - // :snippet-end: - job.cancel() - realm.close() - Realm.deleteRealm(config) - } - } } + // :replace-end: \ No newline at end of file diff --git a/source/examples/generated/kotlin/CreateTest.snippet.add-all-to-realm-set.kt b/source/examples/generated/kotlin/CreateTest.snippet.add-all-to-realm-set.kt new file mode 100644 index 0000000000..b4856e5706 --- /dev/null +++ b/source/examples/generated/kotlin/CreateTest.snippet.add-all-to-realm-set.kt @@ -0,0 +1,19 @@ +realm.write { + val frog = query().find().first() + val snackSet = frog.favoriteSnacks + + // Create two more Snack objects + val cricketsSnack = copyToRealm( + Snack().apply { + name = "crickets" + } + ) + val wormsSnack = copyToRealm( + Snack().apply { + name = "worms" + } + ) + + // Add multiple items to the RealmSet using the addAll() method + snackSet.addAll(setOf(cricketsSnack, wormsSnack)) +} diff --git a/source/examples/generated/kotlin/CreateTest.snippet.create-realm-set.kt b/source/examples/generated/kotlin/CreateTest.snippet.create-realm-set.kt new file mode 100644 index 0000000000..b40e5ad104 --- /dev/null +++ b/source/examples/generated/kotlin/CreateTest.snippet.create-realm-set.kt @@ -0,0 +1,11 @@ +realm.write { + // Create a Frog object named 'Kermit' + // Add item to the RealmSet using the add() method + val frog = copyToRealm( + Frog().apply { + name = "Kermit" + favoriteSnacks.add(Snack().apply { name = "flies" }) + } + ) + println(frog.favoriteSnacks.first().name) // prints "flies" +} diff --git a/source/examples/generated/kotlin/CreateTest.snippet.define-a-realm-set.kt b/source/examples/generated/kotlin/CreateTest.snippet.define-a-realm-set.kt new file mode 100644 index 0000000000..22caf42ba0 --- /dev/null +++ b/source/examples/generated/kotlin/CreateTest.snippet.define-a-realm-set.kt @@ -0,0 +1,10 @@ +class Frog : RealmObject { + var _id: ObjectId = ObjectId() + var name: String = "" + var favoriteSnacks: RealmSet = realmSetOf() +} + +class Snack : RealmObject { + var _id: ObjectId = ObjectId() + var name: String = "" +} diff --git a/source/examples/generated/kotlin/DeleteTest.snippet.clear-set.kt b/source/examples/generated/kotlin/DeleteTest.snippet.clear-set.kt new file mode 100644 index 0000000000..c6c5f7eb73 --- /dev/null +++ b/source/examples/generated/kotlin/DeleteTest.snippet.clear-set.kt @@ -0,0 +1,2 @@ +// Clear all snacks from the set +snackSet.clear() diff --git a/source/examples/generated/kotlin/DeleteTest.snippet.remove-item-from-set.kt b/source/examples/generated/kotlin/DeleteTest.snippet.remove-item-from-set.kt new file mode 100644 index 0000000000..a3689fcfa3 --- /dev/null +++ b/source/examples/generated/kotlin/DeleteTest.snippet.remove-item-from-set.kt @@ -0,0 +1,12 @@ +realm.write { + val myFrog = realm.query("name == $0", "Kermit").find().first() + val snackSet = findLatest(myFrog)!!.favoriteSnacks + + // Remove the Flies snack from the set + val fliesSnack = snackSet.first { it.name == "Flies" } + snackSet.remove(fliesSnack) + + // Remove all snacks from the set + val allSnacks = findLatest(myFrog)!!.favoriteSnacks + snackSet.removeAll(allSnacks) +} diff --git a/source/examples/generated/kotlin/ReadTest.snippet.read-realm-set.kt b/source/examples/generated/kotlin/ReadTest.snippet.read-realm-set.kt new file mode 100644 index 0000000000..7a790a19b5 --- /dev/null +++ b/source/examples/generated/kotlin/ReadTest.snippet.read-realm-set.kt @@ -0,0 +1,17 @@ +realm.write { + // Create a Frog object named 'Kermit' + // with a RealmSet of favorite snacks + val frog = copyToRealm( + Frog().apply { + name = "Kermit" + favoriteSnacks.add(Snack().apply { name = "Flies" }) + favoriteSnacks.add(Snack().apply { name = "Crickets" }) + favoriteSnacks.add(Snack().apply { name = "Worms" }) + } + ) + // Query for frogs that have worms as a favorite snack + val frogs = query("favoriteSnacks.name == $0", "Worms").find().first() + + // Query for specific snacks + val wormsSnack = frog.favoriteSnacks.first { it.name == "Worms" } +} diff --git a/source/examples/generated/kotlin/ReadTest.snippet.realm-set-contains.kt b/source/examples/generated/kotlin/ReadTest.snippet.realm-set-contains.kt new file mode 100644 index 0000000000..86ecbb0034 --- /dev/null +++ b/source/examples/generated/kotlin/ReadTest.snippet.realm-set-contains.kt @@ -0,0 +1,10 @@ +val frog = query("name == $0", "Kermit").find().first() +val snackSet = findLatest(frog)?.favoriteSnacks + +// Check if the set contains a particular value +val wormSnack = snackSet?.first { it.name == "Worms" } +Log.v("Does Kermit eat worms?: ${snackSet?.contains(wormSnack)}") // true + +// Check if the set contains multiple values +val containsAllSnacks = snackSet?.containsAll(snackSet) +Log.v("Does Kermit eat flies, crickets, and worms?: $containsAllSnacks") // true diff --git a/source/examples/generated/kotlin/SchemaTest.snippet.add-all-to-realm-set.kt b/source/examples/generated/kotlin/SchemaTest.snippet.add-all-to-realm-set.kt deleted file mode 100644 index e14e1dec56..0000000000 --- a/source/examples/generated/kotlin/SchemaTest.snippet.add-all-to-realm-set.kt +++ /dev/null @@ -1,16 +0,0 @@ -realm.write { - val myFrog: Frog = realm.query("name = 'Kermit'").first().find()!! - val set = findLatest(myFrog)!!.favoriteSnacks - - val cricketsSnack = this.copyToRealm(Snack().apply { - name = "crickets" - }) - val earthWormsSnack = this.copyToRealm(Snack().apply { - name = "earthworms" - }) - val waxWormsSnack = this.copyToRealm(Snack().apply { - name = "waxworms" - }) - - set.addAll(setOf(cricketsSnack, earthWormsSnack, waxWormsSnack)) - } diff --git a/source/examples/generated/kotlin/SchemaTest.snippet.add-item-to-realm-set.kt b/source/examples/generated/kotlin/SchemaTest.snippet.add-item-to-realm-set.kt deleted file mode 100644 index 9e326726f5..0000000000 --- a/source/examples/generated/kotlin/SchemaTest.snippet.add-item-to-realm-set.kt +++ /dev/null @@ -1,16 +0,0 @@ -realm.write { - // Create a Frog object named 'Kermit' that will have a RealmSet of favorite snacks - val frog = this.copyToRealm(Frog().apply { - name = "Kermit" - }) - // Get the RealmSet of favorite snacks from the Frog object we just created - val set = frog.favoriteSnacks - - // Create a Snack object for the Frog to add to Kermit's favorite snacks - val fliesSnack = this.copyToRealm(Snack().apply { - name = "flies" - }) - - // Add the flies to the RealmSet of Kermit's favorite snacks - set.add(fliesSnack) -} diff --git a/source/examples/generated/kotlin/SchemaTest.snippet.define-a-realm-set.kt b/source/examples/generated/kotlin/SchemaTest.snippet.define-a-realm-set.kt deleted file mode 100644 index 6a6cb1948d..0000000000 --- a/source/examples/generated/kotlin/SchemaTest.snippet.define-a-realm-set.kt +++ /dev/null @@ -1,8 +0,0 @@ -class Frog : RealmObject { - var name: String = "" - var favoriteSnacks: RealmSet = realmSetOf() -} - -class Snack : RealmObject { - var name: String? = null -} diff --git a/source/examples/generated/kotlin/SchemaTest.snippet.react-to-changes-from-the-set.kt b/source/examples/generated/kotlin/SchemaTest.snippet.react-to-changes-from-the-set.kt deleted file mode 100644 index 627a26b228..0000000000 --- a/source/examples/generated/kotlin/SchemaTest.snippet.react-to-changes-from-the-set.kt +++ /dev/null @@ -1,8 +0,0 @@ -val kermitFrog = realm.query("name = 'Kermit'").first().find() -val job = CoroutineScope(Dispatchers.Default).launch { - kermitFrog?.favoriteSnacks - ?.asFlow() - ?.collect() { - // Listen for changes to the RealmSet - } -} diff --git a/source/examples/generated/kotlin/SchemaTest.snippet.remove-item-from-set.kt b/source/examples/generated/kotlin/SchemaTest.snippet.remove-item-from-set.kt deleted file mode 100644 index e17fefbc80..0000000000 --- a/source/examples/generated/kotlin/SchemaTest.snippet.remove-item-from-set.kt +++ /dev/null @@ -1,3 +0,0 @@ -val fliesSnack = realm.query("name = 'flies'").first().find() - -set.remove(fliesSnack) diff --git a/source/examples/generated/kotlin/SchemaTest.snippet.remove-multiple-items-from-set.kt b/source/examples/generated/kotlin/SchemaTest.snippet.remove-multiple-items-from-set.kt deleted file mode 100644 index 0a58f9c2fc..0000000000 --- a/source/examples/generated/kotlin/SchemaTest.snippet.remove-multiple-items-from-set.kt +++ /dev/null @@ -1 +0,0 @@ -set.removeAll(set) diff --git a/source/examples/generated/kotlin/SchemaTest.snippet.set-contains-multiple-items.kt b/source/examples/generated/kotlin/SchemaTest.snippet.set-contains-multiple-items.kt deleted file mode 100644 index 6a1144a0ff..0000000000 --- a/source/examples/generated/kotlin/SchemaTest.snippet.set-contains-multiple-items.kt +++ /dev/null @@ -1,2 +0,0 @@ -val containsAllSnacks = set.containsAll(set) -Log.v("Does Kermit eat crickets, earthworms, and wax worms?: $containsAllSnacks") // true diff --git a/source/examples/generated/kotlin/SchemaTest.snippet.set-contains.kt b/source/examples/generated/kotlin/SchemaTest.snippet.set-contains.kt deleted file mode 100644 index 43c759da4e..0000000000 --- a/source/examples/generated/kotlin/SchemaTest.snippet.set-contains.kt +++ /dev/null @@ -1 +0,0 @@ -Log.v("Does Kermit eat earthworms?: ${set.contains(earthWormsSnack)}") // true diff --git a/source/sdk/kotlin/realm-database/crud/create.txt b/source/sdk/kotlin/realm-database/crud/create.txt index bd603154c4..cafe153799 100644 --- a/source/sdk/kotlin/realm-database/crud/create.txt +++ b/source/sdk/kotlin/realm-database/crud/create.txt @@ -15,8 +15,8 @@ Create Realm Objects - Kotlin SDK You can only insert new objects into a realm within a :ref:`write transaction `. -Create a New Realm Object -------------------------- +Create an Object +---------------- Instantiate Realm objects as you would any other object. In a transaction, you can add the object to the realm if the @@ -39,7 +39,7 @@ To persist a new object to a realm: #. Pass the new object instance to `copyToRealm() <{+kotlin-local-prefix+}io.realm.kotlin/-mutable-realm/copy-to-realm.html>`__ to persist the object data to the realm. This method returns a - **managed** instance of the object. You can modify the persisted + *managed* instance of the object. You can modify the persisted object through the returned instance. .. literalinclude:: /examples/generated/kotlin/CRUDTest.snippet.create-a-new-object.kt @@ -50,18 +50,46 @@ To persist a new object to a realm: You can also upsert into a realm using specific criteria. See :ref:`Upsert a Realm Object `. -Create an Embedded Object -------------------------- +Create a Collection +------------------- -To create an :ref:`embedded object `, assign an instance of the -`EmbeddedRealmObject <{+kotlin-local-prefix+}io.realm.kotlin.types/-embedded-realm-object/index.html>`__ -to a parent object's property: +You can create collections of items using +``RealmList``, ``RealmSet``, and ``RealmMap`` types. -.. literalinclude:: /examples/generated/kotlin/DataTypesTest.snippet.create-embedded-object.kt - :language: kotlin +You can also register a notification handler to listen for changes to a +collection. For more information, see +:ref:`React To Changes `. + +Create an Object with a RealmSet Property +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +You can create objects that contain :ref:`RealmSet ` +properties as you would any Realm object, but you can only set +the values of a mutable set property within a write transaction. + +For more information about defining a set property, refer to +:ref:`kotlin-define-realm-set-type`. + +Add Items to a RealmSet +``````````````````````` + +To add a single item to a ``RealmSet``, pass the object you want to add to the set to the +`set.add() <{+kotlin-local-prefix+}io.realm.kotlin.types/-realm-set/index.html#-153241610%2FFunctions%2F-1651551339>`__ +method: + +.. literalinclude:: /examples/generated/kotlin/CreateTest.snippet.create-realm-set.kt + :language: kotlin + +To add multiple items to a ``RealmSet``, pass the elements you want +to add to the `set.addAll() +<{+kotlin-local-prefix+}io.realm.kotlin.types/-realm-set/index.html#-800009087%2FFunctions%2F-1651551339>`__ +method: + +.. literalinclude:: /examples/generated/kotlin/CreateTest.snippet.add-all-to-realm-set.kt + :language: kotlin Create an Object with a Dictionary Property -------------------------------------------- +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ You can create objects with `RealmDictionary <{+kotlin-local-prefix+}io.realm.kotlin.types/-realm-dictionary/index.html>`__ @@ -79,6 +107,17 @@ For more information about defining a dictionary property, refer to .. literalinclude:: /examples/generated/kotlin/CreateTest.snippet.percent-encode-disallowed-characters.kt :language: kotlin +Create an Embedded Object +------------------------- + +To create an :ref:`embedded object `, assign an +instance of the +`EmbeddedRealmObject <{+kotlin-local-prefix+}io.realm.kotlin.types/-embedded-realm-object/index.html>`__ +to a parent object's property: + +.. literalinclude:: /examples/generated/kotlin/DataTypesTest.snippet.create-embedded-object.kt + :language: kotlin + .. _kotlin-create-asymmetric-object: Create an Asymmetric Object diff --git a/source/sdk/kotlin/realm-database/crud/delete.txt b/source/sdk/kotlin/realm-database/crud/delete.txt index 6b6f0202cd..b4e5306171 100644 --- a/source/sdk/kotlin/realm-database/crud/delete.txt +++ b/source/sdk/kotlin/realm-database/crud/delete.txt @@ -7,7 +7,7 @@ Delete Realm Objects - Kotlin SDK .. contents:: On this page :local: :backlinks: none - :depth: 2 + :depth: 1 :class: singlecol .. note:: @@ -95,6 +95,33 @@ To delete all objects of a type from a realm: .. literalinclude:: /examples/generated/kotlin/CRUDTest.snippet.delete-all-objects-of-a-type.kt :language: kotlin +Delete Items from a RealmSet +---------------------------- + +:ref:`RealmSet ` instances that contain Realm objects +only store references to those objects, so deleting a Realm object from a +realm also deletes that object from any ``RealmSet`` instances that contain +the object. + +You can delete one or more items from a ``RealmSet`` at a time: + +- To remove one item from a ``RealmSet``, pass the element + you want to delete to + `set.remove() <{+kotlin-local-prefix+}io.realm.kotlin.types/-realm-set/index.html#-1503494415%2FFunctions%2F-1651551339>`__. +- To remove multiple items from a ``RealmSet``, pass the + elements you want to delete to + `set.removeAll() <{+kotlin-local-prefix+}io.realm.kotlin.types/-realm-set/index.html#430447804%2FFunctions%2F-1651551339>`__. + +.. literalinclude:: /examples/generated/kotlin/DeleteTest.snippet.remove-item-from-set.kt + :language: kotlin + +Alternatively, you can use +`set.clear() <{+kotlin-local-prefix+}io.realm.kotlin.types/-realm-set/index.html#-767459876%2FFunctions%2F878332154>`__ +to clear all items from a ``RealmSet``: + +.. literalinclude:: /examples/generated/kotlin/DeleteTest.snippet.clear-set.kt + :language: kotlin + .. _kotlin-delete-dictionary-keys-values: Delete Dictionary Keys/Values diff --git a/source/sdk/kotlin/realm-database/crud/read.txt b/source/sdk/kotlin/realm-database/crud/read.txt index 221edbbec7..b6a94a76d2 100644 --- a/source/sdk/kotlin/realm-database/crud/read.txt +++ b/source/sdk/kotlin/realm-database/crud/read.txt @@ -50,8 +50,8 @@ and pass the type as a type parameter to `realm.query() .. literalinclude:: /examples/generated/kotlin/CRUDTest.snippet.find-all-objects-of-a-type.kt :language: kotlin -Find an Embedded Object -~~~~~~~~~~~~~~~~~~~~~~~ +Query an Embedded Object +~~~~~~~~~~~~~~~~~~~~~~~~ You can query an :ref:`embedded object ` directly or through the parent object. You can also use the @@ -61,8 +61,8 @@ method to access the parent of the embedded object. .. literalinclude:: /examples/generated/kotlin/DataTypesTest.snippet.query-embedded-objects.kt :language: kotlin -Read an Object with a Dictionary Property -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Query a Dictionary Property +~~~~~~~~~~~~~~~~~~~~~~~~~~~ You can iterate and check the values of a `RealmDictionary <{+kotlin-local-prefix+}io.realm.kotlin.types/-realm-dictionary/index.html>`__ @@ -71,6 +71,32 @@ as you would a Kotlin Map. .. literalinclude:: /examples/generated/kotlin/ReadTest.snippet.read-realm-dictionary.kt :language: kotlin +Query a RealmSet Property +~~~~~~~~~~~~~~~~~~~~~~~~~ + +You can query a :ref:`RealmSet ` property: + +.. literalinclude:: /examples/generated/kotlin/ReadTest.snippet.read-realm-set.kt + :language: kotlin + +Check if the RealmSet Contains Items +```````````````````````````````````` + +You can check if the ``RealmSet`` contains one or more elements: + +- To check if the set contains a particular item, pass the + element to `set.contains() + <{+kotlin-local-prefix+}io.realm.kotlin.types/-realm-set/index.html#607101300%2FFunctions%2F-1651551339>`__. +- To check if the ``RealmSet`` contains multiple items, pass + the elements to `set.containsAll() + <{+kotlin-local-prefix+}io.realm.kotlin.types/-realm-set/index.html#1318510207%2FFunctions%2F-1651551339>`__. + +Either method returns ``true`` if the set contains the +specified elements. + +.. literalinclude:: /examples/generated/kotlin/ReadTest.snippet.realm-set-contains.kt + :language: kotlin + Filter Data ----------- diff --git a/source/sdk/kotlin/realm-database/crud/update.txt b/source/sdk/kotlin/realm-database/crud/update.txt index 041e01d5e6..236f3a86eb 100644 --- a/source/sdk/kotlin/realm-database/crud/update.txt +++ b/source/sdk/kotlin/realm-database/crud/update.txt @@ -66,7 +66,8 @@ transaction: Update a Collection ------------------- -To update a collection of objects in a realm: +To update a collection of objects in a realm, such as a ``RealmList`` or +``RealmSet``: 1. Query a realm for a collection of objects with `realm.query() diff --git a/source/sdk/kotlin/realm-database/schemas/define-realm-object-model.txt b/source/sdk/kotlin/realm-database/schemas/define-realm-object-model.txt index 66fbe4465d..a1e4fd5946 100644 --- a/source/sdk/kotlin/realm-database/schemas/define-realm-object-model.txt +++ b/source/sdk/kotlin/realm-database/schemas/define-realm-object-model.txt @@ -96,7 +96,55 @@ when you :ref:`open the realm `. .. literalinclude:: /examples/generated/kotlin/SchemaTest.snippet.open-with-class.kt :language: kotlin :emphasize-lines: 2 - + + +Define a Collection +------------------- + +You can define collections of items using +``RealmList``, ``RealmSet``, and ``RealmMap`` types. + +.. _kotlin-define-realm-set-type: + +Define a RealmSet +~~~~~~~~~~~~~~~~~ + +To define a property as a :ref:`RealmSet `, specify its +type within the schema as ``RealmSet``, where T is any of the supported +:ref:`data types ` or a +`RealmObject <{+kotlin-local-prefix+}io.realm.kotlin.types/-realm-object/index.html>`__. +If a ``RealmSet``'s value is a ``RealmObject``, the value *cannot* have +null elements. + +Instantiate an unmanaged ``RealmSet`` by setting the field's default value +using the +`realmSetOf() <{+kotlin-local-prefix+}io.realm.kotlin.ext/realm-set-of.html>`__ +method. + +In the following example, we define a ``Frog`` schema with a +``favoriteSnacks`` field that is a ``RealmSet`` of ``Snack`` objects: + +.. literalinclude:: /examples/generated/kotlin/CreateTest.snippet.define-a-realm-set.kt + :language: kotlin + +.. _kotlin-define-realm-dictionary-type: + +Define a RealmDictionary/RealmMap +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +To define a :ref:`RealmDictionary `, specify its type within the schema as ``RealmDictionary``, where T is any Realm :ref:`primitive type +`, a ``RealmObject``, or an ``EmbeddedRealmObject``. +If a ``RealmDictionary``'s value is a ``RealmObject`` +or ``EmbeddedRealmObject``, the value must be declared nullable. + +.. literalinclude:: /examples/generated/kotlin/CreateTest.snippet.define-realm-dictionary-property.kt + :language: kotlin + +.. include:: /includes/map-key-string-limitations.rst + +.. literalinclude:: /examples/generated/kotlin/CreateTest.snippet.percent-encode-disallowed-characters.kt + :language: kotlin + .. _kotlin-define-embedded-object: Define an Embedded Object diff --git a/source/sdk/kotlin/realm-database/schemas/relationships.txt b/source/sdk/kotlin/realm-database/schemas/relationships.txt index 1ae5b9481c..9e5cc62344 100644 --- a/source/sdk/kotlin/realm-database/schemas/relationships.txt +++ b/source/sdk/kotlin/realm-database/schemas/relationships.txt @@ -37,6 +37,7 @@ types: - ``RealmObject`` - ``RealmList `` +- ``RealmSet `` You can also embed one Realm object directly within another to create a nested data structure. @@ -63,6 +64,8 @@ Each ``SushiPlatter`` references either zero ``Fish`` instances or one other referencing the same ``Fish`` instance; the distinction between a many-to-one and a one-to-one relationship is up to your application. +.. _kotlin-to-many-relationship: + To-Many Relationship -------------------- @@ -70,19 +73,18 @@ A to-many relationship means that an object is related in a specific way to multiple objects. You can create a relationship between one object -and any number of objects using a field of type ``RealmList`` where -``T`` is a Realm object in your application. Note that lists or sets of -``RealmObject`` cannot have null elements and must be initialized with -``realmListOf()`` or ``realmSetOf()``. +and any number of objects using a field of type ``RealmList`` or +``RealmSet``, where ``T`` is a Realm object in your application. +Note that lists or sets of ``RealmObject`` cannot contain null elements +or be null (they must be initialized with ``realmListOf()`` or ``realmSetOf()``). .. literalinclude:: /examples/generated/kotlin/SchemaTest.snippet.to-many-relationship.kt :language: kotlin - :copyable: false -RealmLists are containers of RealmObjects, but otherwise behave like a -regular collection. The same object can occur in multiple to-many -relationships; the distinction between a many-to-many and a one-to-many -relationship is up to your application. +RealmLists and RealmSets are containers of RealmObjects, but +otherwise behave like a regular collection. The same object can +occur in multiple to-many relationships; the distinction between a +many-to-many and a one-to-many relationship is up to your application. .. note:: diff --git a/source/sdk/kotlin/realm-database/schemas/supported-types.txt b/source/sdk/kotlin/realm-database/schemas/supported-types.txt index ee57575c0e..97ef8ecef3 100644 --- a/source/sdk/kotlin/realm-database/schemas/supported-types.txt +++ b/source/sdk/kotlin/realm-database/schemas/supported-types.txt @@ -116,161 +116,29 @@ In a Realm collection, all objects in a collection are of the same type. RealmSet ~~~~~~~~ -You can use the `RealmSet() -<{+kotlin-local-prefix+}io.realm.kotlin.types/-realm-set/index.html>`__ data type -to manage a collection of unique keys. ``RealmSet`` implements Kotlin's -``Set`` interface, so it works just like the built-in ``HashSet`` class, +A `RealmSet() +<{+kotlin-local-prefix+}io.realm.kotlin.types/-realm-set/index.html>`__ +collection represents a +:ref:`to-many relationship ` containing +distinct values. + +``RealmSet`` implements Kotlin's +`Set `__ +interface, so it works just like the built-in ``HashSet`` class, except managed ``RealmSet`` instances persist their contents to a realm. -``RealmSet`` instances that contain Realm objects only store references to those -objects, so deleting a Realm object from a realm also deletes that object from -any ``RealmSet`` instances that contain the object. +.. _kotlin-realm-dictionary: -Define a RealmSet -````````````````` +RealmMap/RealmDictionary +~~~~~~~~~~~~~~~~~~~~~~~~ -To define a property as a ``RealmSet``, specify its type within the schema, -where T is any of the supported :ref:`data types ` or a -`RealmObject <{+kotlin-local-prefix+}io.realm.kotlin.types/-realm-object/index.html>`__. -Note that T can be nullable (``RealmSet``) unless it is of type ``RealmObject``. - -Instantiate an unmanaged ``RealmSet`` by setting the field's default value -using the `realmSetOf() -<{+kotlin-local-prefix+}io.realm.kotlin.ext/realm-set-of.html>`__ method. - -In the following example, we define a ``Frog`` schema with a ``favoriteSnacks`` -field that is a ``RealmSet`` of ``Snack`` objects. - -.. literalinclude:: /examples/generated/kotlin/SchemaTest.snippet.define-a-realm-set.kt - :language: kotlin - -Add an Item to a RealmSet -````````````````````````` - -To add an item to a ``RealmSet``, pass the object you wish to add to the `set.add() -<{+kotlin-local-prefix+}io.realm.kotlin.types/-realm-set/index.html#-153241610%2FFunctions%2F-1651551339>`__ -method. - -In the following example, we get the ``favoriteSnacks`` set, then add a new -``Snack`` object to the set of favorite snacks. - -.. literalinclude:: /examples/generated/kotlin/SchemaTest.snippet.add-item-to-realm-set.kt - :language: kotlin - -Add Many Items to a RealmSet -```````````````````````````` - -To add multiple items to a ``RealmSet``, pass the elements you wish to add to -the `set.addAll() -<{+kotlin-local-prefix+}io.realm.kotlin.types/-realm-set/index.html#-800009087%2FFunctions%2F-1651551339>`__ -method. - -In the following example, we create several ``Snack`` objects and use the -`setOf -`__ -method to create a read-only set of the given elements. We then pass these -elements to the ``set.addAll()`` method to add them to our ``Frog`` object's favorite snacks. - -.. literalinclude:: /examples/generated/kotlin/SchemaTest.snippet.add-all-to-realm-set.kt - :language: kotlin - -Check if the RealmSet Contains an Item -`````````````````````````````````````` - -To check if the ``RealmSet`` contains a particular item, pass the element to -`set.contains() -<{+kotlin-local-prefix+}io.realm.kotlin.types/-realm-set/index.html#607101300%2FFunctions%2F-1651551339>`__. -The method returns true if the set contains the element. - -.. literalinclude:: /examples/generated/kotlin/SchemaTest.snippet.set-contains.kt - :language: kotlin - -Check if the RealmSet Contains Multiple Items -````````````````````````````````````````````` - -To check if the ``RealmSet`` contains multiple items, pass the elements to -`set.containsAll() -<{+kotlin-local-prefix+}io.realm.kotlin.types/-realm-set/index.html#1318510207%2FFunctions%2F-1651551339>`__. -The method returns true if the set contains the specified elements. - -In the following example, we pass the ``Snack`` objects we created earlier to -the ``setOf()`` method to create a read-only set of favorite snacks. Then we -check if the ``RealmSet`` contains all of these ``Snack`` objects by passing -the read-only set to ``set.containsAll()``. - -.. literalinclude:: /examples/generated/kotlin/SchemaTest.snippet.set-contains-multiple-items.kt - :language: kotlin - -Remove an Item from a RealmSet -`````````````````````````````` - -To remove an item from a ``RealmSet``, pass the element you wish to delete to `set.remove() -<{+kotlin-local-prefix+}io.realm.kotlin.types/-realm-set/index.html#-1503494415%2FFunctions%2F-1651551339>`__ - -.. literalinclude:: /examples/generated/kotlin/SchemaTest.snippet.remove-item-from-set.kt - :language: kotlin - -Remove Multiple Items from a RealmSet -````````````````````````````````````` - -To remove multiple items from a ``RealmSet``, pass the elements you wish to delete to -`set.removeAll() <{+kotlin-local-prefix+}io.realm.kotlin.types/-realm-set/index.html#430447804%2FFunctions%2F-1651551339>`__ - -In the following example, we delete the set of favorite snacks we created earlier. - -.. literalinclude:: /examples/generated/kotlin/SchemaTest.snippet.remove-multiple-items-from-set.kt - :language: kotlin - -Notifications -````````````` - -You can register a notification handler on a ``RealmSet``. Realm notifies your -handler when the set changes. To register a change listener on a single -object, generate a ``Flow`` from the ``RealmSet`` with `asFlow() -<{+kotlin-local-prefix+}io.realm.kotlin.types/-realm-list/as-flow.html>`__. -Next, use the ``collect()`` method to handle events on that ``Flow``. The ``Flow`` -emits an `initialSet() -<{+kotlin-local-prefix+}io.realm.kotlin.notifications/-initial-set/index.html>`__ -once subscribed and an `updatedSet() -<{+kotlin-local-prefix+}io.realm.kotlin.notifications/-updated-set/index.html>`__ -on change. - -In the following example, we react to changes on the ``favoriteSnacks`` set of our ``Frog`` object. - -.. literalinclude:: /examples/generated/kotlin/SchemaTest.snippet.react-to-changes-from-the-set.kt - :language: kotlin - -The ``Flow`` runs indefinitely until you `cancel the enclosing coroutine -`__ or until you -delete the parent object. - -.. literalinclude:: /examples/generated/kotlin/QuickStartTest.snippet.quick-start-unsubscribe-to-changes.kt - :language: kotlin - -.. _kotlin-define-realm-dictionary-type: - -RealmDictionary/RealmMap -~~~~~~~~~~~~~~~~~~~~~~~~~ - -You can define a -`RealmDictionary <{+kotlin-local-prefix+}io.realm.kotlin.types/-realm-dictionary/index.html>`__, -which is a specialized +A `RealmDictionary +<{+kotlin-local-prefix+}io.realm.kotlin.types/-realm-dictionary/index.html>`__ +is a specialized `RealmMap <{+kotlin-local-prefix+}io.realm.kotlin.types/-realm-map/index.html>`__ -where every key is a string. A ``RealmMap`` is an associative array that contains -key-value pairs with unique keys. - -A ``RealmDictionary`` may contain values of any Realm primitive type, either -nullable or non-nullable. If a ``RealmDictionary``'s value is a ``RealmObject`` -or ``EmbeddedRealmObject``, the value must be declared nullable. - -.. literalinclude:: /examples/generated/kotlin/CreateTest.snippet.define-realm-dictionary-property.kt - :language: kotlin - -.. include:: /includes/map-key-string-limitations.rst - -.. literalinclude:: /examples/generated/kotlin/CreateTest.snippet.percent-encode-disallowed-characters.kt - :language: kotlin +where every key is a string. A ``RealmMap`` is an associative array that +contains key-value pairs with unique keys. .. _kotlin-additional-types: