Mac Developer Library

Developer

Foundation Framework Reference NSUserDefaults Class Reference

Options
Deployment Target:

On This Page
Language:

NSUserDefaults

The NSUserDefaults 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.

At runtime, you use an NSUserDefaults object to read the defaults that your application uses from a user’s defaults database. NSUserDefaults 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 NSUserDefaults 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 NSUserDefaults are immutable, even if you set a mutable object as the value. For example, if you set a mutable string as the value for "MyStringDefault", the string you later retrieve using stringForKey: will be immutable.

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

If your application supports managed environments, you can use an NSUserDefaults 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.

The NSUserDefaults 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 the NSURL's 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 NSUserDefaults rather than rely on -[NSUserDefaults setURL:forKey:]. This allows you to call +[NSURL URLByResolvingBookmarkData:options:relativeToURL:bookmarkDataIsStale:error:] at a time when you know your application will be able to handle the potential I/O or required user interface interactions.

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 addSuiteNamed: 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, OS X actually reads and writes files located within your app's container, rather than the actual preference files for the other application.

Inheritance


Conforms To


Import Statement


Swift

import Foundation

Objective-C

@import Foundation;

Availability


Available in OS X v10.0 and later.
  • Returns the shared defaults object.

    Declaration

    Swift

    class func standardUserDefaults() -> NSUserDefaults

    Objective-C

    + (NSUserDefaults *)standardUserDefaults

    Return Value

    The shared defaults object.

    Discussion

    If the shared defaults object does not exist yet, it is created with a search list containing the names of the following domains, in this order:

    • NSArgumentDomain, consisting of defaults parsed from the application’s arguments

    • A domain identified by the application’s bundle identifier

    • NSGlobalDomain, consisting of defaults meant to be seen by all applications

    • Separate domains for each of the user’s preferred languages

    • NSRegistrationDomain, a set of temporary defaults whose values can be set by the application to ensure that searches will always be successful

    The defaults are initialized for the current user. Subsequent modifications to the standard search list remain in effect even when this method is invoked again—the search list is guaranteed to be standard only the first time this method is invoked.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    class func resetStandardUserDefaults()

    Objective-C

    + (void)resetStandardUserDefaults

    Discussion

    A subsequent invocation of standardUserDefaults creates a new shared user defaults object with the standard search list.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

  • Returns an NSUserDefaults object initialized with the defaults for the current user account.

    Declaration

    Swift

    convenience init()

    Objective-C

    - (instancetype)init

    Return Value

    An initialized NSUserDefaults object whose argument and registration domains are already set up.

    Discussion

    This method does not put anything in the search list. Invoke it only if you’ve allocated your own NSUserDefaults instance instead of using the shared one.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

  • Returns an NSUserDefaults object initialized with the defaults for the specified user account.

    Deprecation Statement

    This method was never implemented to return anything but the defaults for the current user. Use standardUserDefaults instead.

    Declaration

    Objective-C

    - (id)initWithUser:(NSString *)username

    Parameters

    username

    The name of the user account.

    Return Value

    An initialized NSUserDefaults object whose argument and registration domains are already set up. If the current user does not have access to the specified user account, this method returns nil.

    Discussion

    This method does not put anything in the search list. Invoke it only if you’ve allocated your own NSUserDefaults instance instead of using the shared one.

    You do not normally use this method to initialize an instance of NSUserDefaults. Applications used by a superuser might use this method to update the defaults databases for a number of users. The user who started the application must have appropriate access (read, write, or both) to the defaults database of the new user, or this method returns nil.

    Special Considerations

    This method was never implemented to do anything except return the defaults for the current user.

    Import Statement

    Objective-C

    @import Foundation;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.9.

  • init(suiteName:) - initWithSuiteName: Designated Initializer

    Returns an NSUserDefaults object initialized with the defaults for the specified app group.

    Declaration

    Swift

    init?(suiteName suitename: String)

    Objective-C

    - (instancetype)initWithSuiteName:(NSString *)suitename

    Parameters

    suitename

    The name of the app group.

    If you pass nil to this parameter, the system uses the default search list that the standardUserDefaults class method uses.

    Return Value

    An initialized NSUserDefaults object whose argument and registration domains are already set up.

    Discussion

    Use this method in scenarios such as:

    • When developing an app suite, to share preferences or other data among the apps

    • When developing an app extension, to share preferences or other data between the extension and its containing app

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.9 and later.

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

    Declaration

    Swift

    func registerDefaults(_ dictionary: [NSObject : AnyObject])

    Objective-C

    - (void)registerDefaults:(NSDictionary *)dictionary

    Parameters

    dictionary

    The dictionary of keys and values you want to register.

    Discussion

    If there is no registration domain, one is created using the specified dictionary, and NSRegistrationDomain is added to the end of the search list.

    The contents of the registration domain are not written to disk; you need to call this method each time your application starts. You can place a plist file in the application's Resources directory and call registerDefaults: with the contents that you read in from that file.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

  • Returns the array associated with the specified key.

    Declaration

    Swift

    func arrayForKey(_ defaultName: String) -> [AnyObject]?

    Objective-C

    - (NSArray *)arrayForKey:(NSString *)defaultName

    Parameters

    defaultName

    A key in the current user's defaults database.

    Return Value

    The array associated with the specified key, or nil if the key does not exist or its value is not an NSArray object.

    Special Considerations

    The returned array and its contents are immutable, even if the values you originally set were mutable.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

  • Returns the Boolean value associated with the specified key.

    Declaration

    Swift

    func boolForKey(_ defaultName: String) -> Bool

    Objective-C

    - (BOOL)boolForKey:(NSString *)defaultName

    Parameters

    defaultName

    A key in the current user's defaults database.

    Return Value

    If a boolean value is associated with defaultName in the user defaults, that value is returned. Otherwise, NOfalse is returned.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

  • Returns the data object associated with the specified key.

    Declaration

    Swift

    func dataForKey(_ defaultName: String) -> NSData?

    Objective-C

    - (NSData *)dataForKey:(NSString *)defaultName

    Parameters

    defaultName

    A key in the current user's defaults database.

    Return Value

    The data object associated with the specified key, or nil if the key does not exist or its value is not an NSData object.

    Special Considerations

    The returned data object is immutable, even if the value you originally set was a mutable data object.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

  • Returns the dictionary object associated with the specified key.

    Declaration

    Swift

    func dictionaryForKey(_ defaultName: String) -> [NSObject : AnyObject]?

    Objective-C

    - (NSDictionary *)dictionaryForKey:(NSString *)defaultName

    Parameters

    defaultName

    A key in the current user's defaults database.

    Return Value

    The dictionary object associated with the specified key, or nil if the key does not exist or its value is not an NSDictionary object.

    Special Considerations

    The returned dictionary and its contents are immutable, even if the values you originally set were mutable.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    func floatForKey(_ defaultName: String) -> Float

    Objective-C

    - (float)floatForKey:(NSString *)defaultName

    Parameters

    defaultName

    A key in the current user's defaults database.

    Return Value

    The floating-point value associated with the specified key. If the key does not exist, this method returns 0.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

  • Returns the integer value associated with the specified key..

    Declaration

    Swift

    func integerForKey(_ defaultName: String) -> Int

    Objective-C

    - (NSInteger)integerForKey:(NSString *)defaultName

    Parameters

    defaultName

    A key in the current user's defaults database.

    Return Value

    The integer value associated with the specified key. If the specified key does not exist, this method returns 0.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    func objectForKey(_ defaultName: String) -> AnyObject?

    Objective-C

    - (id)objectForKey:(NSString *)defaultName

    Parameters

    defaultName

    A key in the current user's defaults database.

    Return Value

    The object associated with the specified key, or nil if the key was not found.

    Discussion

    This method searches the domains included in the search list in the order they are listed.

    Special Considerations

    The returned object is immutable, even if the value you originally set was mutable.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

  • Returns the array of strings associated with the specified key.

    Declaration

    Swift

    func stringArrayForKey(_ defaultName: String) -> [AnyObject]?

    Objective-C

    - (NSArray *)stringArrayForKey:(NSString *)defaultName

    Parameters

    defaultName

    A key in the current user's defaults database.

    Return Value

    The array of NSString objects, or nil if the specified default does not exist, the default does not contain an array, or the array does not contain NSString objects.

    Special Considerations

    The returned array and its contents are immutable, even if the values you originally set were mutable.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

  • Returns the string associated with the specified key.

    Declaration

    Swift

    func stringForKey(_ defaultName: String) -> String?

    Objective-C

    - (NSString *)stringForKey:(NSString *)defaultName

    Parameters

    defaultName

    A key in the current user's defaults database.

    Return Value

    For string values, the string associated with the specified key. For number values, the string value of the number. Returns nil if the default does not exist or is not a string or number value.

    Special Considerations

    The returned string is immutable, even if the value you originally set was a mutable string.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

  • Returns the double value associated with the specified key.

    Declaration

    Swift

    func doubleForKey(_ defaultName: String) -> Double

    Objective-C

    - (double)doubleForKey:(NSString *)defaultName

    Parameters

    defaultName

    A key in the current user's defaults database.

    Return Value

    The double value associated with the specified key. If the key does not exist, this method returns 0.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.5 and later.

  • Returns the NSURL instance associated with the specified key.

    Declaration

    Swift

    func URLForKey(_ defaultName: String) -> NSURL?

    Objective-C

    - (NSURL *)URLForKey:(NSString *)defaultName

    Parameters

    defaultName

    A key in the current user's defaults database.

    Return Value

    The NSURL instance value associated with the specified key. If the key does not exist, this method returns nil.

    Discussion

    When an NSURL is read using -[NSUserDefaults URLForKey:], the following logic is used:

    1. If the value for the key is an NSData, the NSData is used as the argument to +[NSKeyedUnarchiver unarchiveObjectWithData:]. If the NSData can be unarchived as an NSURL, the NSURL is returned otherwise nil is returned.

    2. If the value for this key was a file reference URL, the file reference URL will be created but its bookmark data will not be resolved until the NSURL instance is later used (e.g. at -[NSData initWithContentsOfURL:]).

    3. If the value for the key is an NSString which begins with a ~, the NSString will be expanded using -[NSString stringByExpandingTildeInPath] and a file: scheme NSURL will be created from that.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.6 and later.

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

    Declaration

    Swift

    func setBool(_ value: Bool, forKey defaultName: String)

    Objective-C

    - (void)setBool:(BOOL)value forKey:(NSString *)defaultName

    Parameters

    value

    The Boolean value to store in the defaults database.

    defaultName

    The key with which to associate with the value.

    Discussion

    Invokes setObject:forKey: as part of its implementation.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

    See Also

    – boolForKey:

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

    Declaration

    Swift

    func setFloat(_ value: Float, forKey defaultName: String)

    Objective-C

    - (void)setFloat:(float)value forKey:(NSString *)defaultName

    Parameters

    value

    The floating-point value to store in the defaults database.

    defaultName

    The key with which to associate with the value.

    Discussion

    Invokes setObject:forKey: as part of its implementation.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    func setInteger(_ value: Int, forKey defaultName: String)

    Objective-C

    - (void)setInteger:(NSInteger)value forKey:(NSString *)defaultName

    Parameters

    value

    The integer value to store in the defaults database.

    defaultName

    The key with which to associate with the value.

    Discussion

    Invokes setObject:forKey: as part of its implementation.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    func setObject(_ value: AnyObject?, forKey defaultName: String)

    Objective-C

    - (void)setObject:(id)value forKey:(NSString *)defaultName

    Parameters

    value

    The object to store in the defaults database.

    defaultName

    The key with which to associate with the value.

    Discussion

    The value parameter can be only property list objects: NSData, NSString, NSNumber, NSDate, NSArray, or NSDictionary. For NSArray and NSDictionary objects, their contents must be property list objects. See What is a Property List? in Property List Programming Guide.

    Setting a default has no effect on the value returned by the objectForKey: method if the same key exists in a domain that precedes the application domain in the search list.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    func setDouble(_ value: Double, forKey defaultName: String)

    Objective-C

    - (void)setDouble:(double)value forKey:(NSString *)defaultName

    Parameters

    value

    The double value.

    defaultName

    The key with which to associate with the value.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.5 and later.

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

    Declaration

    Swift

    func setURL(_ url: NSURL, forKey defaultName: String)

    Objective-C

    - (void)setURL:(NSURL *)url forKey:(NSString *)defaultName

    Parameters

    url

    The NSURL to store in the defaults database.

    defaultName

    The key with which to associate with the value.

    Discussion

    When an NSURL is stored using -[NSUserDefaults setURL:forKey:], some adjustments are made:

    1. Any non-file URL is written by calling +[NSKeyedArchiver archivedDataWithRootObject:] using the NSURL instance as the root object.

    2. Any file reference file: scheme URL will be treated as a non-file URL, and information which makes this URL compatible with 10.5 systems will also be written as part of the archive as well as its minimal bookmark data.

    3. Any path-based file: scheme URL is written by first taking the absolute URL, getting the path from that and then determining if the path can be made relative to the user's home directory. If it can, the string is abbreviated by using stringByAbbreviatingWithTildeInPath and written out. This allows pre-10.6 clients to read the default and use -[NSString stringByExpandingTildeInPath] to use this information.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.6 and later.

    See Also

    – URLForKey:

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

    Declaration

    Swift

    func removeObjectForKey(_ defaultName: String)

    Objective-C

    - (void)removeObjectForKey:(NSString *)defaultName

    Parameters

    defaultName

    The key whose value you want to remove.

    Discussion

    Removing a default has no effect on the value returned by the objectForKey: method if the same key exists in a domain that precedes the standard application domain in the search list.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    func objectIsForcedForKey(_ key: String) -> Bool

    Objective-C

    - (BOOL)objectIsForcedForKey:(NSString *)key

    Parameters

    key

    The key whose status you want to check.

    Return Value

    YEStrue if the value of the specified key is managed by an administrator, otherwise NOfalse.

    Discussion

    This method assumes that the key is a preference associated with the current user and application. For managed keys, the application should disable any user interface that allows the user to modify the value of key.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.2 and later.

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

    Declaration

    Swift

    func objectIsForcedForKey(_ key: String, inDomain domain: String) -> Bool

    Objective-C

    - (BOOL)objectIsForcedForKey:(NSString *)key inDomain:(NSString *)domain

    Parameters

    key

    The key whose status you want to check.

    domain

    The domain of the key.

    Return Value

    YEStrue if the key is managed by an administrator in the specified domain, otherwise NOfalse.

    Discussion

    This method assumes that the key is a preference associated with the current user. For managed keys, the application should disable any user interface that allows the user to modify the value of key.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.2 and later.

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

    Declaration

    Swift

    func dictionaryRepresentation() -> [NSObject : AnyObject]

    Objective-C

    - (NSDictionary *)dictionaryRepresentation

    Return Value

    A dictionary containing the keys. The keys are names of defaults and the value corresponding to each key is a property list object (NSData, NSString, NSNumber, NSDate, NSArray, or NSDictionary).

    Discussion

    As with objectForKey:, key-value pairs in domains that are earlier in the search list take precedence. The combined result does not preserve information about which domain each entry came from.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    func removeVolatileDomainForName(_ domainName: String)

    Objective-C

    - (void)removeVolatileDomainForName:(NSString *)domainName

    Parameters

    domainName

    The volatile domain you want to remove.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

  • Sets the dictionary for the specified volatile domain.

    Declaration

    Swift

    func setVolatileDomain(_ domain: [NSObject : AnyObject], forName domainName: String)

    Objective-C

    - (void)setVolatileDomain:(NSDictionary *)domain forName:(NSString *)domainName

    Parameters

    domain

    The dictionary of keys and values you want to assign to the domain.

    domainName

    The domain whose keys and values you want to set.

    Discussion

    This method raises an NSInvalidArgumentException if a volatile domain with the specified name already exists.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

  • Returns the dictionary for the specified volatile domain.

    Declaration

    Swift

    func volatileDomainForName(_ domainName: String) -> [NSObject : AnyObject]

    Objective-C

    - (NSDictionary *)volatileDomainForName:(NSString *)domainName

    Parameters

    domainName

    The domain whose keys and values you want.

    Return Value

    The dictionary of keys and values belonging to the domain. The keys in the dictionary are names of defaults, and the value corresponding to each key is a property list object (NSData, NSString, NSNumber, NSDate, NSArray, or NSDictionary).

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

  • The current volatile domain names. (read-only)

    Declaration

    Swift

    var volatileDomainNames: [AnyObject] { get }

    Objective-C

    @property(readonly, copy) NSArray *volatileDomainNames

    Discussion

    The domain names are represented as strings. You can get the contents of each domain by passing the returned domain names to the volatileDomainForName: method.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    func addSuiteNamed(_ suiteName: String)

    Objective-C

    - (void)addSuiteNamed:(NSString *)suiteName

    Parameters

    suiteName

    The domain name to insert. This domain is inserted after the application domain.

    Discussion

    The suiteName domain is similar to a bundle identifier string, but is not necessarily tied to a particular application or bundle. A suite can be used to hold preferences that are shared between multiple applications.

    Searches of preferences tied to a suite follow the normal pattern, searching first for current user, current host, then

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    func removeSuiteNamed(_ suiteName: String)

    Objective-C

    - (void)removeSuiteNamed:(NSString *)suiteName

    Parameters

    suiteName

    The domain name to remove.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

  • These constants specify various user defaults domains.

    Declaration

    Swift

    let NSGlobalDomain: NSString! let NSArgumentDomain: NSString! let NSRegistrationDomain: NSString!

    Objective-C

    extern NSString *NSGlobalDomain; extern NSString *NSArgumentDomain; extern NSString *NSRegistrationDomain;

    Constants

    • NSGlobalDomain

      NSGlobalDomain

      The domain consisting of defaults meant to be seen by all applications.

      Available in OS X v10.0 and later.

    • NSArgumentDomain

      NSArgumentDomain

      The domain consisting of defaults parsed from the application’s arguments. These are one or more pairs of the form -default value included in the command-line invocation of the application.

      Available in OS X v10.0 and later.

    • NSRegistrationDomain

      NSRegistrationDomain

      The domain consisting of a set of temporary defaults whose values can be set by the application to ensure that searches will always be successful.

      Available in OS X v10.0 and later.

  • The NSUserDefaults class provides the following constants as a convenience. They provide access to values of the keys to the locale dictionary, which is discussed in Preferences and Settings Programming Guide.

    See NSDateFormatter and Data Formatting Guide.

    Declaration

    Objective-C

    extern NSString *NSAMPMDesignation; extern NSString *NSDateFormatString; extern NSString *NSDateTimeOrdering; extern NSString *NSEarlierTimeDesignations; extern NSString *NSHourNameDesignations; extern NSString *NSLaterTimeDesignations; extern NSString *NSMonthNameArray; extern NSString *NSNextDayDesignations; extern NSString *NSNextNextDayDesignations; extern NSString *NSPriorDayDesignations; extern NSString *NSShortDateFormatString; extern NSString *NSShortMonthNameArray; extern NSString *NSShortTimeDateFormatString; extern NSString *NSShortWeekDayNameArray; extern NSString *NSThisDayDesignations; extern NSString *NSTimeDateFormatString; extern NSString *NSTimeFormatString; extern NSString *NSWeekDayNameArray; extern NSString *NSYearMonthWeekDesignations;

    Constants

    • NSAMPMDesignation

      NSAMPMDesignation

      Key for the value that specifies how the morning and afternoon designations are printed, affecting strings that use the %p format specifier.

      Use AMSymbol or PMSymbol (NSDateFormatter) instead.

      The defaults are “AM” and “PM”.

      Available in OS X v10.0 and later.

      Deprecated in OS X v10.5.

    • NSDateFormatString

      NSDateFormatString

      Key for the format string that specifies how how dates are printed using the date format specifiers.

      Use the appropriate API from NSDateFormatter instead—see Data Formatting Guide.

      The default is to use weekday names with full month names and full years, as in “Saturday, March 24, 2001.”

      Available in OS X v10.0 and later.

      Deprecated in OS X v10.5.

    • NSDateTimeOrdering

      NSDateTimeOrdering

      Key for the string that specifies how to use ambiguous numbers in date strings.

      Specify this value as a permutation of the letters M (month), D (day), Y (year), and H (hour). For example, MDYH treats “2/3/01 10” as the 3rd day of February 2001 at 10:00 am, whereas DMYH treats the same value as the 2nd day of March 2001 at 10:00 am. If fewer numbers are specified than are needed, the numbers are prioritized to satisfy day first, then month, and then year. For example, if you supply only the value 12, it means the 12th day of this month in this year because the day must be specified. If you supply “2 12” it means either February 12 or December 2, depending on if the ordering is “MDYH” or “DMYH.”

      Available in OS X v10.0 and later.

      Deprecated in OS X v10.5.

    • NSEarlierTimeDesignations

      NSEarlierTimeDesignations

      Key for an array of strings that denote a time in the past.

      There is no direct replacement. If you need to localize words such as “prior,” you should use a strings file as you would for any other localizable text—see Localizing String Resources.

      These are adjectives that modify values from NSYearMonthWeekDesignations. The defaults are “prior,” “last,” “past,” and “ago.”

      Available in OS X v10.0 and later.

      Deprecated in OS X v10.5.

    • NSHourNameDesignations

      NSHourNameDesignations

      Key for strings that identify the time of day.

      These strings should be bound to an hour. The default is this array of arrays: (0, midnight), (10, morning), (12, noon, lunch), (14, afternoon), (19, dinner).

      Available in OS X v10.0 and later.

      Deprecated in OS X v10.5.

    • NSLaterTimeDesignations

      NSLaterTimeDesignations

      Key for an array of strings that denote a time in the future.

      There is no direct replacement. If you need to localize words such as “next,” you should use a strings file as you would for any other localizable text—see Localizing String Resources.

      Strings in this array are adjectives that modify a value from NSYearMonthWeekDesignations.

      The default is an array that contains a single string, "next".

      Available in OS X v10.0 and later.

      Deprecated in OS X v10.5.

    • NSMonthNameArray

      NSMonthNameArray

      Key for the value that specifies the names for the months, affecting strings that use the %B format specifier.

      Use monthSymbols or—if you are going to display these in the user interface by themselves—standaloneMonthSymbols (NSDateFormatter) instead.

      Available in OS X v10.0 and later.

      Deprecated in OS X v10.5.

    • NSNextDayDesignations

      NSNextDayDesignations

      Key for an array of strings that denote the day after today.

      There is no direct replacement. If you need to localize words such as “tomorrow,” you should use a strings file as you would for any other localizable text—see Localizing String Resources.

      The default is an array that contains a single string, "tomorrow".

      Available in OS X v10.0 and later.

      Deprecated in OS X v10.5.

    • NSNextNextDayDesignations

      NSNextNextDayDesignations

      Key for an array of strings that denote the day after tomorrow.

      There is no direct replacement. If you need to localize words such as “nextday,” you should use a strings file as you would for any other localizable text—see Localizing String Resources.

      The default is an array that contains a single string, "nextday".

      Available in OS X v10.0 and later.

      Deprecated in OS X v10.5.

    • NSPriorDayDesignations

      NSPriorDayDesignations

      Key for an array of strings that denote the day before today.

      There is no direct replacement. If you need to localize words such as “yesterday,” you should use a strings file as you would for any other localizable text—see Localizing String Resources.

      The default is an array that contains a single string, "yesterday".

      Available in OS X v10.0 and later.

      Deprecated in OS X v10.5.

    • NSShortDateFormatString

      NSShortDateFormatString

      Key for a format string that specifies how dates are abbreviated.

      Use the appropriate API from NSDateFormatter instead—see Data Formatting Guide.

      The default is to separate the day month and year with slashes and to put the day first, as in 31/10/01.

      Available in OS X v10.0 and later.

      Deprecated in OS X v10.5.

    • NSShortWeekDayNameArray

      NSShortWeekDayNameArray

      Key for an array of strings that specify the abbreviations for the days of the week, affecting strings that use the %a format specifier.

      Use shortWeekdaySymbols or—if you are going to display these in the user interface by themselves—shortStandaloneWeekdaySymbols (NSDateFormatter) instead.

      Sunday should be the first day of the week.

      Available in OS X v10.0 and later.

      Deprecated in OS X v10.5.

    • NSShortMonthNameArray

      NSShortMonthNameArray

      Key for an array of strings that specify the abbreviations for the months, affecting strings that use the %b format specifier.

      Use shortMonthSymbolsor—if you are going to display these in the user interface by themselves—shortStandaloneMonthSymbols (NSDateFormatter) instead.

      Available in OS X v10.0 and later.

      Deprecated in OS X v10.5.

    • NSShortTimeDateFormatString

      NSShortTimeDateFormatString

      Key for a format string that specifies how times and dates are abbreviated.

      Use the appropriate API fromNSDateFormatter instead—see Data Formatting Guide.

      The default is to use dashes to separate the day, month, and year and to use a 12-hour clock, as in "31-Jan-01 1:30 PM."]

      Available in OS X v10.0 and later.

      Deprecated in OS X v10.5.

    • NSThisDayDesignations

      NSThisDayDesignations

      Key for an array of strings that specify what this day is called.

      There is no direct replacement. If you need to localize words such as “today,” you should use a strings file as you would for any other localizable text—see Localizing String Resources.

      The default is an array containing two strings, "today" and "now".

      Available in OS X v10.0 and later.

      Deprecated in OS X v10.5.

    • NSTimeDateFormatString

      NSTimeDateFormatString

      Key for the value that specifies how dates with times are printed, affecting strings that use the format specifiers %c, %X, or %x.

      Use the appropriate API from NSDateFormatter instead—see Data Formatting Guide.

      The default is to use full month names and days with a 24-hour clock, as in "Sunday, January 01, 2001 23:00:00 Pacific Standard Time."

      Available in OS X v10.0 and later.

      Deprecated in OS X v10.5.

    • NSTimeFormatString

      NSTimeFormatString

      Key for a format string that specifies how dates with times are printed.

      Use the appropriate API from NSDateFormatter instead—see Data Formatting Guide.

      The default is to use a 12-hour clock.

      Available in OS X v10.0 and later.

      Deprecated in OS X v10.5.

    • NSWeekDayNameArray

      NSWeekDayNameArray

      Key for an array of strings that specify the names for the days of the week, affecting strings that use the %A format specifier.

      Use weekdaySymbols or—if you are going to display these in the user interface by themselves—standaloneWeekdaySymbols (NSDateFormatter) instead.

      Sunday should be the first day of the week.

      Available in OS X v10.0 and later.

      Deprecated in OS X v10.5.

    • NSYearMonthWeekDesignations

      NSYearMonthWeekDesignations

      Key for an array of strings that specify the words for year, month, and week in the current locale.

      There is no direct replacement. If you need to localize words such as “year,” you should use a strings file as you would for any other localizable text—see Localizing String Resources.

      The defaults are “year,” “month,” and “week.”

      Available in OS X v10.0 and later.

      Deprecated in OS X v10.5.

  • The NSUserDefaults class provides the following constants as a convenience. They provide access to values of the keys to the locale dictionary, which is discussed in Preferences and Settings Programming Guide.

    These constants are deprecated in OS X v10.5. Where there are replacements, you can typically find them in NSNumberFormatter or NSLocale—for example, currencySymbol, currencyDecimalSeparator, and thousandSeparator—otherwise you should use the patterns described in Data Formatting Guide.

    Declaration

    Objective-C

    extern NSString *NSCurrencySymbol; extern NSString *NSDecimalDigits; extern NSString *NSDecimalSeparator; extern NSString *NSInternationalCurrencyString; extern NSString *NSNegativeCurrencyFormatString; extern NSString *NSPositiveCurrencyFormatString; extern NSString *NSThousandsSeparator;

    Constants

    • NSCurrencySymbol

      NSCurrencySymbol

      A string that specifies the symbol used to denote currency in this language.

      Use currencySymbol (NSNumberFormatter) or retrieve the NSLocaleCurrencySymbol from the current locale instead.

      The default is “$”.

      Available in OS X v10.0 and later.

      Deprecated in OS X v10.5.

    • NSDecimalDigits

      NSDecimalDigits

      Strings that identify the decimal digits in addition to or instead of the ASCII digits.

      Available in OS X v10.0 and later.

      Deprecated in OS X v10.5.

    • NSDecimalSeparator

      NSDecimalSeparator

      A string that specifies the decimal separator.

      Use decimalSeparator or currencyDecimalSeparator (NSNumberFormatter) or retrieve the NSLocaleDecimalSeparator from the current locale instead.

      The decimal separator separates the ones place from the tenths place. The default is “.”.

      Available in OS X v10.0 and later.

      Deprecated in OS X v10.5.

    • NSInternationalCurrencyString

      NSInternationalCurrencyString

      A string containing a three-letter abbreviation for currency, following the ISO 4217 standard.

      Retrieve the NSLocaleCurrencySymbol from the current locale instead.

      Available in OS X v10.0 and later.

      Deprecated in OS X v10.5.

    • NSNegativeCurrencyFormatString

      NSNegativeCurrencyFormatString

      A format string that specifies how negative numbers are printed when representing a currency value.

      Use the appropriate API from NSNumberFormatter instead—see Data Formatting Guide.

      The default is –$9,999.00.

      Available in OS X v10.0 and later.

      Deprecated in OS X v10.5.

    • NSPositiveCurrencyFormatString

      NSPositiveCurrencyFormatString

      A format string that specifies how positive numbers are printed when representing a currency value.

      Use the appropriate API from NSNumberFormatter instead—see Data Formatting Guide.

      The default is $9,999.00.

      Available in OS X v10.0 and later.

      Deprecated in OS X v10.5.

    • NSThousandsSeparator

      NSThousandsSeparator

      A string that specifies the separator character for the thousands place of a decimal number.

      Retrieve the NSLocaleGroupingSeparator from the current locale instead.

      The default is a comma.

      Available in OS X v10.0 and later.

      Deprecated in OS X v10.5.

  • This notification is posted when a change is made to defaults in a persistent domain.

    The notification object is the NSUserDefaults object. This notification does not contain a userInfo dictionary.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.