MutableRealmInt
A MutableRealmInt
is a mutable, Long-like, numeric quantity.
MutableRealmInt
s 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.
realm.write {
query<User>("name = $0", "Fred")
.first()
.find()!!
.counter
.increment(1)
}
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.
MutableRealmInt
s cannot be primary keys.
MutableRealmInt
s 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")
.first()
.find()!!
.counter
the 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 MutableRealmInt
s across RealmObject
s results in different behaviors depending on whether the objects are managed. For example, in this code userA
and 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
userA.counter.increment()
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 userA
and userB
are managed objects:
managedUserA.counter.increment()
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:
Unary prefix operators: unaryPlus, unaryMinus
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, unmanagedMutableRealmInt
with the updated value. The only operations that result in a mutated value are set, increment and decrement.