Class

User​Defaults

The NSUser​Defaults class provides a programmatic interface for interacting with the defaults system. The defaults system allows an application to customize its behavior to match a user’s preferences. For example, you can allow users to determine what units of measurement your application displays or how often documents are automatically saved. Applications record such preferences by assigning values to a set of parameters in a user’s defaults database. The parameters are referred to as defaults since they’re commonly used to determine an application’s default state at startup or the way it acts by default.

Overview

At runtime, you use an NSUser​Defaults object to read the defaults that your application uses from a user’s defaults database. NSUser​Defaults caches the information to avoid having to open the user’s defaults database each time you need a default value. The synchronize() method, which is automatically invoked at periodic intervals, keeps the in-memory cache in sync with a user’s defaults database.

The NSUser​Defaults class provides convenience methods for accessing common types such as floats, doubles, integers, Booleans, and URLs. A default object must be a property list—that is, an instance of (or for collections, a combination of instances of): NSData, NSString, NSNumber, NSDate, NSArray, or NSDictionary. If you want to store any other type of object, you should typically archive it to create an instance of NSData. For more details, see Preferences and Settings Programming Guide.

Values returned from NSUser​Defaults are immutable, even if you set a mutable object as the value. For example, if you set a mutable string as the value for "My​String​Default", the string you later retrieve using string(for​Key:​) will be immutable.

A defaults database is created automatically for each user. The NSUser​Defaults class does not currently support per-host preferences. To do this, you must use the CFPreferences API (see Preferences Utilities). However, NSUser​Defaults correctly reads per-host preferences, so you can safely mix CFPreferences code with NSUser​Defaults code.

If your application supports managed environments, you can use an NSUser​Defaults object to determine which preferences are managed by an administrator for the benefit of the user. Managed environments correspond to computer labs or classrooms where an administrator or teacher may want to configure the systems in a particular way. In these situations, the teacher can establish a set of default preferences and force those preferences on users. If a preference is managed in this manner, applications should prevent users from editing that preference by disabling any appropriate controls.

You can use key-value observing to register observers for specific keys of interest in order to be notified of all updates to a local defaults database. For more details, see Key-Value Observing Programming Guide.

The NSUser​Defaults class is thread-safe.

Persistence of NSURL and file reference URLs

When using NSURL instances to refer to files within a process, it's important to make the distinction between location-based tracking (file: scheme URLs that are basically paths) versus filesystem identity tracking (file:​ scheme URLs that are file reference URLs). When persisting an NSURL, you should take that behavior into consideration. If your application tracks the resource being located by its identity so that it can be found if the user moves the file, then you should explicitly write NSURL bookmark data or encode a file reference URL.

If you want to track a file by reference but you require explicit control over when resolution occurs, you should take care to write out bookmark data to NSUser​Defaults rather than rely on set(_:​for​Key:​). This allows you to call URLBy​Resolving​Bookmark​Data:​options:​relative​To​URL:​bookmark​Data​Is​Stale:​error:​ at a time when you know your application will be able to handle the potential I/O or required user interface interactions.

Storing Preferences in iCloud

An app can use the iCloud key-value store to share small amounts of data with other instances of itself on the user’s other computers and iOS devices. For example, a magazine app might store the current issue and page number being read by the user so that other instances of the app can open to the same page when launched.

For more information, see Storing Preferences in iCloud in Preferences and Settings Programming Guide.

Sandbox Considerations

A sandboxed app cannot access or modify the preferences for any other app. (For example, if you add another app's domain using the add​Suite(named:​) method, you do not gain access to that app's preferences.)

Attempting to access or modify another app's preferences does not result in an error, but when you do, macOS actually reads and writes files located within your app's container, rather than the actual preference files for the other application.

Symbols

Getting the Shared NSUserDefaults Instance

class var standard:​ User​Defaults

Returns the shared defaults object.

class func reset​Standard​User​Defaults()

Synchronizes any changes made to the shared user defaults object and releases it from memory.

Initializing an NSUserDefaults Object

init()

Returns an NSUser​Defaults object initialized with the defaults for the current user account.

init?(suite​Name:​ String?)

