Class: NSDictionary

Inherits:
NSObject show all

Overview

The NSDictionary class declares the programmatic interface to objects that manage immutable associations of keys and values. Use this class or its subclass NSMutableDictionary when you need a convenient and efficient way to retrieve data associated with an arbitrary key. NSDictionary creates static dictionaries, and NSMutableDictionary creates dynamic dictionaries. (For convenience, we use the term dictionary to refer to any instance of one of these classes without specifying its exact class membership.)

Direct Known Subclasses

NSMutableDictionary

Class Method Summary (collapse)

Instance Method Summary (collapse)

Methods inherited from NSObject

#!, #!=, #!~, #, #==, #===, #=~, #Rational, #__callee__, #__method__, #__send__, #__type__, `, alloc, allocWithZone:, #autoContentAccessingProxy, autoload, autoload?, autorelease_pool, #awakeAfterUsingCoder:, binding, block_given?, caller, cancelPreviousPerformRequestsWithTarget:, cancelPreviousPerformRequestsWithTarget:selector:object:, catch, class, classFallbacksForKeyedArchiver, #classForCoder, #classForKeyedArchiver, classForKeyedUnarchiver, #clone, conformsToProtocol:, #copy, copyWithZone:, #dealloc, #define_singleton_method, description, display, #doesNotRecognizeSelector:, #dup, #enum_for, #eql?, #equal?, #extend, fail, #finalize, format, #forwardInvocation:, #forwardingTargetForSelector:, framework, #freeze, #frozen?, getpass, gets, global_variables, #init, initialize, #initialize_clone, #initialize_copy, #initialize_dup, #inspect, instanceMethodForSelector:, instanceMethodSignatureForSelector:, #instance_eval, #instance_exec, #instance_of?, #instance_variable_defined?, #instance_variable_get, #instance_variable_set, #instance_variables, instancesRespondToSelector:, isSubclassOfClass:, #is_a?, iterator?, #kind_of?, lambda, load, load_bridge_support_file, load_plist, local_variables, loop, #method, #methodForSelector:, #methodSignatureForSelector:, #methods, #mutableCopy, mutableCopyWithZone:, new, #nil?, open, p, #performSelector:onThread:withObject:waitUntilDone:, #performSelector:onThread:withObject:waitUntilDone:modes:, #performSelector:withObject:afterDelay:, #performSelector:withObject:afterDelay:inModes:, #performSelectorInBackground:withObject:, #performSelectorOnMainThread:withObject:waitUntilDone:, #performSelectorOnMainThread:withObject:waitUntilDone:modes:, print, printf, #private_methods, proc, #protected_methods, #public_method, #public_methods, #public_send, putc, puts, raise, rand, readline, readlines, #replacementObjectForCoder:, #replacementObjectForKeyedArchiver:, require, resolveClassMethod:, resolveInstanceMethod:, #respond_to?, #respond_to_missing?, select, #send, setVersion:, #singleton_methods, sprintf, srand, superclass, #taint, #tainted?, #tap, test, throw, #to_plist, #to_s, trace_var, trap, #trust, #untaint, untrace_var, #untrust, #untrusted?, version

Constructor Details

This class inherits a constructor from NSObject

Dynamic Method Handling

This class handles dynamic methods through the method_missing method in the class NSObject

Class Method Details

+ (Object) dictionary

Creates and returns an empty dictionary. This method is declared primarily for use with mutable subclasses of NSDictionary.If you don’t want a temporary object, you can also create an empty dictionary using alloc… and init.

Returns:

  • (Object) —

    A new empty dictionary.

+ (Object) dictionaryWithContentsOfFile(path)

Creates and returns a dictionary using the keys and values found in a file specified by a given path. The dictionary representation in the file identified by path must contain only property list objects (NSString, NSData, NSDate, NSNumber, NSArray, or NSDictionary objects). For more details, see Property List Programming Guide. The objects contained by this dictionary are immutable, even if the dictionary is mutable.

Parameters:

  • path (String) —

    A full or relative pathname. The file identified by path must contain a string representation of a property list whose root object is a dictionary.

