# androidx.datastore.preferences.core

*** ** * ** ***

Common/AllAndroid/JVMNative/C/iOSJavaScript

## Classes

|---|---|---|
| `https://developer.android.com/reference/kotlin/androidx/datastore/preferences/core/MutablePreferences` | Mutable version of `https://developer.android.com/reference/kotlin/androidx/datastore/preferences/core/Preferences`. | Cmn |
| `https://developer.android.com/reference/kotlin/androidx/datastore/preferences/core/Preferences` | Preferences and MutablePreferences are a lot like a generic Map and MutableMap keyed by the Preferences.Key class. | Cmn |
| `https://developer.android.com/reference/kotlin/androidx/datastore/preferences/core/Preferences.Key` | Key for values stored in Preferences. | Cmn |
| `https://developer.android.com/reference/kotlin/androidx/datastore/preferences/core/Preferences.Pair` | Key Value pairs for Preferences. | Cmn |

## Objects

|---|---|---|
| `https://developer.android.com/reference/kotlin/androidx/datastore/preferences/core/PreferenceDataStoreFactory` |   | Cmn android N JS |
| `https://developer.android.com/reference/kotlin/androidx/datastore/preferences/core/PreferencesFileSerializer` | Proto based serializer for Preferences. | android |
| `https://developer.android.com/reference/kotlin/androidx/datastore/preferences/core/PreferencesSerializer` | Proto based serializer for Preferences. | Cmn android N JS |

## Top-level functions summary

|---|---|---|
| `https://developer.android.com/reference/kotlin/androidx/datastore/preferences/core/Preferences.Key<https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-boolean/index.html>` | `https://developer.android.com/reference/kotlin/androidx/datastore/preferences/core/package-summary#booleanPreferencesKey(kotlin.String)(name: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html)` Get a key for a Boolean preference. | Cmn |
| `https://developer.android.com/reference/kotlin/androidx/datastore/preferences/core/Preferences.Key<https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-byte-array/index.html>` | `https://developer.android.com/reference/kotlin/androidx/datastore/preferences/core/package-summary#byteArrayPreferencesKey(kotlin.String)(name: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html)` Get a key for a ByteArray preference. | Cmn |
| `https://developer.android.com/reference/kotlin/androidx/datastore/preferences/core/Preferences.Key<https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-double/index.html>` | `https://developer.android.com/reference/kotlin/androidx/datastore/preferences/core/package-summary#doublePreferencesKey(kotlin.String)(name: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html)` Get a key for a Double preference. | Cmn |
| `https://developer.android.com/reference/kotlin/androidx/datastore/preferences/core/Preferences` | `https://developer.android.com/reference/kotlin/androidx/datastore/preferences/core/package-summary#emptyPreferences()()` Get a new empty Preferences. | Cmn |
| `https://developer.android.com/reference/kotlin/androidx/datastore/preferences/core/Preferences.Key<https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-float/index.html>` | `https://developer.android.com/reference/kotlin/androidx/datastore/preferences/core/package-summary#floatPreferencesKey(kotlin.String)(name: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html)` Get a key for a Float preference. | Cmn |
| `https://developer.android.com/reference/kotlin/androidx/datastore/preferences/core/Preferences.Key<https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-int/index.html>` | `https://developer.android.com/reference/kotlin/androidx/datastore/preferences/core/package-summary#intPreferencesKey(kotlin.String)(name: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html)` Get a key for an Int preference. | Cmn |
| `https://developer.android.com/reference/kotlin/androidx/datastore/preferences/core/Preferences.Key<https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-long/index.html>` | `https://developer.android.com/reference/kotlin/androidx/datastore/preferences/core/package-summary#longPreferencesKey(kotlin.String)(name: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html)` Get a key for a Long preference. | Cmn |
| `https://developer.android.com/reference/kotlin/androidx/datastore/preferences/core/MutablePreferences` | `https://developer.android.com/reference/kotlin/androidx/datastore/preferences/core/package-summary#mutablePreferencesOf(kotlin.Array)(vararg pairs: https://developer.android.com/reference/kotlin/androidx/datastore/preferences/core/Preferences.Pair<*>)` Construct a MutablePreferences object with a list of Preferences.Pair. | Cmn |
| `https://developer.android.com/reference/kotlin/androidx/datastore/preferences/core/Preferences` | `https://developer.android.com/reference/kotlin/androidx/datastore/preferences/core/package-summary#preferencesOf(kotlin.Array)(vararg pairs: https://developer.android.com/reference/kotlin/androidx/datastore/preferences/core/Preferences.Pair<*>)` Construct a Preferences object with a list of Preferences.Pair. | Cmn |
| `https://developer.android.com/reference/kotlin/androidx/datastore/preferences/core/Preferences.Key<https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html>` | `https://developer.android.com/reference/kotlin/androidx/datastore/preferences/core/package-summary#stringPreferencesKey(kotlin.String)(name: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html)` Get a key for a String preference. | Cmn |
| `https://developer.android.com/reference/kotlin/androidx/datastore/preferences/core/Preferences.Key<https://kotlinlang.org/api/core/kotlin-stdlib/kotlin.collections/-set/index.html<https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html>>` | `https://developer.android.com/reference/kotlin/androidx/datastore/preferences/core/package-summary#stringSetPreferencesKey(kotlin.String)(name: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html)` Get a key for a String Set preference. | Cmn |

