MutableRealmInt

A 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.

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.

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")
.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 MutableRealmInts across RealmObjects 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:

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.

Constructors

Link copied to clipboard
constructor()

Types

Link copied to clipboard
object Companion

Functions

Link copied to clipboard
infix fun and(other: Number): MutableRealmInt

Performs a bitwise AND operation between the two values.

Link copied to clipboard
open operator override fun compareTo(other: MutableRealmInt): Int

MutableRealmInts compare strictly by their Long values.

Link copied to clipboard
operator fun dec(): MutableRealmInt

Returns this value decremented by one.

Link copied to clipboard
abstract fun decrement(value: Number)

Decrements the MutableRealmInt, subtracting the value of the argument. Increment/decrement operations from all devices are reflected in the new value, which is guaranteed to converge. This operation should not be confused with the dec operator, which returns a new value whereas this one modifies the value itself.

Link copied to clipboard
operator fun div(other: Number): MutableRealmInt

Divides this value by the other value, truncating the result to an integer that is closer to zero. The other value will be converted to Long before applying the operator.

Link copied to clipboard
open operator override fun equals(other: Any?): Boolean

Two MutableRealmInts are equal if and only if their Long values are equal.

Link copied to clipboard
abstract fun get(): Long

Gets the MutableRealmInt value.

Link copied to clipboard
open override fun hashCode(): Int

A MutableRealmInt's hash code is, exactly, the hash code of its value.

Link copied to clipboard
operator fun inc(): MutableRealmInt

Returns this value incremented by one.

Link copied to clipboard
abstract fun increment(value: Number)

Increments the MutableRealmInt, adding the value of the argument. Increment/decrement operations from all devices are reflected in the new value, which is guaranteed to converge. This operation should not be confused with the inc operator, which returns a new value whereas this one modifies the value itself.

Link copied to clipboard

Inverts the bits in this value.

Link copied to clipboard
operator fun minus(other: Number): MutableRealmInt

Subtracts the other value from this value. The other value will be converted to Long before applying the operator.

Link copied to clipboard
infix fun or(other: Number): MutableRealmInt

Performs a bitwise OR operation between the two values.

Link copied to clipboard
operator fun plus(other: Number): MutableRealmInt

Adds the other value to this value. The other value will be converted to Long before applying the operator.

Link copied to clipboard
operator fun rem(other: Number): MutableRealmInt

Calculates the remainder of truncating division of this value by the other value. The result is either zero or has the same sign as the dividend and has the absolute value less than the absolute value of the divisor. The other value will be converted to Long before applying the operator.

Link copied to clipboard
abstract fun set(value: Number)

Sets the MutableRealmInt value.

Link copied to clipboard
infix fun shl(bitCount: Int): MutableRealmInt

Shifts this value left by the bitCount number of bits.

Link copied to clipboard
infix fun shr(bitCount: Int): MutableRealmInt

Shifts this value right by the bitCount number of bits, filling the leftmost bits with copies of the sign bit.

Link copied to clipboard
operator fun times(other: Number): MutableRealmInt

Multiplies this value by the other value. The other value will be converted to Long before applying the operator.

Link copied to clipboard
open override fun toByte(): Byte
Link copied to clipboard
open override fun toChar(): Char
Link copied to clipboard
open override fun toDouble(): Double
Link copied to clipboard
open override fun toFloat(): Float
Link copied to clipboard
open override fun toInt(): Int
Link copied to clipboard
open override fun toLong(): Long
Link copied to clipboard
open override fun toShort(): Short
Link copied to clipboard
open override fun toString(): String
Link copied to clipboard
operator fun unaryMinus(): MutableRealmInt

Returns the negative of this value.

Link copied to clipboard
operator fun unaryPlus(): MutableRealmInt

Returns this value.

Link copied to clipboard
infix fun ushr(bitCount: Int): MutableRealmInt

Shifts this value right by the bitCount number of bits, filling the leftmost bits with zeros.

Link copied to clipboard
infix fun xor(other: Number): MutableRealmInt

Performs a bitwise XOR operation between the two values.