Returns:

  • (Object) —

    A new dictionary that contains the dictionary at path, or nil if there is a file error or if the contents of the file are an invalid representation of a dictionary.

+ (Object) dictionaryWithContentsOfURL(aURL)

Creates and returns a dictionary using the keys and values found in a resource specified by a given URL. The dictionary representation in the file identified by path must contain only property list objects (NSString, NSData, NSDate, NSNumber, NSArray, or NSDictionary objects). For more details, see Property List Programming Guide. The objects contained by this dictionary are immutable, even if the dictionary is mutable.

Parameters:

  • aURL (NSURL) —

    An URL that identifies a resource containing a string representation of a property list whose root object is a dictionary.

Returns:

  • (Object) —

    A new dictionary that contains the dictionary at aURL, or nil if there is an error or if the contents of the resource are an invalid representation of a dictionary.

+ (Object) dictionaryWithDictionary(otherDictionary)

Creates and returns a dictionary containing the keys and values from another given dictionary.

Parameters:

  • otherDictionary (Hash) —

    A dictionary containing the keys and values with which to initialize the new dictionary.

Returns:

  • (Object) —

    A new dictionary containing the keys and values found in otherDictionary.

+ (Object) dictionaryWithObject(anObject, forKey:aKey)

Creates and returns a dictionary containing a given key and value.

Parameters:

  • anObject (Object) —

    The value corresponding to aKey.If this value is nil, an NSInvalidArgumentException is raised.

  • aKey (Object) —

    The key for anObject.If this value is nil, an NSInvalidArgumentException is raised.

Returns:

  • (Object) —

    A new dictionary containing a single object, anObject, for a single key, aKey.

+ (Object) dictionaryWithObjects(objects, forKeys:keys)

Creates and returns a dictionary containing entries constructed from the contents of an array of keys and an array of values. This method steps through the objects and keys arrays, creating entries in the new dictionary as it goes. An NSInvalidArgumentException is raised if objects and keys don’t have the same number of elements.

Parameters:

  • objects (Array) —

    An array containing the values for the new dictionary.

  • keys (Array) —

    An array containing the keys for the new dictionary. Each key is copied (using copyWithZone:; keys must conform to the NSCopying protocol), and the copy is added to the dictionary.

Returns:

  • (Object) —

    A new dictionary containing entries constructed from the contents of objects and keys.

+ (Object) dictionaryWithObjects(objects, forKeys:keys, count:count)

Creates and returns a dictionary containing count objects from the objects array. This method steps through the objects and keys arrays, creating entries in the new dictionary as it goes. An NSInvalidArgumentException is raised if a key or value object is nil.The following code fragment illustrates how to create a dictionary that associates the alphabetic characters with their ASCII values:

Parameters:

  • objects (Object) —

    A C array of values for the new dictionary.

  • keys (Object) —

    A C array of keys for the new dictionary. Each key is copied (using copyWithZone:; keys must conform to the NSCopying protocol), and the copy is added to the new dictionary.

  • count (Integer) —

    The number of elements to use from the keys and objects arrays. count must not exceed the number of elements in objects or keys.

Returns:

+ (Object) dictionaryWithObjectsAndKeys(firstObject, ...)

Creates and returns a dictionary containing entries constructed from the specified set of values and keys. This method is similar to dictionaryWithObjects:forKeys:, differing only in the way key-value pairs are specified.For example:

Parameters:

  • firstObject —

    The first value to add to the new dictionary.

  • ... —

    First the key for firstObject, then a null-terminated list of alternating values and keys. If any key is nil, an NSInvalidArgumentException is raised.

Returns:

+ (Object) sharedKeySetForKeys(keys)

Creates a shared key set object for the specified keys. The array of keys may contain duplicates which are quietly ignored. Duplicate hash values of the keys are quietly allowed, but may cause lower performance and increase memory usage.Typically you would create a shared key set for a given set of keys once, before creating shared key dictionaries, and retain and save the result of this method for use with the NSMutableDictionary class method dictionaryWithSharedKeySet:.

