Compound list   Compound Members  

KeyValueMap Class Reference

The class KeyValueMap is used for managing key-value-pairs WITHOUT any hierarchical structure. More...

List of all members.

Public Members

Protected Members


Detailed Description

The class KeyValueMap is used for managing key-value-pairs WITHOUT any hierarchical structure.

Objects of it can be used as they are or in conjunction with the configuration database class. While the first version used the string class, this second uses the QString class. The class uses pairs of methods for each datatype, they are called get() and insert(). Every overloaded version of this methods get the key of the settings and a reference to the value to set or to store it in. A boolean result reports if there where errors or if the key already existed. Keys must of course be unique. Please note that the map does NOT store type information for the keys. You may retrieve a boolean value for a string, it will work if the string is either "true" or "false". See the different get- and insert-methods for details.

Capabilities of the class are:

  1. storing of any key-value-pair that is storable in string values (no binary objects currently),
  2. key-value-pairs are saved in human-readable text files when saving to disk,
  3. the values may contain newline and tabulator characters which will still be there after saving and rereading,
  4. supports the following datatypes:
    1. strings (of course),
    2. integers,
    3. floating point values and
    4. boolean states
  5. supports storing and retrieving of lists of values of the following datatypes:
    1. strings,
    2. integers and
    3. floating point values
    (boolean lists supported in future when requested)
  6. easy syntax of files, in general it is supposed to be a kind of guarantee (you know that free software never guarantees anything, don't you?) that every value that has been stored by one of the member functions of the class like
    insert(const QString& key, [value&]);
    can also be retrieved using
    get(const QString& key, [value&]);
    without being modified.
    (Please report anything that does not do so!)
The class is used to implement the QConfigDB class.


Member Function Documentation

KeyValueMap::KeyValueMap()

The default constructor.

KeyValueMap::KeyValueMap(const KeyValueMap&)

The copy constructor.

virtual KeyValueMap::~KeyValueMap() [virtual]

The virtual destructor.

bool KeyValueMap::invariant()

Debugging aid: returns true if object is OK.

unsigned int KeyValueMap::size() const

Returns the number of key-value-pairs in the map.

void KeyValueMap::clear()

Delete all entries.

bool KeyValueMap::fill(const QString&, bool force=false, bool relax=false)

Fills the map with the files contents.

If the parameter force is true, it overrides keys that are already declared in the database and are declared again in the file. If relax is true, the value of a string may be empty.

bool KeyValueMap::save(const QString&, bool force=false)

Saves the database to a file.

Only overrides existing files if force is true.

bool KeyValueMap::save(QTextStream& file, int count)

Saves contents to an already open text stream.

count spaces are inserted before each line. This method is called when save hierarchical databases.

See also:
QConfigDB

bool KeyValueMap::get(const QString& key, QString& value) const

Get the value for the key as a string.

key is the key to search for, \value is a reference to the object the value for the key is assigned to.

bool KeyValueMap::insert(const QString& key, const QString& value, bool force=false)

Insert a string value for the given key.

If force is true, an existing value for this key will be overridden. The method returns false if the key exists and force is false.

inline bool KeyValueMap::insert(const QString& key, const char* value, bool force=false)

Insert a character pointer for the given key.

pgcc treats character pointers as boolean objects, not as strings. If force is true, an existing value for this key will be overridden. The method returns false if the key exists and force is false.

bool KeyValueMap::insertLine(QString, bool force=false, bool relax=false, bool encode=true)

Insert a line like "key_a="Hallo!" into the map as a key-value-pair.

If force is true existing keys will be overridden. If relax is true the value may be empty an empty string. If encode is false, the string will not be coded (do not use!).

bool KeyValueMap::get(const QString&, long&) const

Get the value for the key as a long integer.

key is the key to search for, \value is a reference to the object the value for the key is assigned to.

bool KeyValueMap::insert(const QString&, const long&, bool force=false)

Insert a long integer value for the given key.

If force is true, an existing value for this key will be overridden. The method returns false if the key exists and force is false.

bool KeyValueMap::get(const QString&, double&) const

Get the value for the key as a double.

key is the key to search for, \value is a reference to the object the value for the key is assigned to.

bool KeyValueMap::insert(const QString&, const double&, bool force=false)

Insert a double value for the given key.

If force is true, an existing value for this key will be overridden. The method returns false if the key exists and force is false.

bool KeyValueMap::get(const QString&, bool&) const

Get the value for the key as a boolean value.

key is the key to search for, \value is a reference to the object the value for the key is assigned to.

bool KeyValueMap::insert(const QString&, const bool&, bool force=false)

Insert a boolean value for the given key.

If force is true, an existing value for this key will be overridden. The method returns false if the key exists and force is false.

bool KeyValueMap::get(const QString&, list<double>&) const

Get the value for the key as a list of doubles.

key is the key to search for, \value is a reference to the object the value for the key is assigned to.

bool KeyValueMap::insert(const QString&, const list<double>&, bool force=false)

Insert a list of doubles for the given key.

If force is true, an existing value for this key will be overridden. The method returns false if the key exists and force is false.

bool KeyValueMap::get(const QString&, list<double>&) const

Get the value for the key as a list of doubles.

key is the key to search for, \value is a reference to the object the value for the key is assigned to.

bool KeyValueMap::insert(const QString&, const list<double>&, bool force=false)

Insert a list of doubles for the given key.

If force is true, an existing value for this key will be overridden. The method returns false if the key exists and force is false.

bool KeyValueMap::get(const QString&, QDate &) const

Get the value for the key as a QDate.

The value will be parsed to a integer list that must be a valid date (see QDate documentation). false will be returned if the value is not valid or a null date. This situation might only happen in manually created files, since the insert-method for QDates rejects to insert inalid dates, it inserts null dates instead.

See also:
get(const QString&, QDate &)

bool KeyValueMap::insert(const QString&, const QDate&, bool force=false)

Insert a QDate for the given key.

If force is true, an existing value for this key will be overridden. The method returns false if the key exists and force is false. Attention: If you insert an invalid date a null date will be used. A null date will also be returned when retrieving this value. You will not be able to store an invalid date and retrieve it using get()!

bool KeyValueMap::get(const QString&, list<double>&) const

Get the value for the key as a list of doubles.

key is the key to search for, \value is a reference to the object the value for the key is assigned to.

bool KeyValueMap::insert(const QString&, const list<double>&, bool force=false)

Insert a list of doubles for the given key.

If force is true, an existing value for this key will be overridden. The method returns false if the key exists and force is false.

bool KeyValueMap::empty()

Returns true if there are no keys declared in this map.

bool KeyValueMap::erase(const QString& key)

Erases all key-value-pairs in the map.

bool KeyValueMap::parseComplexString(const QString& orig, int index, QString& result, int& noOfChars) const [protected]

Transform a complex string into a normal string object.

The values are not stored as they are, they are coded into complex string where control and non-printable characters get a readable representation. When retrieving, this strings are translated back by this method. orig contains the string read from the file, index the position from where to start the translation (need not be the beginning of the string), result contains the transformed string, noOfChars the number of characters used to parse the string. Returns true if there where no errors while parsing.

See also:
makeComplexString()

QString KeyValueMap::makeComplexString(const QString& orig) [protected]

Codes a normal string into a complex string.

See also:
parseComplexString()

bool KeyValueMap::insertRaw(const QString& key, const QString& value, bool force=false) [protected]

Inserts a complex string into the map.

The string must be coded already, no tests are performed. if force is false, an existing value will not be overridden.

bool KeyValueMap::getRaw(const QString& key, QString& value) const [protected]

Retrieves the undecoded value (a complex string) of the given key.


Member Data Documentation

StringStringMap* KeyValueMap::data [protected]

A map storing the key-value-pairs.


The documentation for this class was generated from the following file:

The KDE Addressbook Developers Reference 
Mirko Sucker, 1999