Skip to content

StringValueOperators

interface StringValueOperators : ValueOperators

String aggregation operators.

External resources

Inheritors

Properties

context

@LowLevelApi



abstract override val context: BsonContext

The strategy used when converting from KProperty1 to Field.

field

Converts a Kotlin property into a Field.

length

Returns the number of code points in the specified string.

If the argument resolves to null, this function returns null.

Counting characters

This function uses MongoDB's $strLenCP operator, which counts characters using Unicode code points. This differs from Kotlin's String.length, which uses UTF-16 code units. For strings containing characters outside the Basic Multilingual Plane (like emoji or certain mathematical symbols), the counting behavior will differ.

For example, the emoji "👨‍👩‍👧‍👦" (family) is a single Unicode grapheme cluster but consists of multiple code points. According to this operator, it has a length of 7. However, according to Kotlin's String.length, it has a length of 11.

Example
class Document(
    val text: String,
    val length: Int,
)

collection.aggregate()
    .set {
        Document::length set of(Document::text).length
    }.toList()
External resources

See also

lengthUTF8

Returns the number of UTF-8 encoded bytes in the specified string.

If the argument resolves to null, this function returns null.

Counting characters

This function uses MongoDB's $strLenBytes operator, which counts characters using UTF-8 encoded bytes where each code point, or character, may use between one and four bytes to encode. This differs from the length property which uses Unicode code points.

For example, US-ASCII characters are encoded using one byte. Characters with diacritic markings and additional Latin alphabetical characters are encoded using two bytes. Chinese, Japanese and Korean characters typically require three bytes, and other planes of Unicode (emoji, mathematical symbols, etc.) require four bytes.

Example
class Document(
    val text: String,
    val byteLength: Int,
)

collection.aggregate()
    .set {
        Document::byteLength set of(Document::text).lengthUTF8
    }.toList()
External resources

See also

Functions

concat

open fun <Context : Any> concat(strings: List<Value<Context, String?>>): Value<Context, String?>

Concatenates strings together.

If any of strings are null, the concatenation returns null.

Example
class Document(
    val firstName: String,
    val lastName: String,
    val fullName: String,
)

collection.aggregate()
    .set {
        Document::fullName set concat(of(Document::firstName), of(" "), of(Document::lastName))
    }
    .toList()
External resources
open fun <Context : Any> concat(vararg strings: Value<Context, String?>): Value<Context, String?>

Concatenates strings together.

If any of strings are null, the concatenation returns null.

Example
class Document(
    val firstName: String,
    val lastName: String,
    val fullName: String,
)

collection.aggregate()
    .set {
        Document::fullName set concat(of(Document::firstName), of(" "), of(Document::lastName))
    }
    .toList()
External resources
open infix fun <Context : Any> Value<Context, String?>.concat(other: Value<Context, String?>): Value<Context, String?>

Concatenates strings together.

If any of strings are null, the concatenation returns null.

Example
class Document(
    val firstName: String,
    val lastName: String,
    val fullName: String,
)

collection.aggregate()
    .set {
        Document::fullName set (of(Document::firstName) concat of(" ") concat of(Document::lastName))
    }
    .toList()
External resources

div

open operator fun <Context : Any, Root, Child> Value<Context, Root>.div(field: Field<Root, Child>): Value<Context, Child>

Refers to field as a nested field of the current value.

Examples
class User(
    val name: String,
)

class Data(
    val users: List<User>,
    val userNames: List<Int>,
)

data.aggregate()
    .set {
        Data::userNames set Data::users.map { it / User::name }
    }
External resources
open operator fun <Context : Any, Root, Child> Value<Context, Root>.div(field: KProperty1<Root, Child>): Value<Context, Child>

Refers to field as a nested field of the current value.

Examples
class User(
    val name: String,
)

class Data(
    val users: List<User>,
    val userNames: List<Int>,
)

data.aggregate()
    .set {
        Data::userNames set Data::users.map { it / User::name }
    }
External resources

get

open operator fun <Root, Type> KProperty1<Root, Collection<Type>>.get(index: Int): Field<Root, Type>

Refers to a specific item in an array, by its index.

open operator fun <Root, Type> KProperty1<Root, Map<String, Type>>.get(index: String): Field<Root, Type>

Refers to a specific item in a map, by its name.

open operator fun <Root, Type> Field<Root, Collection<Type>>.get(index: Int): Field<Root, Type>

Refers to a specific item in an array, by its index.

open operator fun <Root, Type> Field<Root, Map<String, Type>>.get(key: String): Field<Root, Type>

Refers to a specific item in a map, by its name.

lowercase

Converts a string to lowercase, returning the result.

If the argument resolves to null, $toLower returns an empty string "".

Example
class Document(
    val text: String,
)

