public abstract class Preferences

Known direct subclasses
MutablePreferences

Mutable version of 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 instance using PreferenceDataStoreFactory.create.

Summary

Nested types

public final class Preferences.Key<T extends Object>

Key for values stored in Preferences.

public final class Preferences.Pair<T extends Object>

Key Value pairs for Preferences.

Public methods

abstract @NonNull Map<@NonNull Preferences.Key<@NonNull ?>, @NonNull Object>

Retrieve a map of all key preference pairs.

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

Returns true if this Preferences contains the specified key.

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

Get a preference with a key.

final @NonNull MutablePreferences

Gets a mutable copy of Preferences which contains all the preferences in this Preferences.

final @NonNull Preferences

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

Public methods

asMap

Added in 1.0.0
public abstract @NonNull Map<@NonNull Preferences.Key<@NonNull ?>, @NonNull ObjectasMap()

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

Returns
@NonNull Map<@NonNull Preferences.Key<@NonNull ?>, @NonNull Object>

a map containing all the preferences in this Preferences

contains

Added in 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
@NonNull Preferences.Key<@NonNull T> key

the key to check for

get

Added in 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 MutablePreferences.set to change the value of a preference (inside a DataStore.edit block).

Parameters
<T extends Object>

the type of the preference

@NonNull Preferences.Key<@NonNull T> key

the key for the preference

Throws
kotlin.ClassCastException

if there is something stored with the same name as key but it cannot be cast to T

toMutablePreferences

Added in 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 DataStore.updateData.

This is similar to Map.toMutableMap.

Returns
@NonNull MutablePreferences

a MutablePreferences with all the preferences from this Preferences

toPreferences

Added in 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 Map.toMap.

Returns
@NonNull Preferences

a copy of this Preferences