androidx.datastore.preferences.core


Classes

MutablePreferences

Mutable version of Preferences.

Cmn
Preferences

Preferences and MutablePreferences are a lot like a generic Map and MutableMap keyed by the Preferences.Key class.

Cmn
Preferences.Key

Key for values stored in Preferences.

Cmn
Preferences.Pair

Key Value pairs for Preferences.

Cmn

Objects

PreferenceDataStoreFactory
Cmn
android
N
PreferencesSerializer

Proto based serializer for Preferences.

Cmn
android
N

Top-level functions summary

Preferences.Key<Boolean>

Get a key for a Boolean preference.

Cmn
Preferences.Key<ByteArray>

Get a key for an ByteArray preference.

Cmn
Preferences.Key<Double>

Get a key for a Double preference.

Cmn
Preferences

Get a new empty Preferences.

Cmn
Preferences.Key<Float>

Get a key for a Float preference.

Cmn
Preferences.Key<Int>

Get a key for an Int preference.

Cmn
Preferences.Key<Long>

Get a key for an Long preference.

Cmn
MutablePreferences

Construct a MutablePreferences object with a list of Preferences.Pair.

Cmn
Preferences
preferencesOf(vararg pairs: Preferences.Pair<*>)

Construct a Preferences object with a list of Preferences.Pair.

Cmn
Preferences.Key<String>

Get a key for a String preference.

Cmn
Preferences.Key<Set<String>>

Get a key for a String Set preference.

Cmn

Extension functions summary

suspend Preferences
DataStore<Preferences>.edit(
    transform: suspend (MutablePreferences) -> Unit
)

Edit the value in DataStore transactionally in an atomic read-modify-write operation.

Cmn

Top-level functions

booleanPreferencesKey

fun booleanPreferencesKey(name: String): Preferences.Key<Boolean>

Get a key for a Boolean preference. You should not have multiple keys with the same name (for use with the same Preferences). Using overlapping keys with different types can result in ClassCastException.

Parameters
name: String

the name of the preference

Returns
Preferences.Key<Boolean>

the Preferences.Key for name

byteArrayPreferencesKey

fun byteArrayPreferencesKey(name: String): Preferences.Key<ByteArray>

Get a key for an ByteArray preference. You should not have multiple keys with the same name (for use with the same Preferences). Using overlapping keys with different types can result in ClassCastException.

Note: ByteArrays returned by DataStore are copies. Mutating their state will do nothing to the underlying data store. They must be set explicitly.

Parameters
name: String

the name of the preference

Returns
Preferences.Key<ByteArray>

the Preferences.Key for name

doublePreferencesKey

fun doublePreferencesKey(name: String): Preferences.Key<Double>

Get a key for a Double preference. You should not have multiple keys with the same name (for use with the same Preferences). Using overlapping keys with different types can result in ClassCastException.

Parameters
name: String

the name of the preference

Returns
Preferences.Key<Double>

the Preferences.Key for name

emptyPreferences

fun emptyPreferences(): Preferences

Get a new empty Preferences.

Returns
Preferences

a new Preferences instance with no preferences set

floatPreferencesKey

fun floatPreferencesKey(name: String): Preferences.Key<Float>

Get a key for a Float preference. You should not have multiple keys with the same name (for use with the same Preferences). Using overlapping keys with different types can result in ClassCastException.

Parameters
name: String

the name of the preference

Returns
Preferences.Key<Float>

the Preferences.Key for name

intPreferencesKey

fun intPreferencesKey(name: String): Preferences.Key<Int>

Get a key for an Int preference. You should not have multiple keys with the same name (for use with the same Preferences). Using overlapping keys with different types can result in ClassCastException.

Parameters
name: String

the name of the preference

Returns
Preferences.Key<Int>

the Preferences.Key for name

longPreferencesKey

fun longPreferencesKey(name: String): Preferences.Key<Long>

Get a key for an Long preference. You should not have multiple keys with the same name (for use with the same Preferences). Using overlapping keys with different types can result in ClassCastException.

Parameters
name: String

the name of the preference

Returns
Preferences.Key<Long>

the Preferences.Key for name

mutablePreferencesOf

fun mutablePreferencesOf(vararg pairs: Preferences.Pair<*>): MutablePreferences

Construct a MutablePreferences object with a list of Preferences.Pair. Comparable to mapOf().

Example usage:

val counterKey = intPreferencesKey("counter")
val preferences = mutablePreferencesOf(counterKey to 100)
Parameters
vararg pairs: Preferences.Pair<*>

the key value pairs with which to construct the preferences

preferencesOf

fun preferencesOf(vararg pairs: Preferences.Pair<*>): Preferences

Construct a Preferences object with a list of Preferences.Pair. Comparable to mapOf().

Example usage:

val counterKey = intPreferencesKey("counter")
val preferences = preferencesOf(counterKey to 100)
Parameters
vararg pairs: Preferences.Pair<*>

the key value pairs with which to construct the preferences

stringPreferencesKey

fun stringPreferencesKey(name: String): Preferences.Key<String>

Get a key for a String preference. You should not have multiple keys with the same name (for use with the same Preferences). Using overlapping keys with different types can result in ClassCastException.

Parameters
name: String

the name of the preference

Returns
Preferences.Key<String>

the Preferences.Key for name

stringSetPreferencesKey

fun stringSetPreferencesKey(name: String): Preferences.Key<Set<String>>

Get a key for a String Set preference. You should not have multiple keys with the same name (for use with the same Preferences). Using overlapping keys with different types can result in ClassCastException.

Note: sets returned by DataStore are unmodifiable and will throw exceptions if mutated.

Parameters
name: String

the name of the preference

Returns
Preferences.Key<Set<String>>

the Preferences.Key> for name

Extension functions

suspend fun DataStore<Preferences>.edit(
    transform: suspend (MutablePreferences) -> Unit
): Preferences

Edit the value in DataStore transactionally in an atomic read-modify-write operation. All operations are serialized.

The coroutine completes when the data has been persisted durably to disk (after which DataStore.data will reflect the update). If the transform or write to disk fails, the transaction is aborted and an exception is thrown.

Note: values that are changed in transform are NOT updated in DataStore until after the transform completes. Do not assume that the data has been successfully persisted until after edit returns successfully.

Note: do NOT store a reference to the MutablePreferences provided to transform. Mutating this after transform returns will NOT change the data in DataStore. Future versions of this may throw exceptions if the MutablePreferences object is mutated outside of transform.

See DataStore.updateData.

Example usage: val COUNTER_KEY = intPreferencesKey("my_counter")

dataStore.edit { prefs -> prefs\[COUNTER_KEY\] = prefs\[COUNTER_KEY\] :? 0 + 1 }

Parameters
transform: suspend (MutablePreferences) -> Unit

block which accepts MutablePreferences that contains all the preferences currently in DataStore. Changes to this MutablePreferences object will be persisted once transform completes.

Throws
androidx.datastore.core.IOException

when an exception is encountered when writing data to disk

kotlin.Exception

when thrown by the transform block