Skip to content

BsonValueReader

@LowLevelApi



interface BsonValueReader

Representation of a BSON value.

See the type to know which accessor to use. All other accessors will fail with a BsonReaderException.

To obtain instances of this interface, see BsonDocumentReader.read and BsonArrayReader.read.

Implementation constraints

Different implementations of BsonValueReader should be 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 BsonValueReader.Companion.equals and BsonValueReader.Companion.hashCode are provided to facilitate implementation.

Types

Companion

object Companion

Properties

type

abstract val type: BsonType

The type of this value.

To access its value, see the accessor function corresponding to this type. All other accessors will fail with BsonReaderException.

Functions

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 <T : Any> read(type: KType, klass: KClass<T>): T?

Reads this reader into an instance of type.

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

readArray

@LowLevelApi



abstract fun readArray(): BsonArrayReader

readBinaryData

@LowLevelApi



abstract fun readBinaryData(): ByteArray

readBinaryDataType

@LowLevelApi



abstract fun readBinaryDataType(): UByte

readBoolean

@LowLevelApi



abstract fun readBoolean(): Boolean

readDateTime

@LowLevelApi



abstract fun readDateTime(): Long

readDBPointerId

@LowLevelApi



abstract fun readDBPointerId(): ByteArray
Deprecated

This functionality is deprecated in the BSON specification. See https://bsonspec.org/spec.html

readDBPointerNamespace

@LowLevelApi



abstract fun readDBPointerNamespace(): String
Deprecated

This functionality is deprecated in the BSON specification. See https://bsonspec.org/spec.html

readDecimal128

@LowLevelApi



abstract fun readDecimal128(): ByteArray

readDocument

@LowLevelApi



abstract fun readDocument(): BsonDocumentReader

readDouble

@LowLevelApi



abstract fun readDouble(): Double

readInstant

@LowLevelApi



open fun readInstant(): Instant

Reads an Instant. Conversion function on top of readDateTime.

readInt32

@LowLevelApi



abstract fun readInt32(): Int

readInt64

@LowLevelApi



abstract fun readInt64(): Long

readJavaScript

@LowLevelApi



abstract fun readJavaScript(): String

readJavaScriptWithScope

@LowLevelApi



abstract fun readJavaScriptWithScope(): String
Deprecated

This functionality is deprecated in the BSON specification. See https://bsonspec.org/spec.html

readMaxKey

@LowLevelApi



abstract fun readMaxKey()

readMinKey

@LowLevelApi



abstract fun readMinKey()

readNull

@LowLevelApi



abstract fun readNull()

readObjectId

@LowLevelApi



abstract fun readObjectId(): ObjectId

readObjectIdBytes

@LowLevelApi



abstract fun readObjectIdBytes(): ByteArray

readRegularExpressionOptions

@LowLevelApi



abstract fun readRegularExpressionOptions(): String

readRegularExpressionPattern

@LowLevelApi



abstract fun readRegularExpressionPattern(): String

readString

@LowLevelApi



abstract fun readString(): String

readSymbol

@LowLevelApi



abstract fun readSymbol(): String
Deprecated

This functionality is deprecated in the BSON specification. See https://bsonspec.org/spec.html

readTimestamp

@LowLevelApi



abstract fun readTimestamp(): Timestamp

readUndefined

@LowLevelApi



abstract fun readUndefined()
Deprecated

This functionality is deprecated in the BSON specification. See https://bsonspec.org/spec.html

readVector

@LowLevelApi



open fun readVector(): Vector

toString

abstract override fun toString(): String

JSON representation of this value.