kord-common/dev.kord.common.entity.optional/Optional

Optional

@Serializable(with = Optional.OptionalSerializer::class)

Represents a value that encapsulates all three possible states of a value in the Discord API. Specifically:

Missing - a field that was not present in the serialized entity
Null - a field that was assigned null in the serialized entity
Value - a field that was assigned a non-null value in the serialized entity.

The base class is (de)serializable with kotlinx.serialization and should be used as follows:

Optional<T> - a field that is only optional but not nullable.
Optional<T?> - A field that is both optional and nullable.
A field that is only nullable should be represented as T? instead.

Trying to deserialize null as Optional<T> will result in a SerializationException being thrown.

Note that kotlinx.serialization does not call serializers for values that are not present in the serialized format. Optional fields should have a default value of Optional.Missing:

@Serializable
class DiscordUser(
    val id: Long,
    val username: String,
    val bot: Optional<Boolean?> = Optional.Missing()
)

Inheritors

Missing

Null

Value

Types

Companion

object Companion

Missing

class Missing<out T> : Optional<T>

Represents a field that was not present in the serialized entity.

Null

class Null<out T> : Optional<T?>

Represents a field that was assigned null in the serialized entity.

Value

class Value<T : Any>(val value: T) : Optional<T>

Represents a field that was assigned a non-null value in the serialized entity. Equality and hashcode is implemented through its value.

Properties

value

open val value: T?

The value this optional wraps.

Functions

coerceToMissing

fun <T : Any> Optional<T?>.coerceToMissing(): Optional<T>

filterInstanceOfList

inline fun <R> Optional<List<*>>.filterInstanceOfList(): Optional<List<R>>

filterList

inline fun <E> Optional<List<E>>.filterList(mapper: (E) -> Boolean): Optional<List<E>>

first

inline fun <E> Optional<List<E>>.first(predicate: (E) -> Boolean): E

firstOrNull

inline fun <E> Optional<List<E>>.firstOrNull(predicate: (E) -> Boolean): E?

flatMap

inline fun <E : Any, T : Any> Optional<E>.flatMap(mapper: (E) -> Optional<T>): Optional<T>

Applies the mapper to the optional if it is a Value, returns the same optional otherwise.

map

@JvmName(name = "mapNullableOptional")

inline fun <E : Any, T : Any> Optional<E?>.map(mapper: (E) -> T): Optional<T?>

inline fun <E : Any, T : Any> Optional<E>.map(mapper: (E) -> T): Optional<T>

mapCopy

fun <T> Optional<MutableList<T>>.mapCopy(): Optional<List<T>>

@JvmName(name = "mapCopyOfMap")

fun <K, V> Optional<MutableMap<K, V>>.mapCopy(): Optional<Map<K, V>>

mapList

@JvmName(name = "mapNullableList")

inline fun <E, T> Optional<List<E>?>.mapList(mapper: (E) -> T): Optional<List<T>?>

inline fun <E, T> Optional<List<E>>.mapList(mapper: (E) -> T): Optional<List<T>>

mapNotNull

inline fun <E : Any, T> Optional<E?>.mapNotNull(mapper: (E) -> T): Optional<T?>

mapNullable

inline fun <E, T> Optional<E>.mapNullable(mapper: (E) -> T): Optional<T?>

mapSnowflake

@JvmName(name = "mapNullableSnowflake")

inline fun <E : Any> Optional<E?>.mapSnowflake(mapper: (E) -> Snowflake): OptionalSnowflake

inline fun <E : Any> Optional<E>.mapSnowflake(mapper: (E) -> Snowflake): OptionalSnowflake

mapValues

inline fun <K, V, R> Optional<Map<K, V>>.mapValues(mapper: (Map.Entry<K, V>) -> R): Optional<Map<K, R>>

orEmpty

fun <E> Optional<List<E>>.orEmpty(): List<E>

fun <E> Optional<Set<E>>.orEmpty(): Set<E>

switchOnMissing

fun <T : Any> Optional<T>.switchOnMissing(value: T): Optional<T>

fun <T : Any> Optional<T>.switchOnMissing(value: Optional<T>): Optional<T>

toPrimitive

fun Optional<Boolean>.toPrimitive(): OptionalBoolean

unwrap

inline fun <T, R : Any> Optional<T>.unwrap(mapper: (T) -> R): R?