Parameters:

  • keys (Array) —

    The array of keys. If the parameter is nil, an exception is thrown. If the array of keys is empty, an empty key set is returned.

Returns:

  • (Object) —

    A shared key set object.

Instance Method Details

- (Array) allKeys

Returns a new array containing the dictionary’s keys. The order of the elements in the array is not defined.

Returns:

  • (Array) —

    A new array containing the dictionary’s keys, or an empty array if the dictionary has no entries.

- (Array) allKeysForObject(anObject)

Returns a new array containing the keys corresponding to all occurrences of a given object in the dictionary. Each object in the dictionary is sent an isEqual: message to determine if it’s equal to anObject.

Parameters:

  • anObject (Object) —

    The value to look for in the dictionary.

Returns:

  • (Array) —

    A new array containing the keys corresponding to all occurrences of anObject in the dictionary. If no object matching anObject is found, returns an empty array.

- (Array) allValues

Returns a new array containing the dictionary’s values. The order of the values in the array isn’t defined.

Returns:

  • (Array) —

    A new array containing the dictionary’s values, or an empty array if the dictionary has no entries.

- (Integer) count

Returns the number of entries in the dictionary.

Returns:

  • (Integer) —

    The number of entries in the dictionary.

- (String) description

Returns a string that represents the contents of the dictionary, formatted as a property list. If each key in the dictionary is an NSString object, the entries are listed in ascending order by key, otherwise the order in which the entries are listed is undefined. This method is intended to produce readable output for debugging purposes, not for serializing data. If you want to store dictionary data for later retrieval, see Property List Programming Guide and Archives and Serializations Programming Guide.

Returns:

  • (String) —

    A string that represents the contents of the dictionary, formatted as a property list.

- (String) descriptionInStringsFileFormat

Returns a string that represents the contents of the dictionary, formatted in .strings file format. The order in which the entries are listed is undefined.

Returns:

  • (String) —

    A string that represents the contents of the dictionary, formatted in .strings file format.

- (String) descriptionWithLocale(locale)

Returns a string object that represents the contents of the dictionary, formatted as a property list. For a description of how locale is applied to each element in the dictionary, see descriptionWithLocale:indent:.If each key in the dictionary responds to compare:, the entries are listed in ascending order by key, otherwise the order in which the entries are listed is undefined.

Parameters:

  • locale (Object) —

    An object that specifies options used for formatting each of the dictionary’s keys and values; pass nil if you don’t want them formatted.On iOS and OS X v10.5 and later, either an instance of NSDictionary or an NSLocale object may be used for locale. On OS X v10.4 and earlier it must be an instance of NSDictionary.

Returns:

- (String) descriptionWithLocale(locale, indent:level)

Returns a string object that represents the contents of the dictionary, formatted as a property list. The returned NSString object contains the string representations of each of the dictionary’s entries. descriptionWithLocale:indent: obtains the string representation of a given key or value as follows:If the object is an NSString object, it is used as is. If the object responds to descriptionWithLocale:indent:, that method is invoked to obtain the object’s string representation. If the object responds to descriptionWithLocale:, that method is invoked to obtain the object’s string representation. If none of the above conditions is met, the object’s string representation is obtained by invoking its description method.If each key in the dictionary responds to compare:, the entries are listed in ascending order, by key. Otherwise, the order in which the entries are listed is undefined.

Parameters:

  • locale (Object) —

    An object that specifies options used for formatting each of the dictionary’s keys and values; pass nil if you don’t want them formatted.On iOS and OS X v10.5 and later, either an instance of NSDictionary or an NSLocale object may be used for locale. On OS X v10.4 and earlier it must be an instance of NSDictionary.

  • level (Integer) —

    Specifies a level of indentation, to make the output more readable: the indentation is (4 spaces) * level.

Returns:

  • (String) —

    A string object that represents the contents of the dictionary, formatted as a property list.

- (Object) enumerateKeysAndObjectsUsingBlock(block)

Applies a given block object to the entries of the dictionary. If the block sets *stop to YES, the enumeration stops.

