CXUserDefaults

alpha version, October 2000

The CXUserDefaults instances represent INI files, with default data stored into them in the Epoc CDictionaryStore format. Though, the API used here is much more convenient for application development, and it has many strong advantages over the plain CDictionaryStore services:

the particular default values are identified by a name;
any of the basic data representing objects from the XFoundation can be stored, just like some scalar values;
"default default" values can be registered, so as the getters always return a reasonable value, even when the INI file does not exist;
the INI file format is standardized enough to allow preparation of external default file editors, working for any application;
this supports using of "power user" default values, inaccessible from the application by a normal user, but easily changeable by the support people.

The key search is implemented a smart way using the hash values; thence it is quite fast: each default value is stored into a separate stream, and the stream ids are determined by a dictionary-like algorithm, whose speed is not affected by a number of key-value pairs stored into the defaults.

+CXUserDefaults *userDefaultsWithIniFileuid(CXString *fname,unsigned uid);

Makes a new object, tied to the INI file with a given name and UID. In case the file does not exist, it is automatically created.

-void registerDefaults(CXDictionary *defaults);

Register the "default default" values, ie. those, which should be used in case the requested value is not found in the INI file.

CXUserDefaults *df=[CXUserDefaults userDefaultsWithIniFile:@"somefile" uid:123456]; [df registerDefaults:[CXDictionary dictionaryWithObjectsAndKeys: @"test value",@"Test", @"12345",@"Other test", @"0",@"qqq", nil]]; XLog(@"Test=%@, Other=%d, Qqq=%s", [df stringForKey:@"Test"], [df intForKey:@"Other test"], [df boolForKey:@"qqq"]?"YES":"NO");

Supposing the INI file did not exist, or it did not contain the values for the keys used here, the XLog will write out "Test=test value, Other=12345, Qqq=NO". See also the preprocessor for a nice and easily readable syntax for making dictionaries.

-void removeObjectForKey(CXString *key);

Removes a default with the name given from the INI file.

-CXString *stringForKey(CXString *key);

Reads a string default value for the key given.

-CXData *dataForKey(CXString *key);

Reads a binary default value for the key given.

-CXArray *arrayForKey(CXString *key);

Reads an array default value for the key given.

-CXDictionary *dictionaryForKey(CXString *key);

Reads a dictionary default value for the key given.

-CXSet *setForKey(CXString *key);

Reads a set default value for the key given.

-int intForKey(CXString *key);

Reads an integer default value for the key given.

-BOOL boolForKey(CXString *key);

Reads a boolean default value for the key given.

-XRange rangeForKey(CXString *key);

Reads a range default value for the key given.

-double doubleForKey(CXString *key);

Reads a double default value for the key given.

-XTimeInterval timeIntervalForKey(CXString *key);

Reads a time interval default value for the key given.

-void setObjectforKey(id object,CXString *key);

Sets any object default value for the key given.

-void setIntforKey(int value,CXString *key);

Sets an integer default value for the key given.

-void setBoolforKey(BOOL value,CXString *key);

Sets a boolean default value for the key given.

-void setRangeforKey(XRange value,CXString *key);

Sets a range default value for the key given.

-void setDoubleforKey(double value,CXString *key);

Sets a double default value for the key given.

-void setTimeIntervalforKey(XTimeInterval value,CXString *key);

Sets a time interval default value for the key given.