collection.aggregate()
    .set {
        Document::text set of(Document::text).lowercase()
    }.toList()
External resources

of

open fun <Context : Any, Result> of(field: Field<Context, Result>): Value<Context, Result>

Refers to a field within an aggregation value.

Example
class Product(
    val acceptanceDate: Instant,
    val publishingDate: Instant,
)

val publishedBeforeAcceptance = products.find {
    expr {
        of(Product::publishingDate) lt of(Product::acceptanceDate)
    }
}

Refers to a field within an aggregation value.

Example
class Product(
    val acceptanceDate: Instant,
    val publishingDate: Instant,
)

val publishedBeforeAcceptance = products.find {
    expr {
        of(Product::publishingDate) lt of(Product::acceptanceDate)
    }
}

open fun <Result> of(value: Result): Value<Any, Result>

Refers to a Kotlin value within an aggregation value.

Example
class Product(
    val age: Int,
)

val publishedBeforeAcceptance = products.find {
    expr {
        of(Product::age) lt of(15)
    }
}

open fun of(value: BsonType): Value<Any, BsonType>

Refers to a BsonType within an aggregation value.

Example
class Product(
    val age: Int,
)

val publishedBeforeAcceptance = products.find {
    expr {
        of(Product::age).type eq of(BsonType.Int32)
    }
}

replace

open fun <Context : Any> Value<Context, String?>.replace(find: Value<Context, String?>, replacement: Value<Context, String?>): Value<Context, String?>

Replaces all instances of find with a replacement string.

If no occurrences of find are found in the input string, the input string is returned. If any of the input, find or replacement is null, null is returned.

The input, find, and replacement expressions must evaluate to a string or a null, or $replaceAll fails with an error.

Example
class Document(
    val item: String,
)

collection.aggregate()
    .set {
        Document::item set of(Document::item).replace(find = of("blue paint"), replacement = of("red paint"))
    }.toList()
External resources
open fun <Context : Any> Value<Context, String?>.replace(find: String, replacement: String): Value<Context, String?>

Replaces all instances of find with a replacement string.

If no occurrences of find are found in the input string, the input string is returned. If the input is null, null is returned.

The input must evaluate to a string or a null, or $replaceAll fails with an error.

Example
class Document(
    val item: String,
)

collection.aggregate()
    .set {
        Document::item set of(Document::item).replace(find = "blue paint", replacement = "red paint")
    }.toList()
External resources

replaceFirst

open fun <Context : Any> Value<Context, String?>.replaceFirst(find: Value<Context, String?>, replacement: Value<Context, String?>): Value<Context, String?>

Replaces the first instance of find with a replacement string.

If no occurrences of find are found in the input string, the input string is returned. If any of the input, find or replacement is null, null is returned.

The input, find, and replacement expressions must evaluate to a string or a null, or $replaceOne fails with an error.

Example
class Document(
    val item: String,
)

collection.aggregate()
    .set {
        Document::item set of(Document::item).replaceFirst(find = of("blue paint"), replacement = of("red paint"))
    }.toList()
External resources
open fun <Context : Any> Value<Context, String?>.replaceFirst(find: String, replacement: String): Value<Context, String?>

Replaces the first instance of find with a replacement string.

If no occurrences of find are found in the input string, the input string is returned. If the input is null, null is returned.

The input must evaluate to a string or a null, or $replaceOne fails with an error.

Example
class Document(
    val item: String,
)

collection.aggregate()
    .set {
        Document::item set of(Document::item).replaceFirst(find = "blue paint", replacement = "red paint")
    }.toList()
External resources

split

Divides a string into an array of substrings based on a delimiter.

$split removes the delimiter and returns the resulting substrings as elements of an array. If the delimiter is not found in the string, $split returns the original string as the only element of an array.

Both the string expression and delimiter must be strings. Otherwise, the operation fails with an error.

Example
class Document(
    val city: String,
    val cityState: List<String>,
)

collection.aggregate()
    .set {
        Document::cityState set of(Document::city).split(of(", "))
    }.toList()
External resources
open fun <Context : Any> Value<Context, String>.split(delimiter: String): Value<Context, List<String>?>

Divides a string into an array of substrings based on a delimiter.

$split removes the delimiter and returns the resulting substrings as elements of an array. If the delimiter is not found in the string, $split returns the original string as the only element of an array.

The string expression must be a string. Otherwise, the operation fails with an error.

Example
class Document(
    val city: String,
    val cityState: List<String>,
)

collection.aggregate()
    .set {
        Document::cityState set of(Document::city).split(", ")
    }.toList()
External resources

substring

open fun <Context : Any> Value<Context, String?>.substring(startIndex: Value<Context, Int>, length: Value<Context, Int>): Value<Context, String?>

Returns the substring of a string.