Parameters:

  • block —

    A block object to operate on entries in the dictionary.

Returns:

- (Object) enumerateKeysAndObjectsWithOptions(opts, usingBlock:block)

Applies a given block object to the entries of the dictionary. If the block sets *stop to YES, the enumeration stops.

Parameters:

  • opts —

    Enumeration options.

  • block —

    A block object to operate on entries in the dictionary.

Returns:

- (NSDate) fileCreationDate

Returns the value for the NSFileCreationDate key.

Returns:

  • (NSDate) —

    The value for the NSFileCreationDate key, or nil if the dictionary doesn’t have an entry for the key.

- (Boolean) fileExtensionHidden

Returns the value for the NSFileExtensionHidden key.

Returns:

  • (Boolean) —

    The value for the NSFileExtensionHidden key, or NO if the dictionary doesn’t have an entry for the key.

- (NSNumber) fileGroupOwnerAccountID

Returns the value for the NSFileGroupOwnerAccountID key.

Returns:

  • (NSNumber) —

    The value for the NSFileGroupOwnerAccountID key, or nil if the dictionary doesn’t have an entry for the key.

- (String) fileGroupOwnerAccountName

Returns the value for the NSFileGroupOwnerAccountName key. This and the other file… methods are for use with a dictionary, such as those returned from the methods fileAttributesAtPath:traverseLink: (NSFileManager), directoryAttributes (NSDirectoryEnumerator), and fileAttributes (NSDirectoryEnumerator), that represents the POSIX attributes of a file or directory. This method returns the name of the corresponding file’s group.

Returns:

  • (String) —

    The value for the key NSFileGroupOwnerAccountName, or nil if the dictionary doesn’t have an entry for the key.

- (OSType) fileHFSCreatorCode

Returns the value for the NSFileHFSCreatorCode key. See “HFS File Types” for details on the OSType data type.

Returns:

  • (OSType) —

    The value for the NSFileHFSCreatorCode key, or 0 if the dictionary doesn’t have an entry for the key.

- (OSType) fileHFSTypeCode

Returns the value for the NSFileHFSTypeCode key. See “HFS File Types” for details on the OSType data type.

Returns:

  • (OSType) —

    The value for the NSFileHFSTypeCode key, or 0 if the dictionary doesn’t have an entry for the key.

- (Boolean) fileIsAppendOnly

Returns the value for the NSFileAppendOnly key.

Returns:

  • (Boolean) —

    The value for the NSFileAppendOnly key, or NO if the dictionary doesn’t have an entry for the key.

- (Boolean) fileIsImmutable

Returns the value for the NSFileImmutable key. This and the other file... methods are for use with a dictionary, such as those returned from the methods fileAttributesAtPath:traverseLink: (NSFileManager), directoryAttributes (NSDirectoryEnumerator), and fileAttributes (NSDirectoryEnumerator), that represents the POSIX attributes of a file or directory.

Returns:

  • (Boolean) —

    The value for the NSFileImmutable key, or NO if the dictionary doesn’t have an entry for the key.

- (NSDate) fileModificationDate

Returns the value for the key NSFileModificationDate. This and the other file… methods are for use with a dictionary, such as those returned from the methods fileAttributesAtPath:traverseLink: (NSFileManager), directoryAttributes (NSDirectoryEnumerator), and fileAttributes (NSDirectoryEnumerator), that represents the POSIX attributes of a file or directory. This method returns the date that the file’s data was last modified.

Returns:

  • (NSDate) —

    The value for the key NSFileModificationDate, or nil if the dictionary doesn’t have an entry for the key.

- (NSNumber) fileOwnerAccountID

Returns the value for the NSFileOwnerAccountID key. This and the other file… methods are for use with a dictionary, such as those returned from the methods fileAttributesAtPath:traverseLink: (NSFileManager), directoryAttributes (NSDirectoryEnumerator), and fileAttributes (NSDirectoryEnumerator), that represents the POSIX attributes of a file or directory. This method returns the account name of the file’s owner.

