BsonArray¶

@Serializable(with = ContextualSerializer::class)
interface BsonArray

A BSON array.

To create instances of this class, see BsonFactory.

Navigating BSON types¶

This interface is part of the BSON trinity:

BsonDocument represents an entire BSON document.
BsonArray represents an array of BSON values.
BsonValue represents a single value in isolation.

Usage¶

val bson: BsonArray = …

for (element in bson) {
    println("Element: $element")
}

Equality¶

Different implementations of this interface are considered equal if they represent the same value with the same type. That is, both values would result in the exact same BSON sent over the wire.

The methods BsonArray.Companion.equals and BsonArray.Companion.hashCode are provided as default implementations.

Types¶

`Companion`¶

object Companion

Properties¶

factory¶

abstract val factory: BsonFactory

The instance of BsonFactory that created this instance.

BsonFactory contains the serialization configuration that apply to this array.

indices¶

open val indices: IntRange

lastIndex¶

open val lastIndex: Int

size¶

abstract val size: Int

The number of items in this array.

Functions¶

asIterable¶

abstract fun asIterable(): Iterable<BsonValue>

Creates an Iterable that wraps this array.

Requirements

The Iterable.toString output should follow the same rules as on BsonArray itself.

asList¶

abstract fun asList(): List<BsonValue>

Creates a List view of this array.

asSequence¶

abstract fun asSequence(): Sequence<BsonValue>

Creates a Sequence of the items in this array.

Requirements

The Sequence.toString output should follow the same rules as the BsonArray itself.

asValue¶

abstract fun asValue(): BsonValue

Returns the BsonValue equivalent to this array.

The returned value has type BsonType.Array and its BsonValue.decodeArray method returns this array.

decode¶

@LowLevelApi
abstract fun <T> decode(type: KType): T

Decodes this array into an instance of the Kotlin type T.

T should be a type that contains elements, such as List<Int> or Set<User>.

To decode this array as a List of elements, see decodeElements instead.

Serialization configuration

This method uses the serialization methods configured in the BsonFactory that created this instance.

For example, if you use the official Java or Kotlin MongoDB drivers, this method will use your configured CodecRegistry.

Example

data class User(
    val name: String,
    val age: Int?,
)

val factory: BsonFactory = …

val bson = factory.buildDocument {
    writeArray("users") {
        writeDocument {
            writeString("name", "Alice")
            writeInt32("age", 13)
        }

        writeDocument {
            writeString("name", "Bob")
            writeInt32("age", 52)
        }
    }
}

val users = bson["users"]?.decode<List<User>>()

println(users[0].name) // Alice
println(users[1].age)  // 13

Overloads

Prefer using the parameter-less overload.

If type doesn't match T, the behavior is unspecified.

Throws

BsonDecodingException: If the value cannot be decoded as an instance of T.

decode¶

inline fun <T> BsonArray.decode(): T

Decodes this array into an instance of the Kotlin type T.

T should be a type that contains elements, such as List<Int> or Set<User>.

To decode this array as a List of elements, see decodeElements instead.

Serialization configuration

This method uses the serialization methods configured in the BsonFactory that created this instance.

For example, if you use the official Java or Kotlin MongoDB drivers, this method will use your configured CodecRegistry.

Example

data class User(
    val name: String,
    val age: Int?,
)

val factory: BsonFactory = …

val bson = factory.buildDocument {
    writeArray("users") {
        writeDocument {
            writeString("name", "Alice")
            writeInt32("age", 13)
        }

        writeDocument {
            writeString("name", "Bob")
            writeInt32("age", 52)
        }
    }
}

val users = bson["users"]?.decode<List<User>>()

println(users[0].name) // Alice
println(users[1].age)  // 13

Throws

BsonDecodingException: If the value cannot be decoded as an instance of T.

inline fun <T> BsonDocument.decode(): T

Decodes this document into an instance of the Kotlin type T.

Serialization configuration

This method uses the serialization methods configured in the BsonFactory that created this instance.

For example, if you use the official Java or Kotlin MongoDB drivers, this method will use your configured CodecRegistry.

Example

data class User(
    val _id: ObjectId,
    val profile: Profile,
)

data class Profile(
    val name: String,
    val age: Int?,
)

val factory: BsonFactory = …

val bson = factory.buildDocument {
    writeObjectId("_id", ObjectId("69c93e17b96e83b72d11b734"))
    writeDocument("profile") {
        writeString("name", "Bob")
        writeInt32("age", 30)
    }
}

val user = bson.decode<User>()

println(user._id)          // ObjectId(69c93e17b96e83b72d11b734)
println(user.profile.name) // Bob
println(user.profile.age)  // 30

Throws

BsonDecodingException: If the value cannot be decoded as an instance of T.

inline fun <T> BsonValue.decode(): T

Decodes this value into an instance of the Kotlin type T.

Serialization configuration

This method uses the serialization methods configured in the BsonFactory that created this instance.

For example, if you use the official Java or Kotlin MongoDB drivers, this method will use your configured CodecRegistry.

Example

data class User(
    val name: String,
    val age: Int,
)

val factory: BsonFactory = …

val bson = factory.buildDocument {
    writeDocument("personalInfo") {
        writeString("name", "Bob")
        writeInt32("age", 30)
    }
}

val user = bson["personalInfo"]!!.decode<User>()

