Tekkotsu Homepage
Demos
Overview
Downloads
Dev. Resources
Reference
Credits

plist::DictionaryBase Class Reference

#include <plistCollections.h>

Inheritance diagram for plist::DictionaryBase:

List of all members.


Detailed Description

Maintains a set of (key,value) pairs, see DictionaryOf, and the Dictionary typedef.

You can add or set entries by a quite a few variations on addEntry(), setEntry(), or addValue(). Basically these boil down to either:

  • pass a pointer to an ObjectBase or directly pass a primitive value (int, float, char, etc.), in which case the dictionary will assume management of the corresponding ObjectBase instance (freeing the memory region when removed)
  • pass a reference to an ObjectBase, in which case you retain control over the object's allocation

Definition at line 177 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

virtual bool removeEntry (const std::string &name)
 remove the entry with key name, returns true if something was actually removed (if false, wasn't there to begin with)
virtual bool renameEntry (const std::string &oldname, const std::string &newname)
 change the key for an entry from oldname to newname, returns false if oldname didn't exist (thus no change was made)
virtual bool swapEntry (const std::string &a, const std::string &b)
 exchange the values for a pair of keys -- if either key doesn't exist, forwards call to renameEntry()
virtual ObjectBasegetEntry (const std::string &name)=0
 returns a reference to the entry with the specified name, creating it if it doesn't exist
virtual ObjectBaseoperator[] (const std::string &name)=0
 returns a reference to the entry with the specified name, creating it if it doesn't exist
virtual ObjectBaseresolveEntry (const std::string &path) const
 returns a pointer to entry with the specified 'path', which may recurse through sub-collections
const_iterator findEntry (const std::string &name) const
 returns an iterator to an entry in the current dictionary
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
virtual 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 void saveXML (xmlNode *node, bool onlyOverwrite, std::set< std::string > &seen) const
 saves the dictionary into the specified node
virtual std::string toString () const
 return current value as a string
virtual unsigned int getLongestKeyLen (const regex_t *reg=NULL, unsigned int depth=-1) const
 returns the length of the longest key, subject to an optional regular expression and max depth
bool ownsReference (ObjectBase *val) const
 returns true if the specified object will be deallocated when removed from the dictionary

Protected Types

typedef std::map< std::string,
std::string > 
comments_t
 shorthand for the type of comments

Protected Member Functions

 DictionaryBase (bool growable)
 constructor
 DictionaryBase (const DictionaryBase &d)
 copy constructor (don't assign listeners)
DictionaryBaseoperator= (const DictionaryBase &d)
 assignment (don't assign listeners)
 ~DictionaryBase ()
 destructor
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 void fireEntryRemoved (ObjectBase &val)
 run through collectionListeners, calling CollectionListener::plistCollectionEntryRemoved(*this,val)
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
virtual bool loadXMLNode (const std::string &key, xmlNode *val, const std::string &comment)=0
 called with each node being loaded so subclass can handle appropriately
virtual bool saveOverXMLNode (xmlNode *k, xmlNode *val, const std::string &key, std::string comment, const std::string &indentStr, std::set< std::string > &seen) const
 called with each node being saved so subclass can handle appropriately, return true if successful and reset key if changed
virtual void saveXMLNode (xmlNode *node, const std::string &key, const ObjectBase *val, const std::string &indentStr) const
 called with each node being saved so subclass can handle appropriately, return true if successful and set key

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 DictionaryBase &d)
 provides textual output

Classes

struct  ConversionTo
 This conversion policy accepts entries of the specified template type, and will try to create new instances of that type constructed from any values which are passed. More...
struct  DeniedValueConversions
 Indicates that no value conversions are allowed. More...
struct  EntryConstraint
 This base conversion policy doesn't actually specify any conversions at all -- this serves as a base class to provide the ability to directly add entries of the specified type; the subclasses will add value conversions. More...
struct  IntegerConversion
 Abstract base class to test whether the collection will accept integers (possibly converting to another value type, or storing directly as a [unsigned] long depending on concrete type). More...
struct  RealConversion
 Abstract base class to test whether the collection will accept floating point numbers (possibly converting to another value type, or storing directly as a double depending on concrete type). More...
struct  StringConversion
 Abstract base class to test whether the collection will accept strings (possibly converting to a value type, or storing directly as string depending on concrete type). More...
struct  WrapValueConversion
 This conversion policy accepts any entries of the specified template type, values will be directly wrapped as Primitives so no conversion at all is actually performed. More...

Member Typedef Documentation

typedef std::map<std::string,ObjectBase*> plist::DictionaryBase::storage_t

shorthand for the type of the storage

Reimplemented in plist::DictionaryOf< PO, Alloc >, and plist::DictionaryOf< ObjectBase >.

Definition at line 181 of file plistCollections.h.

typedef storage_t::iterator plist::DictionaryBase::iterator

shorthand for iterators to be returned

Reimplemented in InstanceTracker< FamilyT, ClassNameT, FactoryBaseT, FactoryT >.

Definition at line 183 of file plistCollections.h.

typedef storage_t::const_iterator plist::DictionaryBase::const_iterator

shorthand for iterators to be returned

Reimplemented in InstanceTracker< FamilyT, ClassNameT, FactoryBaseT, FactoryT >.

Definition at line 185 of file plistCollections.h.

typedef std::map<std::string,std::string> plist::DictionaryBase::comments_t [protected]

shorthand for the type of comments

Definition at line 383 of file plistCollections.h.


Constructor & Destructor Documentation

plist::DictionaryBase::DictionaryBase ( bool  growable  )  [inline, explicit, protected]

constructor

Definition at line 339 of file plistCollections.h.

plist::DictionaryBase::DictionaryBase ( const DictionaryBase d  )  [inline, protected]

copy constructor (don't assign listeners)

Definition at line 341 of file plistCollections.h.

plist::DictionaryBase::~DictionaryBase (  )  [inline, protected]

destructor

Definition at line 346 of file plistCollections.h.


Member Function Documentation

bool plist::DictionaryBase::removeEntry ( const std::string &  name  )  [virtual]

bool plist::DictionaryBase::renameEntry ( const std::string &  oldname,
const std::string &  newname 
) [virtual]

change the key for an entry from oldname to newname, returns false if oldname didn't exist (thus no change was made)

If the collection owns the reference to the object, you have to use this function instead of a pair of calls to removeEntry/addEntry, otherwise you will wind up with an invalid pointer!

Definition at line 122 of file plistCollections.cc.

Referenced by swapEntry().

bool plist::DictionaryBase::swapEntry ( const std::string &  a,
const std::string &  b 
) [virtual]

exchange the values for a pair of keys -- if either key doesn't exist, forwards call to renameEntry()

returns true if the swap was successful, only returns false if both keys are invalid

Definition at line 158 of file plistCollections.cc.

virtual ObjectBase& plist::DictionaryBase::getEntry ( const std::string &  name  )  [pure virtual]

returns a reference to the entry with the specified name, creating it if it doesn't exist

Implemented in OutputConfig< T >, plist::DictionaryOf< PO, Alloc >, OutputConfig< plist::Primitive< float > >, and plist::DictionaryOf< ObjectBase >.

virtual ObjectBase& plist::DictionaryBase::operator[] ( const std::string &  name  )  [pure virtual]

returns a reference to the entry with the specified name, creating it if it doesn't exist

Implemented in plist::DictionaryOf< PO, Alloc >, and plist::DictionaryOf< ObjectBase >.

ObjectBase * plist::DictionaryBase::resolveEntry ( const std::string &  path  )  const [virtual]

returns a pointer to entry with the specified 'path', which may recurse through sub-collections

Implements plist::Collection.

Definition at line 193 of file plistCollections.cc.

Referenced by Config::parseLine(), Controller::setConfig(), and Config::setValue().

const_iterator plist::DictionaryBase::findEntry ( const std::string &  name  )  const [inline]

returns an iterator to an entry in the current dictionary

Reimplemented in plist::DictionaryOf< PO, Alloc >, and plist::DictionaryOf< ObjectBase >.

Definition at line 303 of file plistCollections.h.

Referenced by saveOverXMLNode().

void plist::DictionaryBase::clear (  )  [virtual]

remove all entries in one fell swoop

Implements plist::Collection.

Definition at line 393 of file plistCollections.cc.

Referenced by plist::ArrayBase::~ArrayBase(), and ~DictionaryBase().

const_iterator plist::DictionaryBase::begin (  )  const [inline]

return an STL const_iterator to the first entry

Reimplemented in plist::DictionaryOf< PO, Alloc >, and plist::DictionaryOf< ObjectBase >.

Definition at line 308 of file plistCollections.h.

Referenced by getLongestKeyLen(), loadXML(), and plist::DictionaryOf< PO, Alloc >::set().

const_iterator plist::DictionaryBase::end (  )  const [inline]

return the one-past-end const_iterator

Reimplemented in plist::DictionaryOf< PO, Alloc >, and plist::DictionaryOf< ObjectBase >.

Definition at line 310 of file plistCollections.h.

Referenced by getLongestKeyLen(), loadXML(), and plist::DictionaryOf< PO, Alloc >::set().

virtual size_t plist::DictionaryBase::size (  )  const [inline, virtual]

void plist::DictionaryBase::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!)

Definition at line 212 of file plistCollections.cc.

Referenced by plist::ArrayOf< plist::Primitive< std::string > >::addEntry(), plist::DictionaryOf< PO, Alloc >::loadXMLNode(), plist::DictionaryOf< PO, Alloc >::operator=(), and plist::DictionaryOf< PO, Alloc >::set().

const std::string & plist::DictionaryBase::getComment ( const std::string &  name  )  const

returns comment retrieved from loaded file, or any subsequent call to setComment

Definition at line 219 of file plistCollections.cc.

Referenced by plist::DictionaryOf< PO, Alloc >::operator=(), and plist::DictionaryOf< PO, Alloc >::set().

void plist::DictionaryBase::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:

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.

Reimplemented in InstanceTracker< FamilyT, ClassNameT, FactoryBaseT, FactoryT >.

Definition at line 228 of file plistCollections.cc.

Referenced by InstanceTracker< FamilyT, ClassNameT, FactoryBaseT, FactoryT >::loadXML(), and ConfigDictionary::loadXMLNode().

virtual void plist::DictionaryBase::saveXML ( xmlNode node  )  const [inline, virtual]

subclasses are expected to provide a working implementation

Implements plist::ObjectBase.

Definition at line 320 of file plistCollections.h.

Referenced by ConfigDictionary::saveOverXMLNode(), OutputConfig< T >::saveXML(), and Config::saveXML().

void plist::DictionaryBase::saveXML ( xmlNode node,
bool  onlyOverwrite,
std::set< std::string > &  seen 
) const [virtual]

saves the dictionary into the specified node

Parameters:
[in] node the xml node which should be saved into
[in] onlyOverwrite if is true, only saves entries for keys already found in the node (this overrides the current savePolicy value)
[in] seen used to keep track of which nodes have been seen in node -- may be of particular interest with onlyOverride set
seen is not cleared before being used.

Reimplemented in OutputConfig< T >, Config, and OutputConfig< plist::Primitive< float > >.

Definition at line 271 of file plistCollections.cc.

std::string plist::DictionaryBase::toString (  )  const [virtual]

return current value as a string

Implements plist::ObjectBase.

Definition at line 346 of file plistCollections.cc.

unsigned int plist::DictionaryBase::getLongestKeyLen ( const regex_t *  reg = NULL,
unsigned int  depth = -1 
) const [virtual]

returns the length of the longest key, subject to an optional regular expression and max depth

Implements plist::Collection.

Definition at line 352 of file plistCollections.cc.

bool plist::DictionaryBase::ownsReference ( ObjectBase val  )  const [inline]

returns true if the specified object will be deallocated when removed from the dictionary

Definition at line 335 of file plistCollections.h.

Referenced by plist::DictionaryOf< PO, Alloc >::set().

DictionaryBase& plist::DictionaryBase::operator= ( const DictionaryBase d  )  [inline, protected]

assignment (don't assign listeners)

Definition at line 343 of file plistCollections.h.

Referenced by plist::DictionaryOf< PO, Alloc >::operator=(), and plist::DictionaryOf< PO, Alloc >::set().

void plist::DictionaryBase::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 406 of file plistCollections.cc.

Referenced by plist::ArrayOf< plist::Primitive< std::string > >::addEntry(), plist::DictionaryOf< PO, Alloc >::addEntry(), and plist::DictionaryOf< PO, Alloc >::setEntry().

void plist::DictionaryBase::fireEntryRemoved ( ObjectBase val  )  [protected, virtual]

run through collectionListeners, calling CollectionListener::plistCollectionEntryRemoved(*this,val)

Reimplemented from plist::Collection.

Definition at line 410 of file plistCollections.cc.

Referenced by removeEntry(), and renameEntry().

DictionaryBase::iterator plist::DictionaryBase::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 368 of file plistCollections.cc.

Referenced by resolveEntry().

DictionaryBase::const_iterator plist::DictionaryBase::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 380 of file plistCollections.cc.

void plist::DictionaryBase::cloneMyRef (  )  [protected, virtual]

called after an assignment or copy to clone the objects in myRef to perform a deep copy

Definition at line 419 of file plistCollections.cc.

Referenced by plist::ArrayBase::ArrayBase(), and DictionaryBase().

virtual bool plist::DictionaryBase::loadXMLNode ( const std::string &  key,
xmlNode val,
const std::string &  comment 
) [protected, pure virtual]

called with each node being loaded so subclass can handle appropriately

Implemented in ConfigDictionary, OutputConfig< T >, plist::DictionaryOf< PO, Alloc >, OutputConfig< plist::Primitive< float > >, and plist::DictionaryOf< ObjectBase >.

Referenced by loadXML().

bool plist::DictionaryBase::saveOverXMLNode ( xmlNode k,
xmlNode val,
const std::string &  key,
std::string  comment,
const std::string &  indentStr,
std::set< std::string > &  seen 
) const [protected, virtual]

called with each node being saved so subclass can handle appropriately, return true if successful and reset key if changed

Reimplemented in ConfigDictionary.

Definition at line 450 of file plistCollections.cc.

Referenced by ConfigDictionary::saveOverXMLNode(), and saveXML().

void plist::DictionaryBase::saveXMLNode ( xmlNode node,
const std::string &  key,
const ObjectBase val,
const std::string &  indentStr 
) const [protected, virtual]

called with each node being saved so subclass can handle appropriately, return true if successful and set key

Definition at line 502 of file plistCollections.cc.

Referenced by saveXML(), and OutputConfig< T >::saveXML().


Friends And Related Function Documentation

std::ostream& operator<< ( std::ostream &  os,
const DictionaryBase d 
) [friend]

provides textual output

Definition at line 1414 of file plistCollections.h.


Member Data Documentation

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 386 of file plistCollections.h.

Referenced by plist::DictionaryOf< PO, Alloc >::addEntry(), clear(), getComment(), removeEntry(), renameEntry(), saveOverXMLNode(), saveXMLNode(), setComment(), and swapEntry().


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

Tekkotsu v4.0
Generated Thu Nov 22 00:58:54 2007 by Doxygen 1.5.4