Returns:

  • (NSNumber) —

    The value for the NSFileOwnerAccountID key, or nil if the dictionary doesn’t have an entry for the key.

- (String) fileOwnerAccountName

Returns the value for the key NSFileOwnerAccountName. This and the other file… methods are for use with a dictionary, such as those returned from the methods fileAttributesAtPath:traverseLink: (NSFileManager), directoryAttributes (NSDirectoryEnumerator), and fileAttributes (NSDirectoryEnumerator), that represents the POSIX attributes of a file or directory. This method returns the account name of the file’s owner.

Returns:

  • (String) —

    The value for the key NSFileOwnerAccountName, or nil if the dictionary doesn’t have an entry for the key.

- (Integer) filePosixPermissions

Returns the value for the key NSFilePosixPermissions. This and the other file… methods are for use with a dictionary, such as those returned from the methods fileAttributesAtPath:traverseLink: (NSFileManager), directoryAttributes (NSDirectoryEnumerator), and fileAttributes (NSDirectoryEnumerator), that represents the POSIX attributes of a file or directory. This method returns the file’s permissions.

Returns:

  • (Integer) —

    The value, as an unsigned long, for the key NSFilePosixPermissions, or 0 if the dictionary doesn’t have an entry for the key.

- (Integer) fileSize

Returns the value for the key NSFileSize. This and the other file… methods are for use with a dictionary such, as those returned from the methods fileAttributesAtPath:traverseLink: (NSFileManager), directoryAttributes (NSDirectoryEnumerator), and fileAttributes (NSDirectoryEnumerator), that represents the POSIX attributes of a file or directory. This method returns the file’s size.

Returns:

  • (Integer) —

    The value, as an unsigned long long, for the key NSFileSize, or 0 if the dictionary doesn’t have an entry for the key.

- (Integer) fileSystemFileNumber

Returns the value for the key NSFileSystemFileNumber. This and the other file… methods are for use with a dictionary, such as those returned from the methods fileAttributesAtPath:traverseLink: (NSFileManager), directoryAttributes (NSDirectoryEnumerator), and fileAttributes (NSDirectoryEnumerator), that represents the POSIX attributes of a file or directory. This method returns the file’s inode.

Returns:

  • (Integer) —

    The value, as an unsigned long, for the key NSFileSystemFileNumber, or 0 if the dictionary doesn’t have an entry for the key

- (Integer) fileSystemNumber

Returns the value for the key NSFileSystemNumber. This and the other file... methods are for use with a dictionary, such as those returned from the methods fileAttributesAtPath:traverseLink: (NSFileManager), directoryAttributes (NSDirectoryEnumerator), and fileAttributes (NSDirectoryEnumerator), that represents the POSIX attributes of a file or directory. This method returns the ID of the device containing the file.

Returns:

  • (Integer) —

    The value, as an unsigned long, for the key NSFileSystemNumber, or 0 if the dictionary doesn’t have an entry for the key

- (String) fileType

Returns the value for the key NSFileType. This and the other file… methods are for use with a dictionary, such as those returned from the methods fileAttributesAtPath:traverseLink: (NSFileManager), directoryAttributes (NSDirectoryEnumerator), and fileAttributes (NSDirectoryEnumerator), that represents the POSIX attributes of a file or directory. This method returns the file’s type. Possible return values are described in the “Constants” section of NSFileManager.

Returns:

  • (String) —

    The value for the key NSFileType, or nil if the dictionary doesn’t have an entry for the key.

- (Object) getObjects(objects, andKeys:keys)

Returns by reference C arrays of the keys and values in the dictionary. The elements in the returned arrays are ordered such that the first element in objects is the value for the first key in keys and so on.

Parameters:

  • objects (Object) —

    Upon return, contains a C array of the values in the dictionary.

  • keys (Object) —

    Upon return, contains a C array of the keys in the dictionary.

Returns:

- (Object) initWithContentsOfFile(path)

Initializes a newly allocated dictionary using the keys and values found in a file at a given path. The dictionary representation in the file identified by path must contain only property list objects (NSString, NSData, NSDate, NSNumber, NSArray, or NSDictionary objects). For more details, see Property List Programming Guide. The objects contained by this dictionary are immutable, even if the dictionary is mutable.