println(user.name)  // Bob
println(user.age)   // 30

decodeElements¶

@LowLevelApi
open fun <T> decodeElements(type: KType): List<T>

Decodes this array into a List of the Kotlin type T.

To decode this array into a type other than a List, see decode.

Serialization configuration

This method uses the serialization methods configured in the BsonFactory that created this instance.

For example, if you use the official Java or Kotlin MongoDB drivers, this method will use your configured CodecRegistry.

Example

data class User(
    val name: String,
    val age: Int?,
)

val factory: BsonFactory = …

val bson = factory.buildDocument {
    writeArray("users") {
        writeDocument {
            writeString("name", "Alice")
            writeInt32("age", 13)
        }

        writeDocument {
            writeString("name", "Bob")
            writeInt32("age", 52)
        }
    }
}

val users = bson["users"]?.decodeElements<User>()

println(users[0].name) // Alice
println(users[1].age)  // 13

Overloads

Prefer using the parameter-less overload.

If type doesn't match T, the behavior is unspecified.

Throws

BsonDecodingException: If the value cannot be decoded as an instance of T.

decodeElements¶

inline fun <T> BsonArray.decodeElements(): List<T>

Decodes this array into a List of the Kotlin type T.

To decode this array into a type other than a List, see decode.

Serialization configuration

This method uses the serialization methods configured in the BsonFactory that created this instance.

For example, if you use the official Java or Kotlin MongoDB drivers, this method will use your configured CodecRegistry.

Example

data class User(
    val name: String,
    val age: Int?,
)

val factory: BsonFactory = …

val bson = factory.buildDocument {
    writeArray("users") {
        writeDocument {
            writeString("name", "Alice")
            writeInt32("age", 13)
        }

        writeDocument {
            writeString("name", "Bob")
            writeInt32("age", 52)
        }
    }
}

val users = bson["users"]?.decodeElements<User>()

println(users[0].name) // Alice
println(users[1].age)  // 13

Throws

BsonDecodingException: If the value cannot be decoded as an instance of T.

diff¶

infix fun BsonDocument.diff(other: BsonDocument): String?

Analyzes the difference between two BSON documents.

This function is particularly useful in tests. Since BSON documents can be large, it may be difficult to find what the difference between two documents is.

This function generates human-readable output to find the differences.

Example

val a = factory.buildDocument {
    writeString("a", "foo")
    writeDocument("b") {
        writeString("name", "Bob")
        writeInt32("age", 18)
    }
}

val b = factory.buildDocument {
    writeString("a", "foo")
    writeDocument("b") {
        writeString("name", "Alice")
        writeInt32("age", 19)
    }
}

println(a diff b)

✓ a: "foo"
✗ b:
     ✗ name: "Bob"
             "Alice"
     ✓ age: 18
            19

Return

If the two documents are equal, returns null. Otherwise, generates a human-readable diff.

infix fun BsonArray.diff(other: BsonArray): String?

Analyzes the difference between two BSON arrays.

This function is particularly useful in tests. Since BSON arrays can be large, it may be difficult to find what the difference between two documents is.

This function generates human-readable output to find the differences.

Example

val a = factory.buildArray {
    writeString("foo")
    writeDocument {
        writeString("name", "Bob")
        writeInt32("age", 18)
    }
}

val b = factory.buildArray {
    writeString("foo")
    writeDocument {
        writeString("name", "Alice")
        writeInt32("age", 19)
    }
}

println(a diff b)

✓ 0: "foo"
✗ 1:
     ✗ name: "Bob"
             "Alice"
     ✓ age: 18
            19

Return

If the two arrays are equal, returns null. Otherwise, generates a human-readable diff.

infix fun BsonValue.diff(other: BsonValue): String?

Analyzes the difference between two BSON values.

This function is particularly useful in tests. Since BSON documents can be large, it may be difficult to find what the difference between two documents is.

This function generates human-readable output to find the differences.

Return

If the two documents are equal, returns null. Otherwise, generates a human-readable diff.

get¶

abstract operator fun get(index: Int): BsonValue?

Returns the element in the array at index.

Just like in Kotlin, index should start at 0 and increase monotonically.

This method returns null if there is no element with an index of index. Note that if there is an element at index, and it has the value null, then a BsonValue with type BsonType.Null is returned.

isEmpty¶

open fun isEmpty(): Boolean

Returns true if this array has no elements.

isNotEmpty¶

open fun isNotEmpty(): Boolean

Returns true if this array has at least one element.

iterator¶

abstract operator fun iterator(): Iterator<BsonValue>

Iterates over the elements in this array.

toString¶

abstract override fun toString(): String

JSON representation of this BsonArray, as a String.

withIndex¶

abstract fun withIndex(): Iterable<IndexedValue<BsonValue>>

Iterates over this array, returning both each item and its index.

See also

Iterable.withIndex

BsonArray¶

Navigating BSON types¶

Usage¶

Equality¶

Types¶

Companion¶

Properties¶

factory¶

indices¶

lastIndex¶

size¶

Functions¶

asIterable¶

asList¶

asSequence¶

asValue¶

decode¶

decode¶

decodeElements¶

decodeElements¶

diff¶

get¶

isEmpty¶

isNotEmpty¶

iterator¶

toString¶

withIndex¶

`Companion`¶