CXDictionary

alpha version, October 2000

The CXDictionary represents a hash table, ie. a key-value structure organized so that a search for a key is extremely fast, and actually independent on the number of key-value pairs inside the dictionary.

Just like a CXArray or CXSet, the CXDictionary is a typeless container: you can insert any objects into it, and there is no clumsy limitation of all the contained objects to be of same type. That applies not only for the values, but for the keys as well: though in the majority of programs the keys are strings, you can index a dictionary by just anything else -- arrays, CXData objects, or even other dictionaries.

Even in the current first try implementation, the key search is pretty fast. You can freely use the dictionaries almost in any algorithm where it might come handy; the most effectivity demanding ones aside there is no fear the key search might be too slow for the application to be user-friendly.

The most generic methods of the CXDictionary are the objectForKey and setObjectforKey ones: the former just returns the value for a key given, whilst the latter adds another key-value pair into the dictionary.

Note also that currently dictionaries are mutable, ie. you can add and remove key-value pairs. That will change in future: there will be an immutable class CXDictionary, and a mutable one CXMutableDictionary--that will allow to write considerably more effective code without even thinking (like for an CXArray).

+CXDictionary *dictionaryWithObjectforKey(id obj, id key);

Returns a newly created dictionary with just one key-value pair. Both the key and value are retained. See also the preprocessor for a nice and easily readable syntax for making dictionaries.

+CXDictionary *dictionaryWithObjectsAndKeys(id obj, id key, ...);

Makes a new dictionary with any number of key-value pairs. The list is ended with a nil:

CXDictionary *dict=[CXDictionary dictionaryWithObjectsAndKeys: @"value 1",@"key 1", @"value 2",@"key 2", nil];

Note that--as the method name suggests--the order is value first, key after that. This is quite thought through, since it is quite possible you use variables for values and want to quit the creation in case one of them contains nil:

CXDictionary *dict=[CXDictionary dictionaryWithObjectsAndKeys: val1,@"key 1", val2,@"key 2", val3,@"key 2", nil];

Should the variable val2 contain nil, the dictionary will contain just one pair. It is much less probable you might want to do something alike with keys. See also the preprocessor for a nice and easily readable syntax for making dictionaries.

+CXDictionary *dictionary;

Makes a new empty dictionary.

-int count;

Returns a number of key-value pairs in the dictionary.

-CXArray *allKeys;

Makes an array with all key objects from the dictionary.

-CXArray *allKeysForObject(id obj);

Makes an array with all keys, whose values are isEqual to the object given as an argument.

-CXArray *allKeysForObjectIdenticalTo(id obj);

Like the previous one, but instead of equality the objects are directly compared.

-CXArray *allValues;

Makes an array with all the values from the dictionary.

-CXEnumerator *keyEnumerator;

Returns an enumerator to go thru all the dictionary keys:

CXDictionary *dict=...; // log out all the key/value pairs CXEnumerator *en=[dict keyEnumerator]; id o; while ((o=[en nextObject])) XLog(@"key=%@, value=%@",o,[dict objectForKey:o]);

Incidentally, you can log out the whole dictionary using just an XLog(@"%@",dict); just like with any other XSdk object.

-CXEnumerator *objectEnumerator;

Returns an enumerator to go thru all the dictionary values.

-id objectForKey(id key);

Returns a value for the key given, or nil in case there is no value for the key in the dictionary.

-CXArray *objectsForKeys(CXArray *keys,id notFoundMarker=nil);

Makes an array with values for all the keys given in the array keys. In case some of the keys are not found, the notFoundMarker is used for the appropriate value, or is just skipped in case the notFoundMarker is nil.

Mutable dictionaries

Cutrrently, all the CXDictionary instances are mutable, ie. you can freely add and remove key-value pairs to them. Though, just like with the CXArray, this is subject to change.

-void addEntriesFromDictionary(CXDictionary *dict);

Adds all the key-value pairs from the dictionary given in the argument.

-void removeAllObjects;

Empties the dictionary.

-void removeObjectForKey(id key);

Removes the key-value pair with the key given. Does nothing in case the key is not in the dictionary.

-void removeObjectsForKeys(CXArray *keys);

Removes all the key-value pairs for all the keys given in the array.

-void setObjectforKey(id value,id key);

Adds a key-value pair to the dictionary; both the key and value are retained. In case there already was a key-value pair for the same key there, the old value is released and the new one replaces it.

-void setKeyAndObject(id key,id value);

Just another name for the very same service.