plist::Dictionary Class Reference
#include <plistCollections.h>
Inheritance diagram for plist::Dictionary:
Detailed Description
Maintains a set of (key,value) pairs, where a value can be any subclass of ObjectBase.This class supports callbacks upon modification through the use of the CollectionListener interface. Note that we only store a pointer to the listener list, which is typically unallocated when no listeners are active. This should ensure minimal memory usage per object, as well as support safe storage of plist objects in inter-process shared memory regions.
If you are using these in a shared memory region, just be sure that only the process with listeners does any and all modifications, and that it unsubscribes before detaching from the region (or else destroys the region itself)
There isn't a callback if entries themselves are modified, only when new entries are added, or old ones removed. If you want to know any time any aspect of any entry is modified, listen for the add and remove callbacks, and then add yourself as a listener to each entry individually.
Definition at line 115 of file plistCollections.h.
Public Types | |
| typedef std::map< std::string, ObjectBase * > | storage_t |
| shorthand for the type of the storage | |
| typedef storage_t::iterator | iterator |
| shorthand for iterators to be returned | |
| typedef storage_t::const_iterator | const_iterator |
| shorthand for iterators to be returned | |
Public Member Functions | |
| Dictionary () | |
| constructor | |
| Dictionary (bool growable) | |
| constructor | |
| Dictionary (const Dictionary &d) | |
| copy constructor (don't assign listeners) | |
| Dictionary & | operator= (const Dictionary &d) |
| assignment (don't assign listeners); subclass should call fireEntriesChanged after calling this (and updating its own storage) | |
| ~Dictionary () | |
| destructor | |
| template<typename T> | |
| void | setValue (const std::string &name, const T &val, bool warnExists=false) |
| insert a new entry to the map; expects val to be either a primitive type, like int, float, etc., or one of the variable-sized Collection's, like Vector | |
| template<typename T> | |
| void | addValue (const std::string &name, const T &val, const std::string &comment="", bool warnExists=true) |
| insert a new entry to the map, and corresponding comment; expects val to be either a primitive type, like int, float, etc., or one of the variable-sized Collection's, like Vector | |
| virtual void | setValue (const std::string &name, const char val[], bool warnExists=false) |
| "specialization" (actually just another override) for handling character arrays as strings | |
| virtual void | addValue (const std::string &name, const char val[], const std::string &comment="") |
| "specialization" (actually just another override) for handling character arrays as strings | |
| virtual void | addValue (const std::string &name, const char val[], const std::string &comment, bool warnExists) |
| "specialization" (actually just another override) for handling character arrays as strings | |
| virtual void | setEntry (const std::string &name, ObjectBase &val, bool warnExists=false) |
| insert a new entry to the dictionary, with key name and value val (replaces any previous entry by same name, but can give a warning) | |
| virtual void | addEntry (const std::string &name, ObjectBase &val, const std::string &comment="") |
| insert a new entry to the dictionary, with key name and value val (replaces any previous entry by same name, but can give a warning) | |
| virtual void | addEntry (const std::string &name, ObjectBase &val, const std::string &comment, bool warnExists) |
| insert a new entry to the dictionary, with key name and value val (replaces any previous entry by same name, but can give a warning) | |
| virtual void | setEntry (const std::string &name, ObjectBase *val, bool warnExists=false) |
| insert a new entry to the dictionary, with key name and value val, control of deallocation given to collection | |
| virtual void | addEntry (const std::string &name, ObjectBase *val, const std::string &comment="") |
| insert a new entry to the dictionary, with key name and value val, control of deallocation given to collection | |
| virtual void | addEntry (const std::string &name, ObjectBase *val, const std::string &comment, bool warnExists) |
| insert a new entry to the dictionary, with key name and value val (replaces any previous entry by same name, but can give a warning) | |
| virtual void | removeEntry (const std::string &name) |
| remove the entry with key name | |
| virtual ObjectBase * | getEntry (const std::string &name) const |
| return the value of the key name, or NULL if it doesn't exist | |
| virtual void | clear () |
| remove all entries in one fell swoop | |
| const_iterator | begin () const |
| return an STL const_iterator to the first entry | |
| const_iterator | end () const |
| return the one-past-end const_iterator | |
| size_t | size () const |
| return the size of the dictionary | |
| void | setComment (const std::string &name, const std::string &comment) |
| replaces previous comment for name, or adds it if it doesn't already exist (can preceed actual entry!) | |
| const std::string & | getComment (const std::string &name) const |
| returns comment retrieved from loaded file, or any subsequent call to setComment | |
| virtual void | loadXML (xmlNode *node) |
| From the name of node, will instantiate a new ObjectBase subclass to load it. | |
| virtual void | saveXML (xmlNode *node) const |
| subclasses are expected to provide a working implementation | |
| virtual std::string | toString () const |
| return current value as a string | |
| virtual Dictionary * | clone () const __attribute__((warn_unused_result)) |
| implements the clone function for Dictionaries | |
| template<> | |
| void | setValue (const std::string &name, const ObjectBase &val, bool warnExists) |
| specialization of Dictionary::setValue() for ObjectBase subclasses | |
| template<> | |
| void | addValue (const std::string &name, const ObjectBase &val, const std::string &comment, bool warnExists) |
| specialization of Dictionary::addValue() for ObjectBase subclasses | |
| template<> | |
| void | setValue (const std::string &name, const char *const &val, bool warnExists) |
| specialization of Dictionary::setValue() for char* strings | |
| template<> | |
| void | addValue (const std::string &name, const char *const &val, const std::string &comment, bool warnExists) |
| specialization of Dictionary::addValue() for char* strings | |
| template<> | |
| void | setValue (const std::string &name, char *const &val, bool warnExists) |
| specialization of Dictionary::setValue() for char* strings | |
| template<> | |
| void | addValue (const std::string &name, char *const &val, const std::string &comment, bool warnExists) |
| specialization of Dictionary::addValue() for char* strings | |
Protected Types | |
| typedef std::map< std::string, std::string > | comments_t |
| shorthand for the type of comments | |
Protected Member Functions | |
| virtual void | fireEntryRemoved (ObjectBase &val) |
| run through collectionListeners, calling CollectionListener::plistCollectionEntryRemoved(*this,val) | |
| virtual void | takeObject (const std::string &name, ObjectBase *obj) |
| indicates that the storage implementation should mark this as an externally supplied heap reference, which needs to be deleted on removal/destruction | |
| virtual bool | loadXMLNode (const std::string &key, xmlNode *val, const std::string &comment) |
| called with each node being loaded so subclass can handle appropriately | |
| virtual unsigned int | getLongestKeyLen () const |
| return the length of the longest key for formatting purposes | |
| iterator | getSubEntry (const std::string &name, std::string::size_type &seppos) |
| returns an entry matching just the prefix | |
| const_iterator | getSubEntry (const std::string &name, std::string::size_type &seppos) const |
| returns an entry matching just the prefix | |
| virtual void | cloneMyRef () |
| called after an assignment or copy to clone the objects in myRef to perform a deep copy | |
Protected Attributes | |
| storage_t | dict |
| storage of entries -- mapping from keys to value pointers | |
| std::set< ObjectBase * > | myRef |
| objects which have been handed over to the collection for eventual de-allocation | |
| comments_t | comments |
| storage of entry comments -- mapping from keys to help text comments for manual editing or user feedback | |
Friends | |
| std::ostream & | operator<< (std::ostream &os, const Dictionary &d) |
| provides textual output | |
Member Typedef Documentation
typedef std::map<std::string,std::string> plist::Dictionary::comments_t [protected] |
| typedef storage_t::const_iterator plist::Dictionary::const_iterator |
| typedef storage_t::iterator plist::Dictionary::iterator |
| typedef std::map<std::string,ObjectBase*> plist::Dictionary::storage_t |
Constructor & Destructor Documentation
| plist::Dictionary::Dictionary | ( | ) | [inline] |
| plist::Dictionary::Dictionary | ( | bool | growable | ) | [inline, explicit] |
| plist::Dictionary::Dictionary | ( | const Dictionary & | d | ) | [inline] |
| plist::Dictionary::~Dictionary | ( | ) | [inline] |
Member Function Documentation
| void plist::Dictionary::addEntry | ( | const std::string & | name, | |
| ObjectBase * | val, | |||
| const std::string & | comment, | |||
| bool | warnExists | |||
| ) | [virtual] |
insert a new entry to the dictionary, with key name and value val (replaces any previous entry by same name, but can give a warning)
Definition at line 164 of file plistCollections.cc.
| virtual void plist::Dictionary::addEntry | ( | const std::string & | name, | |
| ObjectBase * | val, | |||
| const std::string & | comment = "" | |||
| ) | [inline, virtual] |
insert a new entry to the dictionary, with key name and value val, control of deallocation given to collection
Implements plist::Collection.
Definition at line 156 of file plistCollections.h.
| void plist::Dictionary::addEntry | ( | const std::string & | name, | |
| ObjectBase & | val, | |||
| const std::string & | comment, | |||
| bool | warnExists | |||
| ) | [virtual] |
insert a new entry to the dictionary, with key name and value val (replaces any previous entry by same name, but can give a warning)
Definition at line 107 of file plistCollections.cc.
| virtual void plist::Dictionary::addEntry | ( | const std::string & | name, | |
| ObjectBase & | val, | |||
| const std::string & | comment = "" | |||
| ) | [inline, virtual] |
insert a new entry to the dictionary, with key name and value val (replaces any previous entry by same name, but can give a warning)
Implements plist::Collection.
Definition at line 152 of file plistCollections.h.
Referenced by addValue(), and loadXMLNode().
| void plist::Dictionary::addValue | ( | const std::string & | name, | |
| char *const & | val, | |||
| const std::string & | comment, | |||
| bool | warnExists | |||
| ) | [inline] |
specialization of Dictionary::addValue() for char* strings
Definition at line 407 of file plistCollections.h.
| void plist::Dictionary::addValue | ( | const std::string & | name, | |
| const char *const & | val, | |||
| const std::string & | comment, | |||
| bool | warnExists | |||
| ) | [inline] |
specialization of Dictionary::addValue() for char* strings
Definition at line 401 of file plistCollections.h.
| void plist::Dictionary::addValue | ( | const std::string & | name, | |
| const ObjectBase & | val, | |||
| const std::string & | comment, | |||
| bool | warnExists | |||
| ) | [inline] |
specialization of Dictionary::addValue() for ObjectBase subclasses
Definition at line 395 of file plistCollections.h.
| virtual void plist::Dictionary::addValue | ( | const std::string & | name, | |
| const char | val[], | |||
| const std::string & | comment, | |||
| bool | warnExists | |||
| ) | [inline, virtual] |
"specialization" (actually just another override) for handling character arrays as strings
Definition at line 147 of file plistCollections.h.
| virtual void plist::Dictionary::addValue | ( | const std::string & | name, | |
| const char | val[], | |||
| const std::string & | comment = "" | |||
| ) | [inline, virtual] |
"specialization" (actually just another override) for handling character arrays as strings
Definition at line 145 of file plistCollections.h.
| void plist::Dictionary::addValue | ( | const std::string & | name, | |
| const T & | val, | |||
| const std::string & | comment = "", |
|||
| bool | warnExists = true | |||
| ) | [inline] |
insert a new entry to the map, and corresponding comment; expects val to be either a primitive type, like int, float, etc., or one of the variable-sized Collection's, like Vector
Definition at line 141 of file plistCollections.h.
| const_iterator plist::Dictionary::begin | ( | ) | const [inline] |
return an STL const_iterator to the first entry
Definition at line 168 of file plistCollections.h.
Referenced by getLongestKeyLen(), and loadXML().
| void plist::Dictionary::clear | ( | ) | [virtual] |
remove all entries in one fell swoop
Implements plist::Collection.
Definition at line 913 of file plistCollections.cc.
| Dictionary * plist::Dictionary::clone | ( | ) | const [virtual] |
implements the clone function for Dictionaries
Implements plist::ObjectBase.
Definition at line 450 of file plistCollections.cc.
| void plist::Dictionary::cloneMyRef | ( | ) | [protected, virtual] |
called after an assignment or copy to clone the objects in myRef to perform a deep copy
Definition at line 934 of file plistCollections.cc.
| const_iterator plist::Dictionary::end | ( | ) | const [inline] |
return the one-past-end const_iterator
Definition at line 170 of file plistCollections.h.
Referenced by getLongestKeyLen(), and loadXML().
| void plist::Dictionary::fireEntryRemoved | ( | ObjectBase & | val | ) | [protected, virtual] |
run through collectionListeners, calling CollectionListener::plistCollectionEntryRemoved(*this,val)
Reimplemented from plist::Collection.
Definition at line 925 of file plistCollections.cc.
Referenced by removeEntry().
| const std::string & plist::Dictionary::getComment | ( | const std::string & | name | ) | const [virtual] |
returns comment retrieved from loaded file, or any subsequent call to setComment
Implements plist::Collection.
Definition at line 257 of file plistCollections.cc.
| ObjectBase * plist::Dictionary::getEntry | ( | const std::string & | name | ) | const [virtual] |
return the value of the key name, or NULL if it doesn't exist
Implements plist::Collection.
Definition at line 219 of file plistCollections.cc.
| unsigned int plist::Dictionary::getLongestKeyLen | ( | ) | const [protected, virtual] |
return the length of the longest key for formatting purposes
Implements plist::Collection.
Definition at line 452 of file plistCollections.cc.
| Dictionary::const_iterator plist::Dictionary::getSubEntry | ( | const std::string & | name, | |
| std::string::size_type & | seppos | |||
| ) | const [protected] |
returns an entry matching just the prefix
- Parameters:
-
[in] name the name being looked up [out] seppos the position of the separator (sub-collections are separated by '.')
- Returns:
- iterator of the sub entry
Definition at line 476 of file plistCollections.cc.
| Dictionary::iterator plist::Dictionary::getSubEntry | ( | const std::string & | name, | |
| std::string::size_type & | seppos | |||
| ) | [protected] |
returns an entry matching just the prefix
- Parameters:
-
[in] name the name being looked up [out] seppos the position of the separator (sub-collections are separated by '.')
- Returns:
- iterator of the sub entry
Definition at line 464 of file plistCollections.cc.
Referenced by addEntry(), getComment(), getEntry(), removeEntry(), setComment(), and setEntry().
| void plist::Dictionary::loadXML | ( | xmlNode * | node | ) | [virtual] |
From the name of node, will instantiate a new ObjectBase subclass to load it.
The mapping from node names to actual instantiated types is:
- 'array' -> Vector
- 'dict' -> Map
- 'real' -> Primitive<double>
- 'integer' -> Primitive<long>
- 'string' -> Primitive<std::string>
- 'true', 'false' -> Primitive<bool>
If successful, returns a pointer to a newly allocated region, which the caller is responsible for freeing. If an error occurs, NULL is returned.
Reimplemented from plist::ObjectBase.
Definition at line 276 of file plistCollections.cc.
| bool plist::Dictionary::loadXMLNode | ( | const std::string & | key, | |
| xmlNode * | val, | |||
| const std::string & | comment | |||
| ) | [protected, virtual] |
called with each node being loaded so subclass can handle appropriately
Definition at line 1017 of file plistCollections.cc.
Referenced by loadXML().
| Dictionary& plist::Dictionary::operator= | ( | const Dictionary & | d | ) | [inline] |
assignment (don't assign listeners); subclass should call fireEntriesChanged after calling this (and updating its own storage)
Definition at line 132 of file plistCollections.h.
| void plist::Dictionary::removeEntry | ( | const std::string & | name | ) | [virtual] |
remove the entry with key name
Implements plist::Collection.
Definition at line 200 of file plistCollections.cc.
Referenced by addEntry(), loadXML(), loadXMLNode(), and setEntry().
| void plist::Dictionary::saveXML | ( | xmlNode * | node | ) | const [virtual] |
subclasses are expected to provide a working implementation
Implements plist::ObjectBase.
Definition at line 317 of file plistCollections.cc.
| void plist::Dictionary::setComment | ( | const std::string & | name, | |
| const std::string & | comment | |||
| ) | [virtual] |
replaces previous comment for name, or adds it if it doesn't already exist (can preceed actual entry!)
Implements plist::Collection.
Definition at line 238 of file plistCollections.cc.
Referenced by loadXMLNode().
| void plist::Dictionary::setEntry | ( | const std::string & | name, | |
| ObjectBase * | val, | |||
| bool | warnExists = false | |||
| ) | [virtual] |
insert a new entry to the dictionary, with key name and value val, control of deallocation given to collection
Implements plist::Collection.
Definition at line 136 of file plistCollections.cc.
| void plist::Dictionary::setEntry | ( | const std::string & | name, | |
| ObjectBase & | val, | |||
| bool | warnExists = false | |||
| ) | [virtual] |
insert a new entry to the dictionary, with key name and value val (replaces any previous entry by same name, but can give a warning)
Implements plist::Collection.
Definition at line 80 of file plistCollections.cc.
Referenced by setValue().
| void plist::Dictionary::setValue | ( | const std::string & | name, | |
| char *const & | val, | |||
| bool | warnExists | |||
| ) | [inline] |
specialization of Dictionary::setValue() for char* strings
Definition at line 404 of file plistCollections.h.
| void plist::Dictionary::setValue | ( | const std::string & | name, | |
| const char *const & | val, | |||
| bool | warnExists | |||
| ) | [inline] |
specialization of Dictionary::setValue() for char* strings
Definition at line 398 of file plistCollections.h.
| void plist::Dictionary::setValue | ( | const std::string & | name, | |
| const ObjectBase & | val, | |||
| bool | warnExists | |||
| ) | [inline] |
specialization of Dictionary::setValue() for ObjectBase subclasses
Definition at line 392 of file plistCollections.h.
| virtual void plist::Dictionary::setValue | ( | const std::string & | name, | |
| const char | val[], | |||
| bool | warnExists = false | |||
| ) | [inline, virtual] |
"specialization" (actually just another override) for handling character arrays as strings
Definition at line 143 of file plistCollections.h.
| void plist::Dictionary::setValue | ( | const std::string & | name, | |
| const T & | val, | |||
| bool | warnExists = false | |||
| ) | [inline] |
insert a new entry to the map; expects val to be either a primitive type, like int, float, etc., or one of the variable-sized Collection's, like Vector
Definition at line 138 of file plistCollections.h.
| size_t plist::Dictionary::size | ( | ) | const [inline] |
return the size of the dictionary
Definition at line 172 of file plistCollections.h.
Referenced by loadXML().
| void plist::Dictionary::takeObject | ( | const std::string & | name, | |
| ObjectBase * | obj | |||
| ) | [protected, virtual] |
indicates that the storage implementation should mark this as an externally supplied heap reference, which needs to be deleted on removal/destruction
Definition at line 921 of file plistCollections.cc.
Referenced by addEntry(), and setEntry().
| std::string plist::Dictionary::toString | ( | ) | const [virtual] |
return current value as a string
Implements plist::ObjectBase.
Definition at line 443 of file plistCollections.cc.
Friends And Related Function Documentation
| std::ostream& operator<< | ( | std::ostream & | os, | |
| const Dictionary & | d | |||
| ) | [friend] |
Member Data Documentation
comments_t plist::Dictionary::comments [protected] |
storage of entry comments -- mapping from keys to help text comments for manual editing or user feedback
not every key necessarily has a comment!
Definition at line 222 of file plistCollections.h.
Referenced by addEntry(), getComment(), operator=(), saveXML(), and setComment().
storage_t plist::Dictionary::dict [protected] |
storage of entries -- mapping from keys to value pointers
Definition at line 213 of file plistCollections.h.
Referenced by addEntry(), clear(), cloneMyRef(), getComment(), getEntry(), getSubEntry(), loadXMLNode(), operator=(), removeEntry(), saveXML(), setComment(), and setEntry().
std::set<ObjectBase*> plist::Dictionary::myRef [protected] |
objects which have been handed over to the collection for eventual de-allocation
Definition at line 216 of file plistCollections.h.
Referenced by clear(), cloneMyRef(), fireEntryRemoved(), operator=(), and takeObject().
The documentation for this class was generated from the following files:
