Main Page   Class Hierarchy   Compound List   File List   Compound Members   Related Pages  

rel::VMap Class Reference

Virtual Map (VMap). This defines an interface for a mapping from string keys to arbitrary values. More...

#include <VMap.h>

Inheritance diagram for rel::VMap:

Inheritance graph
[legend]
List of all members.

Public Types

typedef SmartPtr< VMap > Ptr
enum  ErrorCode {
  Success = 0, TypeMismatch = 1, NotFound = 2, AlreadyExists = 3,
  NotPermitted = 4, Unsupported = 5, ArgumentError = 6, BackendError
}
enum  DirFlags { NoFlags = 0x00, FindOrCreate }

Public Methods

virtual ~VMap ()
virtual Ptr findDirectory (const string &name, int flags=NoFlags)
virtual Ptr findDirectory (const TypeStream &path, int flags=NoFlags)
virtual Ptr createDirectory (const string &name)
virtual Ptr createDirectory (const TypeStream &path)
virtual OpaqueValue find (const string &name)
virtual OpaqueValue find (const TypeStream &path)
virtual VMapIterator begin ()
virtual VMapIterator end ()
virtual VMapIterator at (const string &name)
virtual ErrorCode insert (const string &name, const OpaqueValue &value)
virtual ErrorCode insert (const TypeStream &path, const OpaqueValue &value, int flags=FindOrCreate)
virtual ErrorCode assign (const string &name, const OpaqueValue &value)
virtual ErrorCode assign (const TypeStream &path, const OpaqueValue &value)
virtual ErrorCode erase (const string &name)
virtual ErrorCode erase (const TypeStream &path)
virtual ErrorCode clear ()

Protected Methods

virtual void advanceIterator (const OpaqueValue &) const
virtual bool equalIteratorData (const OpaqueValue &a, const OpaqueValue &b) const
virtual void assignIteratorData (const OpaqueValue &src, const OpaqueValue &dest) const
virtual void getKeyValue (const OpaqueValue &iteratorData, std::pair< std::string, OpaqueValue > *result)

Protected Attributes

friend VMapIterator

Related Functions

(Note that these are not member functions.)

OpaqueValue findFirst (VMapPtr &map, const TypeStream &path, const string &key)
OpaqueValue findDeepest (VMapPtr &map, const TypeStream &path, const string &key)

Detailed Description

Virtual Map (VMap). This defines an interface for a mapping from string keys to arbitrary values.

The values are stored as an OpaqueValue - which can be converted to the appropriate SmartPtr<> type using operator=.

For example, to store an integer pointer, and then pull it back out: 

      // create a new map (a VMemMap - memory based storage)
      VMapPtr testMap(new VMemMap);
      
      // insert the value 42 into the map
      testMap->insert("test value", SmartPtr<int>(new int(42)));
      // This would also work - as the smart pointer can store by-value as well
      // as a pointer to a value..
      // testMap->insert("test value", SmartPtr<int>(int(42)));

      // pull out the value and print it
      SmartPtr<int> result = testMap->find("test value");
      cout << "result = " << *result << endl;

Author:
Valient Gough

Member Enumeration Documentation

enum rel::VMap::DirFlags
 

Special flags for some operations - such as findDirectory(). This can be used to tell findDirectory to create the directory if it doesn't exist, or to return failure.

Enumeration values:
NoFlags   default operation.
FindOrCreate   create directories if they do not exist.

enum rel::VMap::ErrorCode
 

Error codes returned by various VMap operations. These are returned when a return value can be used instead of having to throw an error. For calls which cannot return an error code, or for errors for which there is no matching code, an error may be thrown.

See also:
VMapException
Enumeration values:
Success   Operation succeeded.
TypeMismatch   The requested type didn't match the stored type.
NotFound   No element was found for the requested key.
AlreadyExists   An element already exists for the key.
NotPermitted   Operation not allowed.
Unsupported   Operation not supported.
ArgumentError   Something wrong with the argument.
BackendError   Unknown error from external implementation.

Constructor & Destructor Documentation

VMap::~VMap (    )  [virtual]
 

All elements in the map are released. Since all elements are smart pointers (OpaqueValue), then if that was the last reference, they will be destroyed by whatever means the smart pointer provides.

See also:
OpaqueValue SmartPtr

Member Function Documentation

VMap::ErrorCode VMap::clear (    )  [virtual]
 

Remove (and destroy) all elements in the map.

Reimplemented in rel::VMemMap.

VMapPtr VMap::createDirectory (  const string &   name )  [virtual]
 

create directory using a direct name. throws VMap_unsupported if not implemented

Reimplemented in rel::VMemMap.

VMapPtr VMap::findDirectory (  const TypeStream &   path,
int   flags = NoFlags
)  [virtual]
 

search for [sub]directory using a multi-part name. This can contain one or more directory names, which results in a sequencial search. This is convenient when dealing with nested values -- for example: 

          // search inside the directory "a" for an entry "b".
          OpaqueValue result = testMap->find(Path("a/b"));

          // equivelent code:
          VMapPtr subDir = testMap->find("a");
          if(subDir.get())
              result = subDir->find("b");
Parameters:
name   The directory name. This may contain one or more elements.
flags   By default this is NoFlags, which means that if a directory does not exist, a NULL pointer is returned. If set to FindOrCreate, then the directory is created if it does not already exist. What type of directory gets created depends on what type of map creates it.. If a VMemMap is the parent, then it will create a VMemMap subdirectory..
Returns:
NULL if directory is not found but was not requested to be created (or throws error if it was supposed to be created and still couldn't be returned)

VMapPtr VMap::findDirectory (  const string &   name,
int   flags = NoFlags
)  [virtual]
 

search for [sub]directory using a direct name

Parameters:
name   The directory name. This is not checked for path elements - it is treated as a single string.
flags   By default this is NoFlags, which means that if a directory does not exist, a NULL pointer is returned. If set to FindOrCreate, then the directory is created if it does not already exist. What type of directory gets created depends on what type of map creates it.. If a VMemMap is the parent, then it will create a VMemMap subdirectory..
Returns:
NULL if directory is not found but was not requested to be created (or throws error if it was supposed to be created and still couldn't be returned)

Friends And Related Function Documentation

OpaqueValue findDeepest (  VMapPtr &   map,
const TypeStream &   path,
const string &   key
)  [related]
 

Search down the tree for the deepest occurance of the key. Returns the value if any.

See also:
findFirst

OpaqueValue findFirst (  VMapPtr &   map,
const TypeStream &   path,
const string &   key
)  [related]
 

Search down the tree for the first occurance of the key. Returns the value, if any.

See also:
findDeepest

The documentation for this class was generated from the following files:
Generated at Sat Sep 22 02:20:03 2001 for librel by doxygen1.2.10 written by Dimitri van Heesch, © 1997-2001