# androidx.datastore.preferences

*** ** * ** ***

## Top-level functions summary

|---|---|
| `https://developer.android.com/reference/kotlin/androidx/datastore/migrations/SharedPreferencesMigration<https://developer.android.com/reference/kotlin/androidx/datastore/preferences/core/Preferences>` | `https://developer.android.com/reference/kotlin/androidx/datastore/preferences/package-summary#SharedPreferencesMigration(kotlin.Function0,kotlin.collections.Set)( produceSharedPreferences: () -> https://developer.android.com/reference/android/content/SharedPreferences.html, keysToMigrate: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin.collections/-set/index.html<https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html> )` Creates a SharedPreferencesMigration for DataStore . <br /> |
| `https://developer.android.com/reference/kotlin/androidx/datastore/migrations/SharedPreferencesMigration<https://developer.android.com/reference/kotlin/androidx/datastore/preferences/core/Preferences>` | `https://developer.android.com/reference/kotlin/androidx/datastore/preferences/package-summary#SharedPreferencesMigration(android.content.Context,kotlin.String,kotlin.collections.Set)( context: https://developer.android.com/reference/android/content/Context.html, sharedPreferencesName: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html, keysToMigrate: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin.collections/-set/index.html<https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html> )` Creates a SharedPreferencesMigration for DataStore . |
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin.properties/-read-only-property/index.html<https://developer.android.com/reference/android/content/Context.html, https://developer.android.com/reference/kotlin/androidx/datastore/core/DataStore<https://developer.android.com/reference/kotlin/androidx/datastore/preferences/core/Preferences>>` | `https://developer.android.com/reference/kotlin/androidx/datastore/preferences/package-summary#preferencesDataStore(kotlin.String,androidx.datastore.core.handlers.ReplaceFileCorruptionHandler,kotlin.Function1,kotlinx.coroutines.CoroutineScope)( name: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html, corruptionHandler: https://developer.android.com/reference/kotlin/androidx/datastore/core/handlers/ReplaceFileCorruptionHandler<https://developer.android.com/reference/kotlin/androidx/datastore/preferences/core/Preferences>?, produceMigrations: (https://developer.android.com/reference/android/content/Context.html) -> https://kotlinlang.org/api/core/kotlin-stdlib/kotlin.collections/-list/index.html<https://developer.android.com/reference/kotlin/androidx/datastore/core/DataMigration<https://developer.android.com/reference/kotlin/androidx/datastore/preferences/core/Preferences>>, scope: https://kotlinlang.org/api/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/-coroutine-scope/index.html )` Creates a property delegate for a single process DataStore. |

## Extension functions summary

|---|---|
| `https://developer.android.com/reference/java/io/File.html` | `https://developer.android.com/reference/android/content/Context.html.https://developer.android.com/reference/kotlin/androidx/datastore/preferences/package-summary#(android.content.Context).preferencesDataStoreFile(kotlin.String)(name: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html)` Generate the File object for Preferences DataStore based on the provided context and name. |

## Top-level functions

### SharedPreferencesMigration

