--- title: NSDictionary framework: foundation role: symbol role_heading: Class path: foundation/nsdictionary --- # NSDictionary A static collection of objects associated with unique keys. ## Declaration ```swift class NSDictionary ``` ## Mentioned in Implementing Handoff in Your App ## Overview Overview You can use this type in Swift instead of a Dictionary in cases that require reference semantics. The NSDictionary class declares the programmatic interface to objects that manage immutable associations of keys and values. For example, an interactive form could be represented as a dictionary, with the field names as keys, corresponding to user-entered 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, the term dictionary refers to any instance of one of these classes without specifying its exact class membership.) A key-value pair within a dictionary is called an entry. Each entry consists of one object that represents the key and a second object that is that key’s value. Within a dictionary, the keys are unique. That is, no two keys in a single dictionary are equal (as determined by isEqual(_:)). In general, a key can be any object (provided that it conforms to the NSCopying protocol—see below), but note that when using key-value coding the key must be a string (see Accessing Object Properties). Neither a key nor a value can be nil; if you need to represent a null value in a dictionary, you should use NSNull. NSDictionary is “toll-free bridged” with its Core Foundation counterpart, CFDictionary. See Toll-Free Bridging for more information on toll-free bridging. Creating NSDictionary Objects Using Dictionary Literals In addition to the provided initializers, such as init(objects:forKeys:), you can create an NSDictionary object using a dictionary literal. In Objective-C, the compiler generates code that makes an underlying call to the dictionaryWithObjects:forKeys:count: method. id objects[] = { someObject, @"Hello, World!", @42, someValue }; id keys[] = { @"anObject", @"helloString", @"magicNumber", @"aValue" }; NSUInteger count = sizeof(objects) / sizeof(id); NSDictionary *dictionary = [NSDictionary dictionaryWithObjects:objects forKeys:keys count:count]; Unlike dictionaryWithObjectsAndKeys: and other initializers, dictionary literals specify entries in key-value order. You should not terminate the list of objects with nil when using this literal syntax, and in fact nil is an invalid value. For more information about object literals in Objective-C, see Working with Objects in Programming with Objective-C. In Swift, the NSDictionary class conforms to the DictionaryLiteralConvertible protocol, which allows it to be initialized with dictionary literals. For more information about object literals in Swift, see Literal Expression in The Swift Programming Language (Swift 4.1). Accessing Values Using Subscripting In addition to the provided instance methods, such as object(forKey:), you can access NSDictionary values by their keys using subscripting. Enumerating Entries Using for-in Loops In addition to the provided instance methods, such as enumerateKeysAndObjects(_:), you can enumerate NSDictionary entries using for-in loops. In Objective-C, NSDictionary conforms to the NSFastEnumeration protocol. In Swift, NSDictionary conforms to the SequenceType protocol. Subclassing Notes You generally shouldn’t need to subclass NSDictionary. Custom behavior can usually be achieved through composition rather than subclassing. Methods to Override If you do need to subclass NSDictionary, take into account that it is a Class cluster. Any subclass must override the following primitive methods: init(objects:forKeys:count:) count object(forKey:) keyEnumerator() The other methods of NSDictionary operate by invoking one or more of these primitives. The non-primitive methods provide convenient ways of accessing multiple entries at once. Alternatives to Subclassing Before making a custom class of NSDictionary, investigate NSMapTable and the corresponding Core Foundation type, CFDictionary. Because NSDictionary and CFDictionary are “toll-free bridged,” you can substitute a CFDictionary object for a NSDictionary object in your code (with appropriate casting). Although they are corresponding types, CFDictionary and NSDictionary do not have identical interfaces or implementations, and you can sometimes do things with CFDictionary that you cannot easily do with NSDictionary. If the behavior you want to add supplements that of the existing class, you could write a category on NSDictionary. Keep in mind, however, that this category will be in effect for all instances of NSDictionary that you use, and this might have unintended consequences. Alternatively, you could use composition to achieve the desired behavior. ## Topics ### Creating an Empty Dictionary - [init()](foundation/nsdictionary/init().md) ### Creating a Dictionary from Objects and Keys - [init(objects:forKeys:)](foundation/nsdictionary/init(objects:forkeys:).md) - [init(objects:forKeys:count:)](foundation/nsdictionary/init(objects:forkeys:count:).md) - [init(object:forKey:)](foundation/nsdictionary/init(object:forkey:).md) ### Creating a Dictionary from Another Dictionary - [init(dictionary:)](foundation/nsdictionary/init(dictionary:)-9fw1u.md) - [init(dictionary:copyItems:)](foundation/nsdictionary/init(dictionary:copyitems:).md) - [init(dictionaryLiteral:)](foundation/nsdictionary/init(dictionaryliteral:).md) ### Creating a Dictionary from an External Source - [init(contentsOfURL:error:)](foundation/nsdictionary/init(contentsofurl:error:).md) - [init(contentsOfFile:)](foundation/nsdictionary/init(contentsoffile:).md) ### Creating a Dictionary from an NSCoder - [init(coder:)](foundation/nsdictionary/init(coder:).md) ### Creating Key Sets for Shared-Key Optimized Dictionaries - [sharedKeySet(forKeys:)](foundation/nsdictionary/sharedkeyset(forkeys:).md) ### Counting Entries - [count](foundation/nsdictionary/count.md) ### Comparing Dictionaries - [isEqual(to:)](foundation/nsdictionary/isequal(to:).md) ### Accessing Keys and Values - [allKeys](foundation/nsdictionary/allkeys.md) - [allKeys(for:)](foundation/nsdictionary/allkeys(for:).md) - [allValues](foundation/nsdictionary/allvalues.md) - [value(forKey:)](foundation/nsdictionary/value(forkey:).md) - [objects(forKeys:notFoundMarker:)](foundation/nsdictionary/objects(forkeys:notfoundmarker:).md) - [object(forKey:)](foundation/nsdictionary/object(forkey:).md) - [subscript(_:)](foundation/nsdictionary/subscript(_:)-52n56.md) - [subscript(_:)](foundation/nsdictionary/subscript(_:)-1bt1b.md) ### Enumerating Dictionaries - [keyEnumerator()](foundation/nsdictionary/keyenumerator().md) - [objectEnumerator()](foundation/nsdictionary/objectenumerator().md) - [enumerateKeysAndObjects(_:)](foundation/nsdictionary/enumeratekeysandobjects(_:).md) - [enumerateKeysAndObjects(options:using:)](foundation/nsdictionary/enumeratekeysandobjects(options:using:).md) - [makeIterator()](foundation/nsdictionary/makeiterator().md) ### Sorting Dictionaries - [keysSortedByValue(using:)](foundation/nsdictionary/keyssortedbyvalue(using:).md) - [keysSortedByValue(comparator:)](foundation/nsdictionary/keyssortedbyvalue(comparator:).md) - [keysSortedByValue(options:usingComparator:)](foundation/nsdictionary/keyssortedbyvalue(options:usingcomparator:).md) ### Filtering Dictionaries - [keysOfEntries(passingTest:)](foundation/nsdictionary/keysofentries(passingtest:).md) - [keysOfEntries(options:passingTest:)](foundation/nsdictionary/keysofentries(options:passingtest:).md) ### Storing Dictionaries - [write(to:)](foundation/nsdictionary/write(to:).md) - [write(to:atomically:)](foundation/nsdictionary/write(to:atomically:).md) - [write(toFile:atomically:)](foundation/nsdictionary/write(tofile:atomically:).md) ### Accessing File Attributes - [fileSize()](foundation/nsdictionary/filesize().md) - [fileType()](foundation/nsdictionary/filetype().md) - [fileCreationDate()](foundation/nsdictionary/filecreationdate().md) - [fileModificationDate()](foundation/nsdictionary/filemodificationdate().md) - [filePosixPermissions()](foundation/nsdictionary/fileposixpermissions().md) - [fileOwnerAccountID()](foundation/nsdictionary/fileowneraccountid().md) - [fileOwnerAccountName()](foundation/nsdictionary/fileowneraccountname().md) - [fileGroupOwnerAccountID()](foundation/nsdictionary/filegroupowneraccountid().md) - [fileGroupOwnerAccountName()](foundation/nsdictionary/filegroupowneraccountname().md) - [fileExtensionHidden()](foundation/nsdictionary/fileextensionhidden().md) - [fileIsImmutable()](foundation/nsdictionary/fileisimmutable().md) - [fileIsAppendOnly()](foundation/nsdictionary/fileisappendonly().md) - [fileSystemFileNumber()](foundation/nsdictionary/filesystemfilenumber().md) - [fileSystemNumber()](foundation/nsdictionary/filesystemnumber().md) - [fileHFSTypeCode()](foundation/nsdictionary/filehfstypecode().md) - [fileHFSCreatorCode()](foundation/nsdictionary/filehfscreatorcode().md) ### Describing a Dictionary - [description](foundation/nsdictionary/description.md) - [descriptionInStringsFileFormat](foundation/nsdictionary/descriptioninstringsfileformat.md) - [description(withLocale:)](foundation/nsdictionary/description(withlocale:).md) - [description(withLocale:indent:)](foundation/nsdictionary/description(withlocale:indent:).md) ### Supporting Types - [NSDictionary.Iterator](foundation/nsdictionary/iterator.md) ### Initializers - [init(contentsOf:)](foundation/nsdictionary/init(contentsof:).md) - [init(contentsOf:error:)](foundation/nsdictionary/init(contentsof:error:).md) - [init(dictionary:)](foundation/nsdictionary/init(dictionary:)-4gc13.md) ### Default Implementations - [ExpressibleByDictionaryLiteral Implementations](foundation/nsdictionary/expressiblebydictionaryliteral-implementations.md) - [NSDictionary Implementations](foundation/nsdictionary/nsdictionary-implementations.md) - [Sequence Implementations](foundation/nsdictionary/sequence-implementations.md) ## Relationships ### Inherits From - [NSObject](objectivec/nsobject-swift.class.md) ### Inherited By - [NSMutableDictionary](foundation/nsmutabledictionary.md) ### Conforms To - [CVarArg](swift/cvararg.md) - [Copyable](swift/copyable.md) - [CustomDebugStringConvertible](swift/customdebugstringconvertible.md) - [CustomReflectable](swift/customreflectable.md) - [CustomStringConvertible](swift/customstringconvertible.md) - [Equatable](swift/equatable.md) - [Escapable](swift/escapable.md) - [ExpressibleByDictionaryLiteral](swift/expressiblebydictionaryliteral.md) - [Hashable](swift/hashable.md) - [NSCoding](foundation/nscoding.md) - [NSCopying](foundation/nscopying.md) - [NSFastEnumeration](foundation/nsfastenumeration.md) - [NSFetchRequestResult](coredata/nsfetchrequestresult.md) - [NSMutableCopying](foundation/nsmutablecopying.md) - [NSObjectProtocol](objectivec/nsobjectprotocol.md) - [NSSecureCoding](foundation/nssecurecoding.md) - [Sequence](swift/sequence.md)