Bson¶

interface Bson

A BSON document.

To create instances of this class, see BsonFactory.

Implementation constraints¶

equals and hashCode should follow the same constraints as BsonDocumentReader's implementations.

Functions¶

at¶

infix inline fun <T> Bson.at(path: BsonPath): T

Finds the first value that matches path in a given BSON document.

Example¶

val document: Bson = …

val bar: String = document at BsonPath["foo"]["bar"]

will return the value of the field foo.bar.

Depending on your situation, you can also use the equivalent function selectFirst:

val document: Bson = …

document.selectFirst<String>(BsonPath["foo"]["bar"])

See also

BsonPath: Learn more about BSON paths.
select: Select multiple values with a BSON path.

Throws

NoSuchElementException: If no element is found matching the path.

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¶

inline fun <T : Any> Bson.read(): T?

Reads this document into an instance of type T.

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

See also

BsonContext.write: The inverse operation.

reader¶

@LowLevelApi



abstract fun reader(): BsonDocumentReader

Reads the fields of this document.

select¶

inline fun <T> Bson.select(path: BsonPath): Sequence<T>

Finds all values that match path in a given BSON document.

Example¶

val document: Bson = …

document.select<String>(BsonPath["foo"]["bar"]).firstOrNull()

will return the value of the field foo.bar.

See also

BsonPath: Learn more about BSON paths.
selectFirst: If you're only interested about a single element. See also at.

inline fun <T> Bson.select(@Language



(value = "JSONPath") path: String): Sequence<T>

Finds all values that match path in a given BSON document.

To learn more about the syntax, see BsonPath.

Example¶

val document: Bson = …

document.select<String>("$.foo.bar")

will return a sequence of all values matching the path foo.bar.

See also

at: Select a single value.

selectFirst¶

inline fun <T> Bson.selectFirst(path: BsonPath): T

Finds the first value that matches path in a given BSON document.

Example¶

val document: Bson = …

document.selectFirst<String>(BsonPath["foo"]["bar"])

will return the value of the field foo.bar.

Alternatives¶

Depending on your situation, you can also use the equivalent function at:

val document: Bson = …

val bar: String = document at BsonPath["foo"]["bar"]

See also

BsonPath: Learn more about BSON paths.
select: Select multiple values with a BSON path.

Throws

NoSuchElementException: If no element is found matching the path.

inline fun <T> Bson.selectFirst(@Language



(value = "JSONPath") path: String): T

Finds the first value that matches path in a given BSON document.

To learn more about the syntax, see BsonPath.

Example¶

val document: Bson = …

document.selectFirst<String>("$.foo.bar")

will return the value of the field foo.bar.

See also

BsonPath: Learn more about BSON paths.
select: Select multiple values with a BSON path.
at: Select a single value using infix notation.

toByteArray¶

@LowLevelApi



abstract fun toByteArray(): ByteArray

Low-level byte representation of this BSON document.

toString¶

abstract override fun toString(): String

JSON representation of this Bson object, as a String.