PreferencesKt

Added in 1.0.0

public final class PreferencesKt


Summary

Public methods

static final @NonNull Preferences
edit(
    @NonNull DataStore<@NonNull Preferences> receiver,
    @NonNull SuspendFunction1<@NonNull MutablePreferencesUnit> transform
)

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

Public methods

public static final @NonNull Preferences edit(
    @NonNull DataStore<@NonNull Preferences> receiver,
    @NonNull SuspendFunction1<@NonNull MutablePreferencesUnit> transform
)

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
@NonNull SuspendFunction1<@NonNull MutablePreferencesUnit> transform

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