The substring starts with the character at the specified Unicode code point startIndex (zero-based) in the string and continues for the length number of code points specified.

Note that this behavior is different from String.substring, which expects start and end indexes.

Counting characters

This function uses MongoDB's $substrCP operator, which counts characters using Unicode code points. This differs from Kotlin's String.substring, which uses UTF-16 code units. For strings containing characters outside the Basic Multilingual Plane (like emoji or certain mathematical symbols), the indexing behavior will differ.

For example, the emoji "👨‍👩‍👧‍👦" (family) is a single Unicode grapheme cluster but consists of multiple code points. According to this operator, it has a size of 5. However, according to Kotlin's String.substring, it has a size of 11.

Example
class Document(
    val text: String,
)

collection.aggregate()
    .set {
        Document::text set of(Document::text).substring(startIndex = of(1), length = of(2))
    }.toList()
External resources

See also

Returns the substring of a string.

The substring contains the Unicode code points that are contained within indexes.

Counting characters

This function uses MongoDB's $substrCP operator, which counts characters using Unicode code points. This differs from Kotlin's String.substring, which uses UTF-16 code units. For strings containing characters outside the Basic Multilingual Plane (like emoji or certain mathematical symbols), the indexing behavior will differ.

For example, the emoji "👨‍👩‍👧‍👦" (family) is a single Unicode grapheme cluster but consists of multiple code points. According to this operator, it has a size of 5. However, according to Kotlin's String.substring, it has a size of 11.

Example
class Document(
    val text: String,
)

collection.aggregate()
    .set {
        Document::text set of(Document::text).substring(1..2)
    }.toList()
External resources

See also

substringUTF8

open fun <Context : Any> Value<Context, String?>.substringUTF8(startIndex: Value<Context, Int>, byteCount: Value<Context, Int>): Value<Context, String?>

Returns the substring of a string.

The substring starts with the character at the specified UTF-8 byte startIndex in the string and continues for the byteCount number of bytes.

Note that this behavior is different from String.substring, which expects start and end indexes.

Counting characters

This function uses MongoDB's $substrBytes operator, which counts characters using UTF-8 encoded bytes where each code point, or character, may use between one and four bytes to encode. This differs from the substring function which uses Unicode code points.

For example, US-ASCII characters are encoded using one byte. Characters with diacritic markings and additional Latin alphabetical characters are encoded using two bytes. Chinese, Japanese and Korean characters typically require three bytes, and other planes of Unicode (emoji, mathematical symbols, etc.) require four bytes.

If startIndex or byteCount happen to be within a multibyte character, an error will be thrown.

Example
class Document(
    val text: String,
)

collection.aggregate()
    .set {
        Document::text set of(Document::text).substringUTF8(startIndex = of(1), byteCount = of(2))
    }.toList()
External resources

See also

Returns the substring of a string.

The substring contains the Unicode code points that are contained within indexes.

Counting characters

This function uses MongoDB's $substrBytes operator, which counts characters using UTF-8 encoded bytes where each code point, or character, may use between one and four bytes to encode. This differs from the substring function which uses Unicode code points.

For example, US-ASCII characters are encoded using one byte. Characters with diacritic markings and additional Latin alphabetical characters are encoded using two bytes. Chinese, Japanese and Korean characters typically require three bytes, and other planes of Unicode (emoji, mathematical symbols, etc.) require four bytes.

If the start or end index happens to be within a multibyte character, an error will be thrown.

Example
class Document(
    val text: String,
)

collection.aggregate()
    .set {
        Document::text set of(Document::text).substringUTF8(1..2)
    }.toList()
External resources

See also

trim

Removes whitespace characters, including null, or the specified characters from the beginning and end of a string.

By default, removes whitespace characters including the null character.

Example
class Document(
    val text: String,
)

collection.aggregate()
    .set {
        Document::text set of(Document::text).trim()
    }.toList()
External resources
open fun <Context : Any> Value<Context, String?>.trim(vararg characters: Char): Value<Context, String?>

Removes the specified characters from the beginning and end of a string.

Example
class Document(
    val text: String,
)

// Trim both 'g' and 'e' characters from the beginning and end
collection.aggregate()
    .set {
        Document::text set of(Document::text).trim('g', 'e')
    }.toList()

// Trim space, 'g', and 'e' characters from the beginning and end
collection.aggregate()
    .set {
        Document::text set of(Document::text).trim(' ', 'g', 'e')
    }.toList()
External resources
open fun <Context : Any> Value<Context, String?>.trim(characters: Value<Context, String?>): Value<Context, String?>

Removes the specified characters from the beginning and end of a string.

The characters parameter is a single string that can contain multiple characters to be trimmed. Each character in the string will be removed from both the beginning and end of the input string.

Example
class Document(
    val text: String,
)

