# 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)

*** ** * ** ***


```
public abstract class Preferences
```

<br />

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

|---|---|
| `https://developer.android.com/reference/androidx/datastore/preferences/core/MutablePreferences` | Mutable version of `https://developer.android.com/reference/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/androidx/datastore/preferences/core/PreferenceDataStoreFactory#create(androidx.datastore.core.Storage,androidx.datastore.core.handlers.ReplaceFileCorruptionHandler,kotlin.collections.List,kotlinx.coroutines.CoroutineScope)`.

## Summary

| ### Nested types |
|---|
| `public final class https://developer.android.com/reference/androidx/datastore/preferences/core/Preferences.Key<T extends https://developer.android.com/reference/java/lang/Object.html>` Key for values stored in Preferences. |
| `public final class https://developer.android.com/reference/androidx/datastore/preferences/core/Preferences.Pair<T extends https://developer.android.com/reference/java/lang/Object.html>` Key Value pairs for Preferences. |

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

## Public methods

### asMap

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

```
public abstract @NonNull Map<@NonNull Preferences.Key<@NonNull ?>, @NonNull Object> asMap()
```

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

| Returns |
|---|---|
| `@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/java/util/Map.html<@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/datastore/preferences/core/Preferences.Key<@https://developer.android.com/reference/androidx/annotation/NonNull ?>, @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/java/lang/Object.html>` | a map containing all the preferences in this Preferences |

### contains

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

```
public abstract boolean <T extends Object> contains(@NonNull Preferences.Key<@NonNull T> key)
```

Returns true if this Preferences contains the specified key.

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

### copy

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

```
public final @NonNull Preferences copy(@NonNull Function1<@NonNull MutablePreferences, Unit> block)
```

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

The `https://developer.android.com/reference/androidx/datastore/preferences/core/Preferences#copy(kotlin.Function1)` runs on a `https://developer.android.com/reference/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:

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

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

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

### get

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

```
public abstract T <T extends Object> get(@NonNull Preferences.Key<@NonNull T> key)
```

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/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 extends https://developer.android.com/reference/java/lang/Object.html>` | the type of the preference |
| `@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/datastore/preferences/core/Preferences.Key<@https://developer.android.com/reference/androidx/annotation/NonNull T> key` | 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/androidx/datastore/preferences/core/Preferences#get(androidx.datastore.preferences.core.Preferences.Key)` but it cannot be cast to T |

### toMutablePreferences

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

```
public final @NonNull MutablePreferences toMutablePreferences()
```

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/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/androidx/annotation/NonNull https://developer.android.com/reference/androidx/datastore/preferences/core/MutablePreferences` | a MutablePreferences with all the preferences from this Preferences |

### toPreferences

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

```
public final @NonNull Preferences toPreferences()
```

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/androidx/annotation/NonNull https://developer.android.com/reference/androidx/datastore/preferences/core/Preferences` | a copy of this Preferences |