BsonDocumentReader

@LowLevelApi



interface BsonDocumentReader

Utilities for decomposing a Bson document into its fields.

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

Example

val bson: Bson = …

for ((name, field) in bson.read().entries) {
    println("Field: $name • ${field.type}")
}

Implementation constraints

Different implementations of BsonDocumentReader should be considered equal if they have the same fields which each have the same values. The methods BsonDocumentReader.Companion.equals and BsonDocumentReader.Companion.hashCode are provided to facilitate implementation.

Types

Companion

object Companion

Properties

entries

abstract val entries: Map<String, BsonValueReader>

A map allowing to go through all key-value pairs in the document.

Keys of this map are names of fields. Value of this map are the result of calling read for the given name.

names

open val names: Set<String>

A set of the field names in the document.

Functions

asValue

abstract fun asValue(): BsonValueReader

Reads this entire document 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(name: String): BsonValueReader?

Attempts to read a field named name.

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

Note that if a field 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.

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

This function is a low-level implementation detail. Prefer using the extension function of the same name, that takes no arguments. If type and klass refer to different types, the behavior is unspecified.

toBson

abstract fun toBson(): Bson

Reads this document into a Bson instance.

toString

abstract override fun toString(): String

JSON representation of the document this BsonDocumentReader is reading, as a String.