## Extension functions summary

|---|---|---|
| `suspend https://developer.android.com/reference/kotlin/androidx/datastore/preferences/core/Preferences` | `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/core/package-summary#(androidx.datastore.core.DataStore).edit(kotlin.coroutines.SuspendFunction1)( transform: suspend (https://developer.android.com/reference/kotlin/androidx/datastore/preferences/core/MutablePreferences) -> https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html )` Edit the value in DataStore transactionally in an atomic read-modify-write operation. | Cmn |

## Top-level functions

### booleanPreferencesKey

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

```
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: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html` | the name of the preference |

| Returns |
|---|---|
| `https://developer.android.com/reference/kotlin/androidx/datastore/preferences/core/Preferences.Key<https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-boolean/index.html>` | the Preferences.Key for `https://developer.android.com/reference/kotlin/androidx/datastore/preferences/core/package-summary#booleanPreferencesKey(kotlin.String)` |

### byteArrayPreferencesKey

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

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

Get a key for a 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: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html` | the name of the preference |

| Returns |
|---|---|
| `https://developer.android.com/reference/kotlin/androidx/datastore/preferences/core/Preferences.Key<https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-byte-array/index.html>` | the Preferences.Key for `https://developer.android.com/reference/kotlin/androidx/datastore/preferences/core/package-summary#byteArrayPreferencesKey(kotlin.String)` |

### doublePreferencesKey

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

```
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: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html` | the name of the preference |

| Returns |
|---|---|
| `https://developer.android.com/reference/kotlin/androidx/datastore/preferences/core/Preferences.Key<https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-double/index.html>` | the Preferences.Key for `https://developer.android.com/reference/kotlin/androidx/datastore/preferences/core/package-summary#doublePreferencesKey(kotlin.String)` |

### emptyPreferences

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

```
fun emptyPreferences(): Preferences
```

Get a new empty Preferences.

| Returns |
|---|---|
| `https://developer.android.com/reference/kotlin/androidx/datastore/preferences/core/Preferences` | a new Preferences instance with no preferences set |

### floatPreferencesKey

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

```
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: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html` | the name of the preference |

| Returns |
|---|---|
| `https://developer.android.com/reference/kotlin/androidx/datastore/preferences/core/Preferences.Key<https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-float/index.html>` | the Preferences.Key for `https://developer.android.com/reference/kotlin/androidx/datastore/preferences/core/package-summary#floatPreferencesKey(kotlin.String)` |

### intPreferencesKey

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

```
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: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html` | the name of the preference |