// Trim both 'g' and 'e' characters from the beginning and end
collection.aggregate()
    .set {
        Document::text set of(Document::text).trim(chars = of("ge"))
    }.toList()

// Trim space, 'g', and 'e' characters from the beginning and end
collection.aggregate()
    .set {
        Document::text set of(Document::text).trim(chars = of(" ge"))
    }.toList()
External resources

trimEnd

Removes whitespace characters, including null, or the specified characters from the end of a string.

By default, removes whitespace characters including the null character.

Example
class Document(
    val text: String,
)

collection.aggregate()
    .set {
        Document::text set of(Document::text).trimEnd()
    }.toList()
External resources
open fun <Context : Any> Value<Context, String?>.trimEnd(vararg characters: Char): Value<Context, String?>

Removes the specified characters from the end of a string.

Example
class Document(
    val text: String,
)

// Trim both 'g' and 'e' characters from the end
collection.aggregate()
    .set {
        Document::text set of(Document::text).trimEnd('g', 'e')
    }.toList()

// Trim space, 'g', and 'e' characters from the end
collection.aggregate()
    .set {
        Document::text set of(Document::text).trimEnd(' ', 'g', 'e')
    }.toList()
External resources
open fun <Context : Any> Value<Context, String?>.trimEnd(characters: Value<Context, String?>): Value<Context, String?>

Removes the specified characters from the end of a string.

The characters parameter is a single string that can contain multiple characters to be trimmed. Each character in the string will be removed from the end of the input string.

Example
class Document(
    val text: String,
)

// Trim both 'g' and 'e' characters from the end
collection.aggregate()
    .set {
        Document::text set of(Document::text).trimEnd(characters = of("ge"))
    }.toList()

// Trim space, 'g', and 'e' characters from the end
collection.aggregate()
    .set {
        Document::text set of(Document::text).trimEnd(characters = of(" ge"))
    }.toList()
External resources

trimStart

Removes whitespace characters, including null, or the specified characters from the beginning of a string.

By default, removes whitespace characters including the null character.

Example
class Document(
    val text: String,
)

collection.aggregate()
    .set {
        Document::text set of(Document::text).trimStart()
    }.toList()
External resources
open fun <Context : Any> Value<Context, String?>.trimStart(vararg characters: Char): Value<Context, String?>

Removes the specified characters from the beginning of a string.

Example
class Document(
    val text: String,
)

// Trim both 'g' and 'e' characters from the beginning
collection.aggregate()
    .set {
        Document::text set of(Document::text).trimStart('g', 'e')
    }.toList()

// Trim space, 'g', and 'e' characters from the beginning
collection.aggregate()
    .set {
        Document::text set of(Document::text).trimStart(' ', 'g', 'e')
    }.toList()
External resources
open fun <Context : Any> Value<Context, String?>.trimStart(characters: Value<Context, String?>): Value<Context, String?>

Removes the specified characters from the beginning of a string.

The characters parameter is a single string that can contain multiple characters to be trimmed. Each character in the string will be removed from the beginning of the input string.

Example
class Document(
    val text: String,
)

// Trim both 'g' and 'e' characters from the beginning
collection.aggregate()
    .set {
        Document::text set of(Document::text).trimStart(characters = of("ge"))
    }.toList()

// Trim space, 'g', and 'e' characters from the beginning
collection.aggregate()
    .set {
        Document::text set of(Document::text).trimStart(characters = of(" ge"))
    }.toList()
External resources

unsafe

open infix fun <Root, Child> KProperty1<Root, *>.unsafe(child: String): Field<Root, Child>

Refers to a field child of the current field, with no compile-time safety.

open infix fun <Root, Child> KProperty1<Root, *>.unsafe(child: KProperty1<*, Child>): Field<Root, Child>

Refers to a field child of the current field, without checking that it is a field available on the current object.

open infix fun <Root, Child> KProperty1<Root, *>.unsafe(child: Field<*, Child>): Field<Root, Child>

Refers to a field child of the current field, without checking that it is a field available on the current object.

open infix fun <Root, Child> Field<Root, *>.unsafe(child: KProperty1<*, Child>): Field<Root, Child>

Refers to a field child of the current field, without checking that it is a field available on the current object.

open infix fun <Root, Child> Field<Root, *>.unsafe(child: Field<*, Child>): Field<Root, Child>

Refers to a field child of the current field, without checking that it is a field available on the current object.

open infix fun <Root, Type, Child> Field<Root, Type>.unsafe(child: String): Field<Root, Child>

Refers to a field child of the current field, with no compile-time safety.

uppercase

Converts a string to uppercase, returning the result.

If the argument resolves to null, $toUpper returns an empty string "".

Example
class Document(
    val text: String,
)

collection.aggregate()
    .set {
        Document::text set of(Document::text).uppercase()
    }.toList()
External resources