Parameters:

  • path (String) —

    A full or relative pathname. The file identified by path must contain a string representation of a property list whose root object is a dictionary.

Returns:

  • (Object) —

    An initialized dictionary—which might be different than the original receiver—that contains the dictionary at path, or nil if there is a file error or if the contents of the file are an invalid representation of a dictionary.

- (Object) initWithContentsOfURL(aURL)

Initializes a newly allocated dictionary using the keys and values found at a given URL. The dictionary representation in the file identified by path must contain only property list objects (NSString, NSData, NSDate, NSNumber, NSArray, or NSDictionary objects). For more details, see Property List Programming Guide. The objects contained by this dictionary are immutable, even if the dictionary is mutable.

Parameters:

  • aURL (NSURL) —

    An URL that identifies a resource containing a string representation of a property list whose root object is a dictionary.

Returns:

  • (Object) —

    An initialized dictionary—which might be different than the original receiver—that contains the dictionary at aURL, or nil if there is an error or if the contents of the resource are an invalid representation of a dictionary.

- (Object) initWithDictionary(otherDictionary)

Initializes a newly allocated dictionary by placing in it the keys and values contained in another given dictionary.

Parameters:

  • otherDictionary (Hash) —

    A dictionary containing the keys and values with which to initialize the new dictionary.

Returns:

  • (Object) —

    An initialized dictionary—which might be different than the original receiver—containing the keys and values found in otherDictionary.

- (Object) initWithDictionary(otherDictionary, copyItems:flag)

Initializes a newly allocated dictionary using the objects contained in another given dictionary. After an immutable dictionary has been initialized in this way, it cannot be modified.The copyWithZone: method performs a shallow copy. If you have a collection of arbitrary depth, passing YES for the flag parameter will perform an immutable copy of the first level below the surface. If you pass NO the mutability of the first level is unaffected. In either case, the mutability of all deeper levels is unaffected.

Parameters:

  • otherDictionary (Hash) —

    A dictionary containing the keys and values with which to initialize the new dictionary.

  • flag (Boolean) —

    If YES, each object in otherDictionary receives a copyWithZone: message to create a copy of the object—objects must conform to the NSCopying protocol. In a managed memory environment, this is instead of the retain message the object would otherwise receive. The object copy is then added to the returned dictionary.If NO, then in a managed memory environment each object in otherDictionary simply receives a retain message when it is added to the returned dictionary.

Returns:

  • (Object) —

    An initialized object—which might be different than the original receiver—containing the keys and values found in otherDictionary.

- (Object) initWithObjects(objects, forKeys:keys)

Initializes a newly allocated dictionary with entries constructed from the contents of the objects and keys arrays. This method steps through the objects and keys arrays, creating entries in the new dictionary as it goes. An NSInvalidArgumentException is raised if the objects and keys arrays do not have the same number of elements.

Parameters:

  • objects (Array) —

    An array containing the values for the new dictionary.

  • keys (Array) —

    An array containing the keys for the new dictionary. Each key is copied (using copyWithZone:; keys must conform to the NSCopying protocol), and the copy is added to the new dictionary.

Returns:

- (Object) initWithObjects(objects, forKeys:keys, count:count)

Initializes a newly allocated dictionary with count entries. This method steps through the objects and keys arrays, creating entries in the new dictionary as it goes. An NSInvalidArgumentException is raised if a key or value object is nil.

Parameters:

  • objects (Object) —

    A C array of values for the new dictionary.

  • keys (Object) —

    A C array of keys for the new dictionary. Each key is copied (using copyWithZone:; keys must conform to the NSCopying protocol), and the copy is added to the new dictionary.

  • count (Integer) —

    The number of elements to use from the keys and objects arrays. count must not exceed the number of elements in objects or keys.

Returns:

- (Object) initWithObjectsAndKeys(firstObject, ...)

