Warning, /DataFormats/Common/doc/Common_containers.doc is written in an unsupported language. File is not indexed.
0001 /*!
0002 \page DataFormats_Common_containers Package DataFormats/Common: container classes
0003 <center>
0004 <small>
0005 <a href=http://cmsdoc.cern.ch/swdev/viewcvs/viewcvs.cgi/CMSSW/DataFormats/Common/?cvsroot=CMSSW>CVS head for this package</a> -
0006 <a href=http://cmsdoc.cern.ch/swdev/viewcvs/viewcvs.cgi/CMSSW/DataFormats/Common/.admin/developers?rev=HEAD&cvsroot=CMSSW&content-type=text/vnd.viewcvs-markup>Administrative privileges</a>
0007 </small>
0008 </center>
0009
0010 \section desc Description
0011 Commonly used persistent containers.
0012
0013 \subsection interface Public interface
0014 - edm::AssociationMap <b><Tag></b>: one-to-many, one-to-one
0015 or one-to-value association based on edm::Ref. Objects in a EDM collection
0016 are associated to one or many objects in another EDM collection or to
0017 values of a specified type.<br><br>
0018 The template <tt>Tag</tt> should be one of the following:
0019 - edm::OneToValue <b><CKey, Val, index></b> for associations by value
0020 - edm::OneToOne <b><CKey, CVal, index></b> for one-to-one maps by reference
0021 - edm::OneToMany <b><CKey, CVal, index></b> for one-to-many maps by reference
0022 - edm::OneToManyWithQuality <b><CKey, CVal, Q, index></b>
0023 <b>CKey</b> is the collection type of the object to be associated, <b>CVal</b> is the collection of
0024 associated objects, <b>Val</b> is the associated value type and <b>Q</b> is the data type describing
0025 the match quality. References are stored as indices of type <tt>index</tt>, that is by default
0026 <tt>unsigned long</tt>, but could be <tt>unsigned short</tt> for collections with less than 65535
0027 objects or <tt>unsigned char</tt> for collections with less than 255 objects.<br><br>
0028 One example of basic usage is presented below:
0029 \htmlonly
0030 <pre>
0031 typedef edm::AssociationMap<edm::OneToMany<CaloJetCollection, TrackCollection> >
0032 JetTracksMap;
0033 JetTracksMap map;
0034
0035 CaloJetRef rj = ...;
0036 TrackRef rt = ...;
0037 map->insert( rj, rt );
0038 const TrackRefVector & tracks = map[ rj ];
0039
0040 JetTracksMap::const_iterator i = map.find( rj );
0041 assert( i != map.end() );
0042 const CaloJetRef & jet1 = i->key;
0043 const TrackRefVector & tracks1 = i->val;
0044 </pre>
0045 \endhtmlonly
0046 The attribute <tt>transientMap_</tt> has to be declared transient in the
0047 dictionary. Other used persistent
0048 types have to be declared in the dictionary, depending case by case:
0049 \htmlonly
0050 <pre>
0051 <lcgdict>
0052 <class name="edm::AssociationMap< ... >" >
0053 <field name="transientMap_" transient="true" />
0054 </class >
0055 </lcgdict>
0056 </pre>
0057 \endhtmlonly
0058
0059 - edm::AssociationVector <b><CKey, CVal></b>: container very similar to
0060 <tt>std::vector<CVal></tt>, with in addition an <tt>edm::RefProd<CKey></tt>.
0061 Assuming the two collection of types <tt>CKey</tt> and <tt>CVal</tt> are of the same
0062 size and properly ordered, this container implements in a very simple way a one-to-one
0063 association. In order to get the reference to the <i>i<sup>th</sup></i> object in
0064 the <tt>CKey</tt> collection, the method <tt>key(i)</tt> is implemented. Below
0065 a user example:
0066 \htmlonly
0067 <pre>
0068 edm::AssiciationVector<reco::MuonCollection, std::vector<double> > isolations( muonRefProd );
0069 // fill the association ...
0070 for( size_t i = 0; i < isolations.size(); ++ i ) {
0071 double iso = isolations[ i ];
0072 reco::MuonRef muon = isolations.key( i );
0073 double pt = muon->pt();
0074 }
0075 </pre>
0076 \endhtmlonly
0077
0078 - edm::DetSet <b><T></b>:
0079
0080 - edm::EDCollection <b><T></b>: Functionally equivalent to <tt>std::vector<T></tt>.
0081 Still present for hystorical reason; will be probably removed in one of the next releases.
0082
0083 - edm::IDVectorMap <b><ID, C, P></b>:
0084
0085 - edm::OwnVector <b><T, P = edm::ClonePolicy<T> ></b>: container
0086 with interface very similar to <tt>std::vector<T></tt>,
0087 capable of storing polymorphic objects that are owned by the
0088 container to avoid memory leak.
0089 edm::OwnVector has functionalities very similar to
0090 <a href="http://www.boost.org/libs/ptr_container/doc/ptr_vector.html"><tt>boost::ptr_vector<T></tt></a>,
0091 providing also EDM persistent capabilities.
0092 <br><br>The first template argument <tt><b>T</b></tt> is the common base class of
0093 polymorphic objects to be stored; the second parameter <tt><b>P</b></TT> specifies
0094 the \ref DataFormats_Common_helpers "policy" required to allocate clones of
0095 the stored object. By default, it
0096 is equal to the type <b>edm::ClonePolicy<T></b> assuming the
0097 type <tt>T</tt> is equipped with a virtual method <tt><b>clone()</b></tt> that returning a cloned
0098 instance of the actual concrete object. Other user-provided policy implementations are possible.
0099 <br><br>
0100 As for <a href="http://www.boost.org/libs/ptr_container/doc/ptr_vector.html"><tt>boost::ptr_vector</tt></a>,
0101 due to the polymorphic nature of contained objects, the STL <tt><b>std::sort</b></tt>
0102 function and other mutating algorithms do not work with edm::OwnVector. For this reason, functions to sort
0103 the collection are provided as class methods, using the same approach
0104 taken by <a href="http://www.boost.org/libs/ptr_container/doc/ptr_vector.html"><tt>boost::ptr_vector</tt></a>.
0105 See also this <a href="http://www.boost.org/libs/ptr_container/doc/tutorial.html#algorithms">documentation</a>
0106 from <a href="http://www.boost.org">Boost library</a>.<br><br>
0107 Please, note that for classes that do not provide a "<" operator, the function
0108 <tt>sort()</tt> has to be <b>explicitly removed</b> from the reflex dictionary generation.
0109 So, you should add to your <tt>classes_def.xml</tt> the following lines:
0110 \htmlonly
0111 <pre>
0112 <lcgdict>
0113 <selection>
0114 <class name="MyBaseClass" />
0115 <class name="edm::OwnVector<MyBaseClass, edm::ClonePolicy<MyBaseClass> >" />
0116 . . .
0117 </selection>
0118 <exclusion>
0119 <class name="edm::OwnVector<MyBaseClass, edm::ClonePolicy<MyBaseClass> >">
0120 <method name="sort" />
0121 </class>
0122 </exclusion>
0123 </lcgdict>
0124 </pre>
0125 \endhtmlonly
0126
0127 - edm::RangeMap <b><ID, C, P></b>: generic container of objects
0128 organized in a collection of type <tt><b>C</b></tt> and sorted
0129 according to an identified of type <tt><b>ID</b></tt>. It is
0130 possible to iterate over contained object, iterate over identifiers,
0131 access only objects with a specified identifier, or whose identifier
0132 match a specified criterion. The collection is sorted before being
0133 inserted in the Event. The \ref DataFormats_Common_helpers "policy" to be used
0134 to produce copies/clones of the objects during insertion and final
0135 sorting phases can be specified as template parameter <tt><b>P</b></tt>.
0136
0137 - edm::SortedCollection <b><T, SORT></b>:
0138
0139 </pre>
0140 \subsection modules Modules
0141 None.
0142
0143 \subsection tests Unit tests and examples
0144 None.
0145
0146 \section status Status and planned development
0147 Completed, stable.
0148
0149 <hr>
0150 Last updated: @DATE@ L. Lista
0151 */
