# Preferences

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+class:androidx.datastore.preferences.core.Preferences) Added in [1.0.0](https://developer.android.com/jetpack/androidx/releases/datastore#1.0.0)

*** ** * ** ***

Common/AllAndroid/JVMNative/C/iOSJavaScript
- Cmn

  ```
  abstract class Preferences
  ```
Known direct subclasses [MutablePreferences](https://developer.android.com/reference/kotlin/androidx/datastore/preferences/core/MutablePreferences)

|---|---|
| `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`. |

*** ** * ** ***

Preferences and MutablePreferences are a lot like a generic Map and MutableMap keyed by the Preferences.Key class. These are intended for use with DataStore. Construct a `DataStore<Preferences>` instance using `https://developer.android.com/reference/kotlin/androidx/datastore/preferences/core/PreferenceDataStoreFactory#create(androidx.datastore.core.Storage,androidx.datastore.core.handlers.ReplaceFileCorruptionHandler,kotlin.collections.List,kotlinx.coroutines.CoroutineScope)`.

## Summary

| ### Nested types |
|---|
| `class https://developer.android.com/reference/kotlin/androidx/datastore/preferences/core/Preferences.Key<T : https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-any/index.html?>` Key for values stored in Preferences. |
| `class https://developer.android.com/reference/kotlin/androidx/datastore/preferences/core/Preferences.Pair<T : https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-any/index.html?>` Key Value pairs for Preferences. |

| ### Public functions |
|---|---|---|
| `abstract https://kotlinlang.org/api/core/kotlin-stdlib/kotlin.collections/-map/index.html<https://developer.android.com/reference/kotlin/androidx/datastore/preferences/core/Preferences.Key<*>, https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-any/index.html>` | `https://developer.android.com/reference/kotlin/androidx/datastore/preferences/core/Preferences#asMap()()` Retrieve a map of all key preference pairs. | Cmn |
| `abstract operator https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-boolean/index.html` | `<T : https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-any/index.html?> https://developer.android.com/reference/kotlin/androidx/datastore/preferences/core/Preferences#contains(androidx.datastore.preferences.core.Preferences.Key)(key: https://developer.android.com/reference/kotlin/androidx/datastore/preferences/core/Preferences.Key<T>)` Returns true if this Preferences contains the specified key. | Cmn |
| `https://developer.android.com/reference/kotlin/androidx/datastore/preferences/core/Preferences` | `https://developer.android.com/reference/kotlin/androidx/datastore/preferences/core/Preferences#copy(kotlin.Function1)(block: (https://developer.android.com/reference/kotlin/androidx/datastore/preferences/core/MutablePreferences) -> https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html)` Creates a new read-only Preferences with the changes from `https://developer.android.com/reference/kotlin/androidx/datastore/preferences/core/Preferences#copy(kotlin.Function1)`. | Cmn |
| `abstract operator T?` | `<T : https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-any/index.html?> https://developer.android.com/reference/kotlin/androidx/datastore/preferences/core/Preferences#get(androidx.datastore.preferences.core.Preferences.Key)(key: https://developer.android.com/reference/kotlin/androidx/datastore/preferences/core/Preferences.Key<T>)` Get a preference with a key. | Cmn |
| `https://developer.android.com/reference/kotlin/androidx/datastore/preferences/core/MutablePreferences` | `https://developer.android.com/reference/kotlin/androidx/datastore/preferences/core/Preferences#toMutablePreferences()()` Gets a mutable copy of Preferences which contains all the preferences in this Preferences. | Cmn |
| `https://developer.android.com/reference/kotlin/androidx/datastore/preferences/core/Preferences` | `https://developer.android.com/reference/kotlin/androidx/datastore/preferences/core/Preferences#toPreferences()()` Gets a read-only copy of Preferences which contains all the preferences in this Preferences. | Cmn |

## Public functions

### asMap

Cmn Added in [1.0.0](https://developer.android.com/jetpack/androidx/releases/datastore#1.0.0)

```
abstract fun asMap(): Map<Preferences.Key<*>, Any>
```

Retrieve a map of all key preference pairs. The returned map is unmodifiable, and attempts to mutate it will throw runtime exceptions.

| Returns |
|---|---|
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin.collections/-map/index.html<https://developer.android.com/reference/kotlin/androidx/datastore/preferences/core/Preferences.Key<*>, https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-any/index.html>` | a map containing all the preferences in this Preferences |

### contains

Cmn Added in [1.0.0](https://developer.android.com/jetpack/androidx/releases/datastore#1.0.0)

```
abstract operator fun <T : Any?> contains(key: Preferences.Key<T>): Boolean
```

Returns true if this Preferences contains the specified key.

| Parameters |
|---|---|
| `key: https://developer.android.com/reference/kotlin/androidx/datastore/preferences/core/Preferences.Key<T>` | the key to check for |

### copy

Cmn Added in [1.3.0](https://developer.android.com/jetpack/androidx/releases/datastore#1.3.0)

```
fun copy(block: (MutablePreferences) -> Unit): Preferences
```

Creates a new read-only Preferences with the changes from `https://developer.android.com/reference/kotlin/androidx/datastore/preferences/core/Preferences#copy(kotlin.Function1)`.

The `https://developer.android.com/reference/kotlin/androidx/datastore/preferences/core/Preferences#copy(kotlin.Function1)` runs on a `https://developer.android.com/reference/kotlin/androidx/datastore/preferences/core/MutablePreferences` copy of this `Preferences` object, so any changes inside the block will be present in the returned `Preferences` object.

Example:

```kotlin
val newPrefs = prefs.copy { preferences ->
    preferences[COUNTER_KEY] = 1
}
```

| Parameters |
|---|---|
| `block: (https://developer.android.com/reference/kotlin/androidx/datastore/preferences/core/MutablePreferences) -> https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html` | The lambda to apply to a mutable copy of these preferences. |

| Returns |
|---|---|
| `https://developer.android.com/reference/kotlin/androidx/datastore/preferences/core/Preferences` | A new read-only `Preferences` object with the applied changes. |

### get

Cmn Added in [1.0.0](https://developer.android.com/jetpack/androidx/releases/datastore#1.0.0)

```
abstract operator fun <T : Any?> get(key: Preferences.Key<T>): T?
```

Get a preference with a key. If the key is not set, returns null.

If T is Set, this returns an unmodifiable set which will throw a runtime exception when mutated. Do not try to mutate the returned set.

Use `https://developer.android.com/reference/kotlin/androidx/datastore/preferences/core/MutablePreferences#set(androidx.datastore.preferences.core.Preferences.Key,kotlin.Any)` to change the value of a preference (inside a DataStore
.edit block).

<br />

| Parameters |
|---|---|
| `<T : https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-any/index.html?>` | the type of the preference |
| `key: https://developer.android.com/reference/kotlin/androidx/datastore/preferences/core/Preferences.Key<T>` | the key for the preference |

| Throws |
|---|---|
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-class-cast-exception/index.html` | if there is something stored with the same name as `https://developer.android.com/reference/kotlin/androidx/datastore/preferences/core/Preferences#get(androidx.datastore.preferences.core.Preferences.Key)` but it cannot be cast to T |

### toMutablePreferences

Cmn Added in [1.0.0](https://developer.android.com/jetpack/androidx/releases/datastore#1.0.0)

```
fun toMutablePreferences(): MutablePreferences
```

Gets a mutable copy of Preferences which contains all the preferences in this Preferences. This can be used to update your preferences without building a new Preferences object from scratch in `https://developer.android.com/reference/kotlin/androidx/datastore/core/DataStore#updateData(kotlin.coroutines.SuspendFunction1)`.

This is similar to `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin.collections/index.html`.

| Returns |
|---|---|
| `https://developer.android.com/reference/kotlin/androidx/datastore/preferences/core/MutablePreferences` | a MutablePreferences with all the preferences from this Preferences |

### toPreferences

Cmn Added in [1.0.0](https://developer.android.com/jetpack/androidx/releases/datastore#1.0.0)

```
fun toPreferences(): Preferences
```

Gets a read-only copy of Preferences which contains all the preferences in this Preferences.

This is similar to `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin.collections/index.html`.

| Returns |
|---|---|
| `https://developer.android.com/reference/kotlin/androidx/datastore/preferences/core/Preferences` | a copy of this Preferences |