mccallum@gnu.ai.mit.edu
)fedor@boulder.colorado.edu
)Version: 27209
Date: 2008-12-04 18:04:00 +0000 (Thu, 04 Dec 2008)
Copyright: (C) 1995, 1996, 1997 Free Software Foundation, Inc.
- Declared in:
- Foundation/NSDictionary.h
- Conforms to:
- NSCoding
- NSCopying
- NSMutableCopying
This class and its subclasses store key-value pairs, where the key and the value are objects. A great many utility methods for working with dictionaries are provided as part of this class, including the ability to retrieve multiple entries simultaneously, obtain sorted contents, and read/write from/to a serialized representation.
The keys are copied and values are retained by the
implementation, and both are released when
either their entry is dropped or the entire
dictionary is deallocated.
As in the OS X
implementation, keys must therefore
implement the
<NSCopying>
protocol.
Objects of this class are immutable. For a mutable version, use the NSMutableDictionary subclass.
The basic functionality in
NSDictionary
is similar to that in
Java's HashMap
, and like that class
it includes no locking code and is not thread-safe.
If the contents will be modified and accessed from
multiple threads you should enclose critical
operations within locks (see
NSLock
).
nil
. Thus, the
list's length must be even, followed by
nil
.
nil
locale and zero indent.
nil
, no formatting is done, otherwise
entries are formatted according to the
locale, and indented according to
level. nil
, a level of zero indents
items by four spaces, while a level of one
indents them by a tab. In MacOS-X class clusters do not have designated initialisers, and there is a general rule that -init is treated as the designated initialiser of the class cluster, but that other intitialisers may not work s expected an would need to be individually overridden in any subclass.
GNUstep tries to make it easier to subclass a class cluster, by making class clusters follow the same convention as normal classes, so the designated initialiser is the richest initialiser. This means that all other initialisers call the documented designated initialiser (which calls -init only for MacOS-X compatibility), and anyone writing a subclass only needs to override that one initialiser in order to have all the other ones work.
For MacOS-X compatibility, you may also need to override various other initialisers. Exactly which ones, you will need to determine by trial on a MacOS-X system... and may vary between releases of MacOS-X. So to be safe, on MacOS-X you probably need to re-implement all the class cluster initialisers you might use in conjunction with your subclass.
Initialises the dictionary with the contents of the specified file, which must contain a dictionary in property-list format.
In GNUstep, the property-list format may be either the OpenStep format (ASCII data), or the MacOS-X format (UTF-8 XML data)... this method will recognise which it is.
If there is a failure to load the file for any reason,
the receiver will be released and the method will
return nil
.
Works by invoking [NSString -initWithContentsOfFile:] and [NSString -propertyList] then checking that the result is a dictionary.
Initialises the dictionary with the contents of the specified URL, which must contain a dictionary in property-list format.
In GNUstep, the property-list format may be either the OpenStep format (ASCII data), or the MacOS-X format (UTF-8 XML data)... this method will recognise which it is.
If there is a failure to load the URL for any reason,
the receiver will be released and the method will
return nil
.
Works by invoking [NSString -initWithContentsOfURL:] and [NSString -propertyList] then checking that the result is a dictionary.
YES
then the values are copied into the
newly initialised dictionary, otherwise they are
simply retained, on the assumption that it is safe
to retain the keys from another dictionary since that
other dictionary mwill have copied the
keys originally to ensure that they are immutable.
nil
.
Thus, the list's length must be even, followed by
nil
.
isEqual
to a key in the
other, and, for a given key, the
corresponding value objects also satisfy
isEqual
.
[a comp: b]
. The comp method
should return NSOrderedSame
,
NSOrderedAscending
, or
NSOrderedDescending
as appropriate.
nil
if the key is
not present.
nil
if there is no
value. Writes the contents of the dictionary to the file specified by path. The file contents will be in property-list format... under GNUstep this is either OpenStep style (ASCII characters using \U hexadecimal escape sequences for unicode), or MacOS-X style (XML in the UTF8 character set).
If the useAuxiliaryFile flag is
YES
, the file write operation is
atomic... the data is written to a temporary file,
which is then renamed to the actual file name.
If the conversion of data into the correct
property-list format fails or the write
operation fails, the method returns
NO
, otherwise it returns
YES
.
NB. The fact that the file is in property-list format does not necessarily mean that it can be used to reconstruct the dictionary using the -initWithContentsOfFile: method. If the original dictionary contains non-property-list objects, the descriptions of those objects will have been written, and reading in the file as a property-list will result in a new dictionary containing the string descriptions.
Writes the contents of the dictionary to the specified url. This functions just like -writeToFile:atomically: except that the output may be written to any URL, not just a local file.
- Declared in:
- Foundation/NSDictionary.h
nil
.
nil
, although a console warning is produced in the latter
case.
nil
,
an exception is raised. If aKey already in
dictionary, the value it maps to is silently
replaced. The value anObject is
retained, but aKey is copied (because
a dictionary key must be immutable) and must therefore
implement the
<NSCopying>
protocol.)
nil
,
in which case it is equivalent to
-removeObjectForKey:
nil
,
in which case it is equivalent to
-removeObjectForKey:
nil
,
in which case it is equivalent to
-removeObjectForKey: