RealmSet - Kotlin SDK

Overview

You can use the RealmSet() 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, 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.

Define a RealmSet

To define a property as a RealmSet<T>, specify its type within the schema, where T is any of the supported data types or a RealmObject. Note that T can be nullable (RealmSet<T?>) unless it is of type RealmObject.

Instantiate an unmanaged RealmSet by setting the field's default value using the realmSetOf() method.

In the following example, we define a Frog schema with a favoriteSnacks field that is a RealmSet of Snack objects.

class Frog : RealmObject {
    var name: String = ""
    var favoriteSnacks: RealmSet<Snack> = realmSetOf<Snack>()
}
class Snack : RealmObject {
    var name: String? = null
}

Add an Item to a RealmSet

To add an item to a RealmSet, pass the object you wish to add to the set.add() method.

In the following example, we get the favoriteSnacks set, then add a new Snack object to the set of favorite snacks.

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)
}

Add Many Items to a RealmSet

To add multiple items to a RealmSet, pass the elements you wish to add to the set.addAll() 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.

realm.write {
    val myFrog: Frog = realm.query<Frog>("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))
    }

Check if the RealmSet Contains an Item

To check if the RealmSet contains a particular item, pass the element to set.contains(). The method returns true if the set contains the element.

Log.v("Does Kermit eat earthworms?: ${set.contains(earthWormsSnack)}") // true

Check if the RealmSet Contains Multiple Items

To check if the RealmSet contains multiple items, pass the elements to set.containsAll(). 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().

val containsAllSnacks = set.containsAll(set)
Log.v("Does Kermit eat crickets, earthworms, and wax worms?: $containsAllSnacks") // true

Remove an Item from a RealmSet

To remove an item from a RealmSet, pass the element you wish to delete to set.remove()

val fliesSnack = realm.query<Snack>("name = 'flies'").first().find()
set.remove(fliesSnack)

Remove Multiple Items from a RealmSet

To remove multiple items from a RealmSet, pass the elements you wish to delete to set.removeAll()

In the following example, we delete the set of favorite snacks we created earlier.

set.removeAll(set)

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(). Next, use the collect() method to handle events on that Flow. The Flow emits an initialSet() once subscribed and an updatedSet() on change.

In the following example, we react to changes on the favoriteSnacks set of our Frog object.

val kermitFrog = realm.query<Frog>("name = 'Kermit'").first().find()
val job = CoroutineScope(Dispatchers.Default).launch {
    kermitFrog?.favoriteSnacks
        ?.asFlow()
        ?.collect() {
            // Listen for changes to the RealmSet
        }
}

The Flow runs indefinitely until you cancel the enclosing coroutine or until you delete the parent object.

job.cancel() // cancel the coroutine containing the listener