Initializes a newly allocated dictionary with entries constructed from the specified set of values and keys. This method is similar to initWithObjects:forKeys:, differing only in the way in which the key-value pairs are specified.For example:

Parameters:

  • firstObject —

    The first value to add to the new dictionary.

  • ... —

    First the key for firstObject, then a null-terminated list of alternating values and keys. If any key is nil, an NSInvalidArgumentException is raised.

Returns:

- (Boolean) isEqualToDictionary(otherDictionary)

Returns a Boolean value that indicates whether the contents of the receiving dictionary are equal to the contents of another given dictionary. Two dictionaries have equal contents if they each hold the same number of entries and, for a given key, the corresponding value objects in each dictionary satisfy the isEqual: test.

Parameters:

  • otherDictionary (Hash) —

    The dictionary with which to compare the receiving dictionary.

Returns:

  • (Boolean) —

    YES if the contents of otherDictionary are equal to the contents of the receiving dictionary, otherwise NO.

- (NSEnumerator) keyEnumerator

Returns an enumerator object that lets you access each key in the dictionary. The following code fragment illustrates how you might use this method. If you use this method with instances of mutable subclasses of NSDictionary, your code should not modify the entries during enumeration. If you intend to modify the entries, use the allKeys method to create a “snapshot” of the dictionary’s keys. Then use this snapshot to traverse the entries, modifying them along the way.Note that the objectEnumerator method provides a convenient way to access each value in the dictionary.

Returns:

  • (NSEnumerator) —

    An enumerator object that lets you access each key in the dictionary.

- (NSSet) keysOfEntriesPassingTest(predicate)

Returns the set of keys whose corresponding value satisfies a constraint described by a block object.

Parameters:

  • predicate —

    A block object that specifies constraints for values in the dictionary.

Returns:

  • (NSSet) —

    The set of keys whose corresponding value satisfies predicate.

- (NSSet) keysOfEntriesWithOptions(opts, passingTest:predicate)

Returns the set of keys whose corresponding value satisfies a constraint described by a block object.

Parameters:

  • opts —

    A bit mask of enumeration options.

  • predicate —

    A block object that specifies constraints for values in the dictionary.

Returns:

  • (NSSet) —

    The set of keys whose corresponding value satisfies predicate.

- (Array) keysSortedByValueUsingComparator(cmptr)

Returns an array of the dictionary’s keys, in the order they would be in if the dictionary were sorted by its values using a given comparator block.

Parameters:

  • cmptr (NSComparator) —

    A comparator block.

Returns:

  • (Array) —

    An array of the dictionary’s keys, in the order they would be in if the dictionary were sorted by its values using cmptr.

- (Array) keysSortedByValueUsingSelector(comparator)

Returns an array of the dictionary’s keys, in the order they would be in if the dictionary were sorted by its values. Pairs of dictionary values are compared using the comparison method specified by comparator; the comparator message is sent to one of the values and has as its single argument the other value from the dictionary.

Parameters:

  • comparator (Symbol) —

    A selector that specifies the method to use to compare the values in the dictionary.The comparator method should return NSOrderedAscending if the dictionary is smaller than the argument, NSOrderedDescending if the dictionary is larger than the argument, and NSOrderedSame if they are equal.

Returns:

  • (Array) —

    An array of the dictionary’s keys, in the order they would be in if the dictionary were sorted by its values.

- (Array) keysSortedByValueWithOptions(opts, usingComparator:cmptr)

Returns an array of the dictionary’s keys, in the order they would be in if the dictionary were sorted by its values using a given comparator block and a specified set of options.

Parameters:

  • opts (NSSortOptions) —

    A bitmask of sort options.

  • cmptr (NSComparator) —

    A comparator block.

Returns:

  • (Array) —

    An array of the dictionary’s keys, in the order they would be in if the dictionary were sorted by its values using cmptr with the options given in opts.

- (NSEnumerator) objectEnumerator

Returns an enumerator object that lets you access each value in the dictionary. The following code fragment illustrates how you might use the method. If you use this method with instances of mutable subclasses of NSDictionary, your code should not modify the entries during enumeration. If you intend to modify the entries, use the allValues method to create a “snapshot” of the dictionary’s values. Work from this snapshot to modify the values.