Returns an NSUser​Defaults object initialized with the defaults for the specified app group.

Registering Defaults

func register(defaults:​ [String :​ Any])

Adds the contents of the specified dictionary to the registration domain.

Getting Default Values

func object(for​Key:​ String)

Returns the object associated with the first occurrence of the specified default.

func url(for​Key:​ String)

Returns the NSURL instance associated with the specified key.

func array(for​Key:​ String)

Returns the array associated with the specified key.

func dictionary(for​Key:​ String)

Returns the dictionary object associated with the specified key.

func string(for​Key:​ String)

Returns the string associated with the specified key.

func string​Array(for​Key:​ String)

Returns the array of strings associated with the specified key.

func data(for​Key:​ String)

Returns the data object associated with the specified key.

func bool(for​Key:​ String)

Returns the Boolean value associated with the specified key.

func integer(for​Key:​ String)

Returns the integer value associated with the specified key..

func float(for​Key:​ String)

Returns the floating-point value associated with the specified key.

func double(for​Key:​ String)

Returns the double value associated with the specified key.

func dictionary​Representation()

Returns a dictionary that contains a union of all key-value pairs in the domains in the search list.

Setting Default Values

func set(Any?, for​Key:​ String)

Sets the value of the specified default key in the standard application domain.

func set(URL?, for​Key:​ String)

Sets the value of the specified default key to the specified URL.

func set(Bool, for​Key:​ String)

Sets the value of the specified default key to the specified Boolean value.

func set(Int, for​Key:​ String)

Sets the value of the specified default key to the specified integer value.

func set(Float, for​Key:​ String)

Sets the value of the specified default key to the specified floating-point value.

func set(Double, for​Key:​ String)

Sets the value of the specified default key to the double value.

Removing Defaults

func remove​Object(for​Key:​ String)

Removes the value of the specified default key in the standard application domain.

Maintaining Persistent Domains

func synchronize()

Writes any modifications to the persistent domains to disk and updates all unmodified persistent domains to what is on disk.

func persistent​Domain(for​Name:​ String)

Returns a dictionary containing the keys and values in the specified persistent domain.

func remove​Persistent​Domain(for​Name:​ String)

Removes the contents of the specified persistent domain from the user’s defaults.

func set​Persistent​Domain([String :​ Any], for​Name:​ String)

Sets the dictionary for the specified persistent domain.

Accessing Managed Environment Keys

func object​Is​Forced(for​Key:​ String)

Returns a Boolean value indicating whether the specified key is managed by an administrator.

func object​Is​Forced(for​Key:​ String, in​Domain:​ String)

Returns a Boolean value indicating whether the key in the specified domain is managed by an administrator.

Maintaining Volatile Domains

func remove​Volatile​Domain(for​Name:​ String)

Removes the specified volatile domain from the user’s defaults.

func set​Volatile​Domain([String :​ Any], for​Name:​ String)

Sets the dictionary for the specified volatile domain.

func volatile​Domain(for​Name:​ String)

Returns the dictionary for the specified volatile domain.

var volatile​Domain​Names:​ [String]

The current volatile domain names.

Maintaining Suites

func add​Suite(named:​ String)

Inserts the specified domain name into the receiver’s search list.

func remove​Suite(named:​ String)

Removes the specified domain name from the receiver’s search list.

Constants

NSUser​Defaults Domains

These constants specify various user defaults domains.

Notifications

class let did​Change​Notification:​ NSNotification.Name

This notification is posted when user defaults are changed within the current process.

class let size​Limit​Exceeded​Notification:​ NSNotification.Name

This notification is posted when more data is stored in user defaults than is allowed.

class let completed​Initial​Cloud​Sync​Notification:​ NSNotification.Name

This notification is posted when ubiquitous defaults finish downloading data, either the first time a device is connected to an iCloud account or when a user switches their primary iCloud account.

class let did​Change​Cloud​Accounts​Notification:​ NSNotification.Name

This notification is posted when the user changes the primary iCloud account.

class let no​Cloud​Account​Notification:​ NSNotification.Name

This notification is posted when a cloud default is set, but no iCloud user is logged in.

Relationships

Inherits From