CVS head for this package - Administrative privileges

Description

Commonly used persistent containers.

Public interface

edm::AssociationMap <Tag>: one-to-many, one-to-one or one-to-value association based on edm::Ref. Objects in a EDM collection are associated to one or many objects in another EDM collection or to values of a specified type.

The template Tag should be one of the following:
- edm::OneToValue <CKey, Val, index> for associations by value
- edm::OneToOne <CKey, CVal, index> for one-to-one maps by reference
- edm::OneToMany <CKey, CVal, index> for one-to-many maps by reference
- edm::OneToManyWithQuality <CKey, CVal, Q, index> CKey is the collection type of the object to be associated, CVal is the collection of associated objects, Val is the associated value type and Q is the data type describing the match quality. References are stored as indices of type index, that is by default unsigned long, but could be unsigned short for collections with less than 65535 objects or unsigned char for collections with less than 255 objects.
  
  One example of basic usage is presented below:
```
  typedef edm::AssociationMap<edm::OneToMany<CaloJetCollection, TrackCollection> >
    JetTracksMap;
  JetTracksMap map;

  CaloJetRef rj = ...; 
  TrackRef rt = ...;
  map->insert( rj, rt );
  const TrackRefVector & tracks = map[ rj ];

  JetTracksMap::const_iterator i = map.find( rj );
  assert( i != map.end() );
  const CaloJetRef & jet1 = i->key;
  const TrackRefVector & tracks1 = i->val;
```
  The attribute transientMap_ has to be declared transient in the dictionary. Other used persistent types have to be declared in the dictionary, depending case by case:
```
<lcgdict>
  <class name="edm::AssociationMap< ... >" >
    <field name="transientMap_" transient="true" />
  </class >
</lcgdict>
```
edm::AssociationVector <CKey, CVal>: container very similar to std::vector<CVal>, with in addition an edm::RefProd<CKey>. Assuming the two collection of types CKey and CVal are of the same size and properly ordered, this container implements in a very simple way a one-to-one association. In order to get the reference to the i^th object in the CKey collection, the method key(i) is implemented. Below a user example:
```
  edm::AssiciationVector<reco::MuonCollection, std::vector<double> > isolations( muonRefProd );
  // fill the association ...
  for( size_t i = 0; i < isolations.size(); ++ i ) {
    double iso = isolations[ i ];
    reco::MuonRef muon = isolations.key( i );
    double pt = muon->pt();
  }
```
edm::DetSet <T>:
edm::EDCollection <T>: Functionally equivalent to std::vector<T>. Still present for hystorical reason; will be probably removed in one of the next releases.
edm::IDVectorMap <ID, C, P>:
edm::OwnVector <T, P = edm::ClonePolicy<T> >: container with interface very similar to std::vector<T>,
capable of storing polymorphic objects that are owned by the container to avoid memory leak. edm::OwnVector has functionalities very similar to boost::ptr_vector<T>, providing also EDM persistent capabilities.

The first template argument T is the common base class of polymorphic objects to be stored; the second parameter P specifies the policy required to allocate clones of the stored object. By default, it is equal to the type edm::ClonePolicy<T> assuming the type T is equipped with a virtual method clone() that returning a cloned instance of the actual concrete object. Other user-provided policy implementations are possible.

As for boost::ptr_vector, due to the polymorphic nature of contained objects, the STL std::sort function and other mutating algorithms do not work with edm::OwnVector. For this reason, functions to sort the collection are provided as class methods, using the same approach taken by boost::ptr_vector. See also this documentation from Boost library.

Please, note that for classes that do not provide a "<" operator, the function sort() has to be explicitly removed from the reflex dictionary generation. So, you should add to your classes_def.xml the following lines:
```
<lcgdict>
<selection>
  <class name="MyBaseClass" />
  <class name="edm::OwnVector<MyBaseClass, edm::ClonePolicy<MyBaseClass> >" />
  . . .
</selection>
<exclusion>
  <class name="edm::OwnVector<MyBaseClass, edm::ClonePolicy<MyBaseClass> >">
    <method name="sort" />
  </class>
</exclusion>
</lcgdict>
```
edm::RangeMap <ID, C, P>: generic container of objects organized in a collection of type C and sorted according to an identified of type ID. It is possible to iterate over contained object, iterate over identifiers, access only objects with a specified identifier, or whose identifier match a specified criterion. The collection is sorted before being inserted in the Event. The policy to be used to produce copies/clones of the objects during insertion and final sorting phases can be specified as template parameter P.
edm::SortedCollection <T, SORT>:

Modules

None.

Unit tests and examples

None.

Status and planned development

Completed, stable.

Last updated: @DATE@ L. Lista