Returns:

  • (NSEnumerator) —

    An enumerator object that lets you access each value in the dictionary.

- (Object) objectForKey(aKey)

Returns the value associated with a given key.

Parameters:

  • aKey (Object) —

    The key for which to return the corresponding value.

Returns:

  • (Object) —

    The value associated with aKey, or nil if no value is associated with aKey.

- (Object) objectForKeyedSubscript(key)

Returns the value associated with a given key. This method is the same as valueForKey:.

Parameters:

  • key (Object) —

    The key for which to return the corresponding value.

Returns:

  • (Object) —

    The value associated with aKey, or nil if no value is associated with aKey.

- (Array) objectsForKeys(keys, notFoundMarker:anObject)

Returns the set of objects from the dictionary that corresponds to the specified keys as an NSArray. The objects in the returned array and the keys array have a one-for-one correspondence, so that the nthe object in the returned array corresponds to the nthe key in keys.

Parameters:

  • keys (Array) —

    An NSArray containing the keys for which to return corresponding values.

  • anObject (Object) —

    The marker object to place in the corresponding element of the returned array if an object isn’t found in the dictionary to correspond to a given key.

Returns:

- (Object) valueForKey(key)

Returns the value associated with a given key. If key does not start with “@”, invokes objectForKey:. If key does start with “@”, strips the “@” and invokes [super valueForKey:] with the rest of the key.

Parameters:

  • key (String) —

    The key for which to return the corresponding value. Note that when using key-value coding, the key must be a string (see “Key-Value Coding Fundamentals”).

Returns:

  • (Object) —

    The value associated with key.

- (Boolean) writeToFile(path, atomically:flag)

Writes a property list representation of the contents of the dictionary to a given path. This method recursively validates that all the contained objects are property list objects (instances of NSData, NSDate, NSNumber, NSString, NSArray, or NSDictionary) before writing out the file, and returns NO if all the objects are not property list objects, since the resultant file would not be a valid property list.If the dictionary’s contents are all property list objects, the file written by this method can be used to initialize a new dictionary with the class method dictionaryWithContentsOfFile: or the instance method initWithContentsOfFile:.For more information about property lists, see Property List Programming Guide.

Parameters:

  • path (String) —

    The path at which to write the file.If path contains a tilde (~) character, you must expand it with stringByExpandingTildeInPath before invoking this method.

  • flag (Boolean) —

    A flag that specifies whether the file should be written atomically.If flag is YES, the dictionary is written to an auxiliary file, and then the auxiliary file is renamed to path. If flag is NO, the dictionary is written directly to path. The YES option guarantees that path, if it exists at all, won’t be corrupted even if the system should crash during writing.

Returns:

  • (Boolean) —

    YES if the file is written successfully, otherwise NO.

- (Boolean) writeToURL(aURL, atomically:flag)

Writes a property list representation of the contents of the dictionary to a given URL. This method recursively validates that all the contained objects are property list objects (instances of NSData, NSDate, NSNumber, NSString, NSArray, or NSDictionary) before writing out the file, and returns NO if all the objects are not property list objects, since the resultant output would not be a valid property list.If the dictionary’s contents are all property list objects, the location written by this method can be used to initialize a new dictionary with the class method dictionaryWithContentsOfURL: or the instance method initWithContentsOfURL:.For more information about property lists, see Property List Programming Guide.

Parameters:

  • aURL (NSURL) —

    The URL to which to write the dictionary.

  • flag (Boolean) —

    A flag that specifies whether the output should be written atomically.If flag is YES, the dictionary is written to an auxiliary location, and then the auxiliary location is renamed to aURL. If flag is NO, the dictionary is written directly to aURL. The YES option guarantees that aURL, if it exists at all, won’t be corrupted even if the system should crash during writing. flag is ignored if aURL is of a type that cannot be written atomically.

Returns:

  • (Boolean) —

    YES if the location is written successfully, otherwise NO.