iLab Neuromorphic Robotics Toolkit  0.1
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
AutoMap.H
Go to the documentation of this file.
1 /*! @file
2  @author Randolph Voorhies
3  @copyright GNU Public License (GPL v3)
4  @section License
5  @verbatim
6  // ////////////////////////////////////////////////////////////////////////
7  // The iLab Neuromorphic Robotics Toolkit (NRT) //
8  // Copyright 2010-2012 by the University of Southern California (USC) //
9  // and the iLab at USC. //
10  // //
11  // iLab - University of Southern California //
12  // Hedco Neurociences Building, Room HNB-10 //
13  // Los Angeles, Ca 90089-2520 - USA //
14  // //
15  // See http://ilab.usc.edu for information about this project. //
16  // ////////////////////////////////////////////////////////////////////////
17  // This file is part of The iLab Neuromorphic Robotics Toolkit. //
18  // //
19  // The iLab Neuromorphic Robotics Toolkit is free software: you can //
20  // redistribute it and/or modify it under the terms of the GNU General //
21  // Public License as published by the Free Software Foundation, either //
22  // version 3 of the License, or (at your option) any later version. //
23  // //
24  // The iLab Neuromorphic Robotics Toolkit is distributed in the hope //
25  // that it will be useful, but WITHOUT ANY WARRANTY; without even the //
26  // implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR //
27  // PURPOSE. See the GNU General Public License for more details. //
28  // //
29  // You should have received a copy of the GNU General Public License //
30  // along with The iLab Neuromorphic Robotics Toolkit. If not, see //
31  // <http://www.gnu.org/licenses/>. //
32  // ////////////////////////////////////////////////////////////////////////
33  @endverbatim */
34 
35 
36 #ifndef INCLUDE_NRT_CORE_DESIGN_AUTOMAP_H
37 #define INCLUDE_NRT_CORE_DESIGN_AUTOMAP_H
38 
39 #include <unordered_map>
40 #include <queue>
41 #include <stddef.h> // for size_t
42 
43 /*! \defgroup design Generic classes implementing common design patterns
44 
45  Design patterns implemented include Singleton, SynchroQueue, ThreadPool, Semaphore, BoundedBuffer, BoundedSet, etc
46 
47  \ingroup core */
48 
49 namespace nrt
50 {
51  //! A table used to create unique Ids and store a value for each Id
52  /*! The AutoMap class provides a way to create unique keys, with recycling when keys get deleted. One can then store a
53  value for each key. The keys are unique to each instance of the class, not globally unique.
54 
55  \note Care must be taken when using this structure in a multithreaded environment. If not locked properly, the
56  internal structures could get messed up. AutoMap itself has no internal locking mechanisms.
57 
58  \ingroup design */
59  template <class KeyType, class ValueType>
60  class AutoMap
61  {
62  public:
63  //! Constructor
64  AutoMap();
65 
66  //! Iterator over the map
67  typedef typename std::map<KeyType, ValueType>::iterator iterator;
68 
69  //! Returns an iterator pointing to the beginning of the map
70  iterator begin();
71 
72  //! Returns an iterator pointing to the end of the map
73  iterator end();
74 
75  //! Constant iterator over the map
76  typedef typename std::map<KeyType, ValueType>::const_iterator const_iterator;
77 
78  //! Returns a const_iterator pointing to the beginning of the map
79  const_iterator begin() const;
80 
81  //! Returns an iterator pointing to the end of the map
82  const_iterator end() const;
83 
84  //! Access a value by key
85  /*! Caution this is different from std::map and will throw if the key does not exist. */
86  ValueType & operator[](KeyType const & key);
87 
88  //! Insert a value by first creating a new key for it, and return that key
89  /*! This is the function that std::map is missing. */
90  KeyType insert(ValueType const & value);
91 
92  //! Erase a key/value entry from the map
93  void erase(iterator pos);
94 
95  //! Erase by key, it will be recycled and available next time a new key is created by insert()
96  void erase(KeyType const & key);
97 
98  //! Clear the entire AutoMap
99  void clear();
100 
101  //! An exception type which is thrown when users try to use an unknown key
102  class KeyNotFoundException;
103 
104  private:
105  std::map<KeyType, ValueType> itsMap;
106  std::queue<KeyType> itsRecycleBin;
107  KeyType itsMaxKey;
108  };
109 } // namespace nrt
110 
112 
113 #endif // INCLUDE_NRT_CORE_DESIGN_AUTOMAP_H