BsonArrayReader

@LowLevelApi



interface BsonArrayReader

Utilities for decomposing a BsonArray into its elements.

To obtain an instance of this interface, see BsonArray.reader.

Example

val bson: BsonArray = …

for ((index, field) in bson.read().elements.withIndex()) {
    println("[$index] • ${field.type}")
}

Implementation constraints

Different implementations of BsonArrayReader should be considered equal if they have the same elements in the same order. The methods BsonArrayReader.Companion.equals and BsonArrayReader.Companion.hashCode are provided to facilitate implementation.

Types

Companion

object Companion

Properties

elements

abstract val elements: List<BsonValueReader>

A list of all elements in this reader.

Values of this map are the elements contained by this array. To go through this list with its indices, see Iterable.withIndex or Collection.indices.

indices

open val indices: IntRange

A range of the valid indices in this array.

size

open val size: Int

The number of elements in this array.

To iterate over the elements by index, see indices.

Functions

asValue

abstract fun asValue(): BsonValueReader

Reads this entire array as a BsonValueReader.

diff

@LowLevelApi



infix fun BsonDocumentReader.diff(other: BsonDocumentReader): 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.reader() diff b.reader())

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

Return

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

@LowLevelApi



infix fun BsonArrayReader.diff(other: BsonArrayReader): 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.reader() diff b.reader())

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

Return

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

@LowLevelApi



infix fun BsonValueReader.diff(other: BsonValueReader): 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.

infix fun Bson.diff(other: Bson): 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.

read

abstract fun read(index: Int): BsonValueReader?

Attempts to read an element at index index.

If such an element exists, an instance of BsonValueReader is returned. If no such element exists, null is returned.

Note that if an element exists and is null, a instance of BsonValueReader with a type of null is returned.

abstract fun <T : Any> read(type: KType, klass: KClass<T>): T?

Reads this document into an instance of type.

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

If it isn't possible to deserialize this BSON to the given type, an exception is thrown.

toBson

abstract fun toBson(): BsonArray

Reads this document into a BsonArray instance.

toString

abstract override fun toString(): String

JSON representation of the array this BsonArrayReader is reading, as a String.