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> |
booleanPreferencesKey(name: String) Get a key for a Boolean preference. |
Preferences.Key<Double> |
doublePreferencesKey(name: String) Get a key for a Double preference. |
Preferences |
Get a new empty Preferences. |
Preferences.Key<Float> |
floatPreferencesKey(name: String) Get a key for a Float preference. |
Preferences.Key<Int> |
intPreferencesKey(name: String) Get a key for an Int preference. |
Preferences.Key<Long> |
longPreferencesKey(name: String) Get a key for an Long preference. |
MutablePreferences |
mutablePreferencesOf(vararg pairs: Preferences.Pair<*>) 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> |
stringPreferencesKey(name: String) Get a key for a String preference. |
Preferences.Key<Set<String>> |
stringSetPreferencesKey(name: 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 |