|
Isis 3.0 Developer's Reference (API) |
Home |
Collector/container for arbitrary items. More...
#include <CollectorMap.h>
Inherits RemovalPolicy< T >, and CopyPolicy< T >.
Public Types | |
| enum | KeyPolicy { UniqueKeys, DuplicateKeys } |
Enumerated selection of key behaviour. More... | |
| typedef T | CollectorType |
| Data type A multimap attacking a key to a CollectorType and a ComparePolicy<CollectorType>. | |
| typedef std::multimap< K, CollectorType, ComparePolicy < K > > | CollectorList |
| typedef CollectorList::iterator | CollectorIter |
| CollectorList iterator type declaration. | |
| typedef CollectorList::const_iterator | CollectorConstIter |
| CollectorList constant iterator type declaration. | |
Public Member Functions | |
| CollectorMap () | |
| Constructor. | |
| CollectorMap (const KeyPolicy &keyPolicy) | |
| Allows the user to choose if keys can be duplicated. | |
| virtual | ~CollectorMap () |
| Destructor handles removal of the elements within the collection. | |
| CollectorMap (const CollectorMap &cmap) | |
| Copy constructor invokes the copy policy as provided by the users. | |
| CollectorMap & | operator= (const CollectorMap &cmap) |
| Assignment operator for the CollectorMap class object. | |
| int | size () const |
| Returns the size of the collection. | |
| int | count (const K &key) const |
| Returns the number of keys found in the list. | |
| void | add (const K &key, const T &value) |
| Adds the element to the list. | |
| bool | exists (const K &key) const |
| Checks the existance of a particular key in the list. | |
| T & | get (const K &key) throw (iException &) |
| Returns the value associated with the name provided. | |
| const T & | get (const K &key) const throw (iException &) |
| Const version returning the value associated with the given name. | |
| int | index (const K &key) const |
| Returns the index of the first occuring element in the list. | |
| T & | getNth (int nth) throw (iException &) |
| Returns the nth value in the collection. | |
| const T & | getNth (int nth) const throw (iException &) |
| Returns the nth value in the collection. | |
| const K & | key (int nth) const throw (iException &) |
| Returns the nth key in the collection. | |
| int | remove (const K &key) |
| Removes and entry from the list. | |
| CollectorConstIter | begin () const |
| Const iterator into list. | |
| CollectorConstIter | end () const |
| Const iterator to end of list. | |
| CollectorIter | begin () |
| Returns the start of the list for iterating purposes. | |
| CollectorIter | end () |
| Returns the end of the list. | |
Collector/container for arbitrary items.
Used to contain types with iterators of const and non-const conditions. This is a multimap that contains arbitrary keys with arbitrary elements. It is intended to be used for pointers and copyable objects. They should be rather efficient in the copy out operation so large objects may not be suitable or classes that do not have a good copy operator. During testing it was noted that an object is copied up to four times and destroyed three times upon an add() operation.
This class is implemented using policies. The ComparePolicy is used to test key elements such as strings and double values. The NoCaseStringCompare policy is provided that expedites case insensitive string key comparisons. The RobustFloatCompare implements the comparison of double or float key types. Direct comparisons of floats can be problematic due to round off and storage manifestations of these values in conputers. The default policy, SimpleCompare, does a simple parameter to key equality test.
The RemovalPolicy is provided when a map value is removed from the list. This allows pointers and arrays to be stored in the map as well. To store pointers, use PointerRemoval and for arrays there is the ArrayRemoval policy. The default is the NoopRemoval policy which simply lets the destructor handle removals.
The CopyPolicy is necessary to properly handle the copying of elements. This is especially important for pointers and arrays. In order to minimize difficult passing strategies, map elements are passed by address and the return type is the element type. DefaultCopy simply copies the elements as is relying on the element T assigment operator to do the right thing. For pointers to objects, the PointerCopy allocates the object using the copy constructor. One could provide a similar operator assuming a clone() method existed for the type T element. The ArrayCopy policy is left to the user to provide their own as it cannot support arrays of varying length. (One should use std::vector instead!) Users can supply their own CopyPolicy that need only expose a copy(cont T *src) method.
Here are some examples that demonstrate how this policy-based template class can be used:
// Create a unique string key list that stores double floating point values. // Use the default removal and copy policies but allow testing for character // keys without regard to case via the NoCaseStringCompare. #include "CollectorMap.h" CollectorMap<std::string, double, NoCaseStringCompare > dmap; cout << "\nSize of double map = " << dmap.size() << endl; dmap.add("one", 1.0); dmap.add("two", 2.0); cout << "Size of double map = " << dmap.size() << endl; cout << "One = " << dmap.get("one") << endl; cout << "Two = " << dmap.get("Two") << endl; const double &one = dmap.get("one"); cout << "\nTest Const one = " << one << endl; dmap.remove("one");
Using this class internal to classes is perhaps where it may be applied more frequently. The example below shows how to declare an integer key using pointers to classes:
#include "CollectorMap.h" class ClassTest { public: ClassTest(int n = 0) : _n(n) { } ~ClassTest() { } int Ident() const { return (_n); } private: int _n; }; // Typedefs are sometimes convenient in these cases typedef CollectorMap<int, ClassTest *, SimpleCompare, PointerRemoval, PointerCopy> PointerMap; PointerMap ctest2; ctest2.add(4,new ClassTest(4)); ctest2.add(5,new ClassTest(5)); ctest2.add(6,new ClassTest(6)); ctest2.add(7,new ClassTest(7)); cout << "Remove ClassTest 6\n"; ctest2.remove(6); // Creates a copy of ctest2 using the PointerCopy policy PointerMap map2(ctest2); cout << "Find element 7: " << map2.find(7)->Ident() << endl;
And, finally, an example of how to use duplicate keys:
#include "CollectorMap.h" typedef CollectorMap<int,std::string> IntStr; IntStr dupstr(IntStr::DuplicateKeys); dupstr.add(1,"One"); dupstr.add(1, "One #2"); dupstr.add(1,"One #3"); dupstr.add(2,"Two"); dupstr.add(2,"Two #2"); dupstr.add(3,"Three"); cout << "Size of Dup object: " << dupstr.size() << endl; cout << "Number Ones: " << dupstr.count(1) << endl; cout << "Number Twos: " << dupstr.count(2) << endl; cout << "Number Threes: " << dupstr.count(3) << endl; cout << "Number Fours: " << dupstr.count(4) << endl; IntStr::CollectorConstIter isIter; int j = 0; for (isIter = dupstr.begin() ; isIter != dupstr.end() ; ++isIter, j++) { cout << "IntStr[" << j << "] = {" << isIter->first << ", " << isIter->second << "}, Index: " << dupstr.index(isIter->first) << endl; cout << "Nth Test Ident = " << dupstr.getNth(j) << endl; }
The output of the above example is:
Size of Dup object: 6
Number Ones: 3
Number Twos: 2
Number Threes: 1
Number Fours: 0
IntStr[0] = {1, One}, Index: 0
Nth Test Ident = One
IntStr[1] = {1, One #2}, Index: 0
Nth Test Ident = One #2
IntStr[2] = * {1, One #3}, Index: 0
Nth Test Ident = One #3
IntStr[3] * = {2, Two}, Index: 3
Nth Test Ident = Two
IntStr[4] = * {2, Two #2}, Index: 3
Nth Test Ident = Two #2
IntStr[5] = * {3, Three}, Index: 5
Nth Test Ident = Three
| typedef CollectorList::const_iterator Isis::CollectorMap< K, T, ComparePolicy, RemovalPolicy, CopyPolicy >::CollectorConstIter |
CollectorList constant iterator type declaration.
| typedef CollectorList::iterator Isis::CollectorMap< K, T, ComparePolicy, RemovalPolicy, CopyPolicy >::CollectorIter |
CollectorList iterator type declaration.
| typedef std::multimap<K, CollectorType, ComparePolicy<K> > Isis::CollectorMap< K, T, ComparePolicy, RemovalPolicy, CopyPolicy >::CollectorList |
| typedef T Isis::CollectorMap< K, T, ComparePolicy, RemovalPolicy, CopyPolicy >::CollectorType |
Data type A multimap attacking a key to a CollectorType and a ComparePolicy<CollectorType>.
| enum Isis::CollectorMap::KeyPolicy |
| Isis::CollectorMap< K, T, ComparePolicy, RemovalPolicy, CopyPolicy >::CollectorMap | ( | ) | [inline] |
Constructor.
| Isis::CollectorMap< K, T, ComparePolicy, RemovalPolicy, CopyPolicy >::CollectorMap | ( | const KeyPolicy & | keyPolicy | ) | [inline] |
Allows the user to choose if keys can be duplicated.
This constructor is provided to the user that wants to explicity define how the keys, namely insertions are managed. The default is unique keys in the noop constructor...this one allows instantiation of either policy.
| keyPolicy | Can be UniqueKeys or DuplicateKeys |
| virtual Isis::CollectorMap< K, T, ComparePolicy, RemovalPolicy, CopyPolicy >::~CollectorMap | ( | ) | [inline, virtual] |
Destructor handles removal of the elements within the collection.
This must take into account the removal strategy and apply to any remaining elements.
| Isis::CollectorMap< K, T, ComparePolicy, RemovalPolicy, CopyPolicy >::CollectorMap | ( | const CollectorMap< K, T, ComparePolicy, RemovalPolicy, CopyPolicy > & | cmap | ) | [inline] |
Copy constructor invokes the copy policy as provided by the users.
This copy constructor will transfer the map of an incoming CollectorMap to a newly created one. This process employs the user selectable CopyPolicy. It invokes the copy() method exposed in the copy policy.
| cmap | The CollectorMap to be copied |
| void Isis::CollectorMap< K, T, ComparePolicy, RemovalPolicy, CopyPolicy >::add | ( | const K & | key, | |
| const T & | value | |||
| ) | [inline] |
Adds the element to the list.
If the element exists and the key policy is restricted to uniqueness, it is replaced after the removal strategy is applied. If it doesn't exist, it is inserted into the list. For duplicate keys, it is simply inserted.
| key | Key in the associative map for the value | |
| value | Value to be associated with the key |
References Isis::CollectorMap< K, T, ComparePolicy, RemovalPolicy, CopyPolicy >::UniqueKeys.
Referenced by Isis::CSVReader::getColumnSummary(), and Isis::LroWideAngleCamera::LroWideAngleCamera().
| CollectorIter Isis::CollectorMap< K, T, ComparePolicy, RemovalPolicy, CopyPolicy >::begin | ( | ) | [inline] |
Returns the start of the list for iterating purposes.
| CollectorConstIter Isis::CollectorMap< K, T, ComparePolicy, RemovalPolicy, CopyPolicy >::begin | ( | ) | const [inline] |
Const iterator into list.
| int Isis::CollectorMap< K, T, ComparePolicy, RemovalPolicy, CopyPolicy >::count | ( | const K & | key | ) | const [inline] |
Returns the number of keys found in the list.
For unique keys, this will always be 1. If duplicate keys are allowed, this will return the number of keys in the container.
| key | Key to return count for |
| CollectorIter Isis::CollectorMap< K, T, ComparePolicy, RemovalPolicy, CopyPolicy >::end | ( | ) | [inline] |
Returns the end of the list.
| CollectorConstIter Isis::CollectorMap< K, T, ComparePolicy, RemovalPolicy, CopyPolicy >::end | ( | ) | const [inline] |
Const iterator to end of list.
| bool Isis::CollectorMap< K, T, ComparePolicy, RemovalPolicy, CopyPolicy >::exists | ( | const K & | key | ) | const [inline] |
Checks the existance of a particular key in the list.
| key | Key to search for in the list |
Referenced by Isis::CSVReader::getColumnSummary(), and Isis::LroWideAngleCamera::LroWideAngleCamera().
| const T& Isis::CollectorMap< K, T, ComparePolicy, RemovalPolicy, CopyPolicy >::get | ( | const K & | key | ) | const throw (iException &) [inline] |
Const version returning the value associated with the given name.
| key | Key to fetch the value for |
References _FILEINFO_, Isis::CollectorMap< K, T, ComparePolicy, RemovalPolicy, CopyPolicy >::key(), Isis::iException::Message(), and Isis::iException::Programmer.
| T& Isis::CollectorMap< K, T, ComparePolicy, RemovalPolicy, CopyPolicy >::get | ( | const K & | key | ) | throw (iException &) [inline] |
Returns the value associated with the name provided.
If the specifed name and value does not exist in the list, an out_of_range exception is thrown. Use exists to predetermine of the value is in the list.
| key | Key to fetch the value for |
| iException | if the value is not found |
References _FILEINFO_, Isis::CollectorMap< K, T, ComparePolicy, RemovalPolicy, CopyPolicy >::key(), Isis::iException::Message(), and Isis::iException::Programmer.
Referenced by Isis::CSVReader::getColumnSummary(), and Isis::LroWideAngleCamera::LroWideAngleCamera().
| const T& Isis::CollectorMap< K, T, ComparePolicy, RemovalPolicy, CopyPolicy >::getNth | ( | int | nth | ) | const throw (iException &) [inline] |
Returns the nth value in the collection.
If the specifed value does not exist in the list, an out_of_range exception is thrown. Use size() to predetermine if the range is valid.
| nth | Return the Nth value in the list |
References _FILEINFO_, Isis::iException::Message(), and Isis::iException::Programmer.
| T& Isis::CollectorMap< K, T, ComparePolicy, RemovalPolicy, CopyPolicy >::getNth | ( | int | nth | ) | throw (iException &) [inline] |
Returns the nth value in the collection.
If the specifed value does not exist in the list, an out_of_range exception is thrown. Use size() to predetermine if the range is valid.
| nth | Return the Nth value in the list |
References _FILEINFO_, Isis::iException::Message(), and Isis::iException::Programmer.
Referenced by Isis::LroWideAngleCamera::LroWideAngleCamera().
| int Isis::CollectorMap< K, T, ComparePolicy, RemovalPolicy, CopyPolicy >::index | ( | const K & | key | ) | const [inline] |
Returns the index of the first occuring element in the list.
This returns the index such that the getNth() methods would retrieve the element with key. For duplicate keys, it is garaunteed to return the first element. It will return -1 if the element is not in the list.
| key | Key to fetch the value for |
| const K& Isis::CollectorMap< K, T, ComparePolicy, RemovalPolicy, CopyPolicy >::key | ( | int | nth | ) | const throw (iException &) [inline] |
Returns the nth key in the collection.
If the specifed key does not exist in the list, an out_of_range exception is thrown. Use size() to predetermine if the range is valid.
| nth | Return the Nth key in the list |
References _FILEINFO_, Isis::iException::Message(), and Isis::iException::Programmer.
Referenced by Isis::CSVReader::columns(), Isis::CollectorMap< K, T, ComparePolicy, RemovalPolicy, CopyPolicy >::get(), and Isis::CollectorMap< K, T, ComparePolicy, RemovalPolicy, CopyPolicy >::remove().
| CollectorMap& Isis::CollectorMap< K, T, ComparePolicy, RemovalPolicy, CopyPolicy >::operator= | ( | const CollectorMap< K, T, ComparePolicy, RemovalPolicy, CopyPolicy > & | cmap | ) | [inline] |
Assignment operator for the CollectorMap class object.
This object assignment operator is provided to properly handle the copying of CollectorMap elements to a new instantiation. This implements the CopyPolicy for each element in the cmap object to the current one. This is a two step operation: first destroy any elements that exist in the destination object (using the RemovalPolicy) and then copy all elements from the cmap object to the current one using the copy() method exposed in the CopyPolicy.
| cmap | The CollectorMap to be copied |
| int Isis::CollectorMap< K, T, ComparePolicy, RemovalPolicy, CopyPolicy >::remove | ( | const K & | key | ) | [inline] |
Removes and entry from the list.
| key | Name of key/value pair to remove from the list |
References Isis::CollectorMap< K, T, ComparePolicy, RemovalPolicy, CopyPolicy >::key().
| int Isis::CollectorMap< K, T, ComparePolicy, RemovalPolicy, CopyPolicy >::size | ( | ) | const [inline] |
Returns the size of the collection.
Referenced by Isis::CSVReader::columns(), Isis::CSVReader::isTableValid(), and Isis::LroWideAngleCamera::LroWideAngleCamera().