Google is committed to advancing racial equity for Black communities. See how.

androidx.datastore.preferences.core

Classes

MutablePreferences

Mutable version of Preferences.

Preferences

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

Top-level functions summary

Preferences.Key<Boolean>

Get a key for a Boolean preference.

Preferences.Key<Double>

Get a key for a Double preference.

Preferences

Get a new empty Preferences.

Preferences.Key<Float>

Get a key for a Float preference.

Preferences.Key<Int>

Get a key for an Int preference.

Preferences.Key<Long>

Get a key for an Long preference.

MutablePreferences

Construct a MutablePreferences object with a list of Preferences.

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

Construct a Preferences object with a list of Preferences.

Preferences.Key<String>

Get a key for a String preference.

Preferences.Key<Set<String>>

Get a key for a String Set preference.

Extension functions summary

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

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

Top-level functions

booleanPreferencesKey

@JvmName("booleanKey") 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
Return
the Preferences.Key for name

doublePreferencesKey

@JvmName("doubleKey") 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
Return
the Preferences.Key for name

emptyPreferences

@JvmName("createEmpty") fun emptyPreferences(): Preferences

Get a new empty Preferences.

Return
a new Preferences instance with no preferences set

floatPreferencesKey

@JvmName("floatKey") 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
Return
the Preferences.Key for name

intPreferencesKey

@JvmName("intKey") 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
Return
the Preferences.Key for name

longPreferencesKey

@JvmName("longKey") 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
Return
the Preferences.Key for name

mutablePreferencesOf

@JvmName("createMutable") 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 = preferencesOf(counterKey to 100)

Parameters
vararg pairs: Preferences.Pair<*> the key value pairs with which to construct the preferences

preferencesOf

@JvmName("create") 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

@JvmName("stringKey") 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
Return
the Preferences.Key for name

stringSetPreferencesKey

@JvmName("stringSetKey") 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
Return
the Preferences.Key <Set> for name

Extension functions

edit

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.
Exceptions
IOException when an exception is encountered when writing data to disk
Exception when thrown by the transform block