Artifact: [androidx.datastore:datastore-preferences](https://developer.android.com/jetpack/androidx/releases/datastore) [View Source](https://cs.android.com/search?q=file:androidx/datastore/preferences/SharedPreferencesMigration.android.kt+function:SharedPreferencesMigration)

```
fun SharedPreferencesMigration(
    produceSharedPreferences: () -> SharedPreferences,
    keysToMigrate: Set<String> = MIGRATE_ALL_KEYS
): SharedPreferencesMigration<Preferences>
```

Creates a SharedPreferencesMigration for DataStore
.

<br />

Note: This migration only supports the basic SharedPreferences types: boolean, float, int, long, string and string set. If the result of getAll contains other types, they will be ignored.

| Parameters |
|---|---|
| `produceSharedPreferences: () -> https://developer.android.com/reference/android/content/SharedPreferences.html` | Should return the instance of SharedPreferences to migrate from. |
| `keysToMigrate: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin.collections/-set/index.html<https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html> = MIGRATE_ALL_KEYS` | The list of keys to migrate. The keys will be mapped to datastore.Preferences with their same values. If the key is already present in the new Preferences, the key will not be migrated again. If the key is not present in the SharedPreferences it will not be migrated. If keysToMigrate is not set, all keys will be migrated from the existing SharedPreferences. |

### SharedPreferencesMigration

Artifact: [androidx.datastore:datastore-preferences](https://developer.android.com/jetpack/androidx/releases/datastore) [View Source](https://cs.android.com/search?q=file:androidx/datastore/preferences/SharedPreferencesMigration.android.kt+function:SharedPreferencesMigration) Added in [1.0.0](https://developer.android.com/jetpack/androidx/releases/datastore#1.0.0)

```
fun SharedPreferencesMigration(
    context: Context,
    sharedPreferencesName: String,
    keysToMigrate: Set<String> = MIGRATE_ALL_KEYS
): SharedPreferencesMigration<Preferences>
```

Creates a SharedPreferencesMigration for DataStore
.

<br />

If the SharedPreferences is empty once the migration completes, this migration will attempt to delete it.

| Parameters |
|---|---|
| `context: https://developer.android.com/reference/android/content/Context.html` | Context used for getting SharedPreferences. |
| `sharedPreferencesName: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html` | The name of the SharedPreferences. |
| `keysToMigrate: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin.collections/-set/index.html<https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html> = MIGRATE_ALL_KEYS` | The list of keys to migrate. The keys will be mapped to datastore.Preferences with their same values. If the key is already present in the new Preferences, the key will not be migrated again. If the key is not present in the SharedPreferences it will not be migrated. If keysToMigrate is not set, all keys will be migrated from the existing SharedPreferences. |

### preferencesDataStore

Artifact: [androidx.datastore:datastore-preferences](https://developer.android.com/jetpack/androidx/releases/datastore) [View Source](https://cs.android.com/search?q=file:androidx/datastore/preferences/PreferenceDataStoreDelegate.android.kt+function:preferencesDataStore)

```
fun preferencesDataStore(
    name: String,
    corruptionHandler: ReplaceFileCorruptionHandler<Preferences>? = null,
    produceMigrations: (Context) -> List<DataMigration<Preferences>> = { listOf() },
    scope: CoroutineScope = CoroutineScope(Dispatchers.IO + SupervisorJob())
): ReadOnlyProperty<Context, DataStore<Preferences>>
```

Creates a property delegate for a single process DataStore. This should only be called once in a file (at the top level), and all usages of the DataStore should use a reference the same Instance. The receiver type for the property delegate must be an instance of `https://developer.android.com/reference/android/content/Context.html`.

This should only be used from a single application in a single classloader in a single process.

Example usage:

```kotlin
val Context.myDataStore by preferencesDataStore("filename")

class SomeClass(val context: Context) {
   suspend fun update() = context.myDataStore.edit {...}
}
```

| Parameters |
|---|---|
| `name: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html` | The name of the preferences. The preferences will be stored in a file in the "datastore/" subdirectory in the application context's files directory and is generated using `https://developer.android.com/reference/kotlin/androidx/datastore/preferences/package-summary#(android.content.Context).preferencesDataStoreFile(kotlin.String)`. |
| `corruptionHandler: https://developer.android.com/reference/kotlin/androidx/datastore/core/handlers/ReplaceFileCorruptionHandler<https://developer.android.com/reference/kotlin/androidx/datastore/preferences/core/Preferences>? = null` | The corruptionHandler is invoked if DataStore encounters a `https://developer.android.com/reference/kotlin/androidx/datastore/core/CorruptionException` when attempting to read data. CorruptionExceptions are thrown by serializers when data can not be de-serialized. |
| `produceMigrations: (https://developer.android.com/reference/android/content/Context.html) -> https://kotlinlang.org/api/core/kotlin-stdlib/kotlin.collections/-list/index.html<https://developer.android.com/reference/kotlin/androidx/datastore/core/DataMigration<https://developer.android.com/reference/kotlin/androidx/datastore/preferences/core/Preferences>> = { listOf() }` | produce the migrations. The ApplicationContext is passed in to these callbacks as a parameter. DataMigrations are run before any access to data can occur. Each producer and migration may be run more than once whether or not it already succeeded (potentially because another migration failed or a write to disk failed.) |
| `scope: https://kotlinlang.org/api/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/-coroutine-scope/index.html = CoroutineScope(Dispatchers.IO + SupervisorJob())` | The scope in which IO operations and transform functions will execute. |

| Returns |
|---|---|
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin.properties/-read-only-property/index.html<https://developer.android.com/reference/android/content/Context.html, https://developer.android.com/reference/kotlin/androidx/datastore/core/DataStore<https://developer.android.com/reference/kotlin/androidx/datastore/preferences/core/Preferences>>` | a property delegate that manages a datastore as a singleton. |

## Extension functions

### Context.preferencesDataStoreFile

Artifact: [androidx.datastore:datastore-preferences](https://developer.android.com/jetpack/androidx/releases/datastore) [View Source](https://cs.android.com/search?q=file:androidx/datastore/preferences/PreferenceDataStoreFile.android.kt+function:preferencesDataStoreFile) Added in [1.0.0](https://developer.android.com/jetpack/androidx/releases/datastore#1.0.0)

```
fun Context.preferencesDataStoreFile(name: String): File
```

Generate the File object for Preferences DataStore based on the provided context and name. The file is in the `https://developer.android.com/reference/android/content/Context.html#filesDir` of `https://developer.android.com/reference/android/content/Context.html#applicationContext` for `this` + "datastore/" subdirectory with `https://developer.android.com/reference/kotlin/androidx/datastore/preferences/package-summary#(android.content.Context).preferencesDataStoreFile(kotlin.String)`. This is public to allow for testing and backwards compatibility (e.g. if moving from the `preferencesDataStore` delegate or context.createDataStore to PreferencesDataStoreFactory).

Do NOT use the file outside of DataStore.

the context of the application used to get the files directory

the name of the preferences