| Returns |
|---|---|
| `https://developer.android.com/reference/kotlin/androidx/datastore/preferences/core/Preferences.Key<https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-int/index.html>` | the Preferences.Key for `https://developer.android.com/reference/kotlin/androidx/datastore/preferences/core/package-summary#intPreferencesKey(kotlin.String)` |

### longPreferencesKey

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

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

Get a key for a 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: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html` | the name of the preference |

| Returns |
|---|---|
| `https://developer.android.com/reference/kotlin/androidx/datastore/preferences/core/Preferences.Key<https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-long/index.html>` | the Preferences.Key for `https://developer.android.com/reference/kotlin/androidx/datastore/preferences/core/package-summary#longPreferencesKey(kotlin.String)` |

### mutablePreferencesOf

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

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

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

Example usage:

```kotlin
val counterKey = intPreferencesKey("counter")
val preferences = mutablePreferencesOf(counterKey to 100)
```

| Parameters |
|---|---|
| `vararg pairs: https://developer.android.com/reference/kotlin/androidx/datastore/preferences/core/Preferences.Pair<*>` | the key value pairs with which to construct the preferences |

### preferencesOf

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

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

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

Example usage:

```kotlin
val counterKey = intPreferencesKey("counter")
val preferences = preferencesOf(counterKey to 100)
```

| Parameters |
|---|---|
| `vararg pairs: https://developer.android.com/reference/kotlin/androidx/datastore/preferences/core/Preferences.Pair<*>` | the key value pairs with which to construct the preferences |

### stringPreferencesKey

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

```
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: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html` | the name of the preference |

| Returns |
|---|---|
| `https://developer.android.com/reference/kotlin/androidx/datastore/preferences/core/Preferences.Key<https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html>` | the Preferences.Key for `https://developer.android.com/reference/kotlin/androidx/datastore/preferences/core/package-summary#stringPreferencesKey(kotlin.String)` |

### stringSetPreferencesKey

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

```
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: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html` | the name of the preference |

| Returns |
|---|---|
| `https://developer.android.com/reference/kotlin/androidx/datastore/preferences/core/Preferences.Key<https://kotlinlang.org/api/core/kotlin-stdlib/kotlin.collections/-set/index.html<https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html>>` | the Preferences.Key\> for `https://developer.android.com/reference/kotlin/androidx/datastore/preferences/core/package-summary#stringSetPreferencesKey(kotlin.String)` |

## Extension functions

### DataStore.edit

Cmn Artifact: [androidx.datastore:datastore-preferences-core](https://developer.android.com/jetpack/androidx/releases/datastore) [View Source](https://cs.android.com/search?q=file:androidx/datastore/preferences/core/Preferences.kt+function: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 `https://developer.android.com/reference/kotlin/androidx/datastore/core/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 `https://developer.android.com/reference/kotlin/androidx/datastore/preferences/core/package-summary#(androidx.datastore.core.DataStore).edit(kotlin.coroutines.SuspendFunction1)` 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 `https://developer.android.com/reference/kotlin/androidx/datastore/preferences/core/package-summary#(androidx.datastore.core.DataStore).edit(kotlin.coroutines.SuspendFunction1)` returns will NOT change the data in DataStore. Future versions of this may throw exceptions if the MutablePreferences object is mutated outside of `https://developer.android.com/reference/kotlin/androidx/datastore/preferences/core/package-summary#(androidx.datastore.core.DataStore).edit(kotlin.coroutines.SuspendFunction1)`.

See `https://developer.android.com/reference/kotlin/androidx/datastore/core/DataStore#updateData(kotlin.coroutines.SuspendFunction1)`.

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

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

| Parameters |
|---|---|
| `transform: suspend (https://developer.android.com/reference/kotlin/androidx/datastore/preferences/core/MutablePreferences) -> https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html` | block which accepts MutablePreferences that contains all the preferences currently in DataStore. Changes to this MutablePreferences object will be persisted once transform completes. |

| Throws |
|---|---|
| `https://developer.android.com/reference/kotlin/androidx/datastore/core/IOException` | when an exception is encountered when writing data to disk |
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-exception/index.html` | when thrown by the transform block |