MutableRealmInt is a mutable, Long-like, numeric quantity.
MutableRealmInts are most interesting as members of a managed RealmObject object in a synchronized Realm. When managed, the increment and decrement operators implement a conflict-free replicated data type: simultaneous increments and decrements from multiple distributed clients will be aggregated correctly. For instance, if the value of a
counter field for the object representing a
User named Fred is currently 0, then the following code, executed on two different devices, simultaneously, even if connected by a slow, unreliable network, will always cause the value of
counter to eventually converge on the value 2.
query<User>("name = $0", "Fred")
Note that the set operator must be used with care. It will quash the effects of any prior calls to increment or decrement. Although the value of a
MutableRealmInt will always converge across devices, the specific value on which it converges will depend on the actual order in which operations took place. Mixing set with increment and/or decrement is, therefore, not advised, unless fuzzy counting is acceptable.
MutableRealmInts cannot be primary keys.
MutableRealmInts cannot store
null values. However, it is possible to declare nullable
MutableRealmInt class members:
var counter: MutableRealmInteger? = null
A reference to a managed
MutableRealmInt is subject to all of the constraints that apply to the model object from which it was obtained: It can only be mutated within a transaction and it becomes invalid if the Realm backing it is closed. Note that a reference to a managed
MutableRealmInt retains a reference to the model object to which it belongs. For example in this code:
val counter: MutableRealmInt = realm.query<User>("user = $0", "Fred")
counter holds a reference to the
User model object from which it was obtained. Neither can be GCed until all references to both are unreachable.
It is worth noting that sharing
RealmObjects results in different behaviors depending on whether the objects are managed. For example, in this code
userB are unmanaged instances:
val userA: User = ... // userA.counter = 42
val userB: User = ... // userB.counter = null
userB.counter = userA.counter // both now point to the same reference
println(userA.counter.get()) // 43
println(userB.counter.get()) // 43
The assignment is done by reference as expected. However, on managed objects it is done by value as is the case for all other Realm primitive types. This means that the last two lines in the code above will yield a different result in case
userB are managed objects:
println(managedUserA.counter.get()) // 43
println(managedUserB.counter.get()) // 42
In addition to the API functions,
MutableRealmInt is a subclass of Number. This allows users to convert the boxed values stored in the instance to other numeric types. Moreover, the class provides a set of operators and infix functions similar to the ones provided by Long:
Equality operators: equals
Comparison operators: compareTo
Both binary operators and logic bitwise functions enforce conversion of the received value to
Long for convenience so precision loss may occur when computing the result depending on the type of the received Number. Additionally, all these operators and infix functions do not mutate the instance on which they are executed. For example, calling
counter.inc() will not modify
counter but rather create a new, unmanaged
MutableRealmInt with the updated value. The only operations that result in a mutated value are set, increment and decrement.