Using Rogue Wave Tools.h++ in Reconstruction Code Bob Jacobsen (Bob_Jacobsen@LBL.Gov) Revision 0 (Draft 2) Jan 5, 1997 1 Introduction This note standardizes the use of Rogue Wave Tools.h++ classes within the BaBar recon- struction software. This standardization is needed to reduce current interoperability prob- lems, and to prevent future problems when migrating to later versions. As of the time of this writing, Tools.h++ version 7.02 has been adopted for use on BaBar software. Tools.h++ contains approximately 190 classes, organized into a number of different categories. The Tools.h++ User Guide provides a general overview of all the classes, and discusses their relative merits. This is a working document. Use of the Rogue Wave classes, this document, and gen- eral programming issues are discussed in the Monday common reconstruction meetings, and in the common reconstruction Web discussion: http://www-hep.llnl.gov/HyperNews/get/babardiscuss/recoCommon.html 2 Usage Recommendations The general recommendation is to use classes from Tools.h++ when it will simplify your design or code. In particular, the collection and container classes and string support within Tools.h++ are much more powerful than what is currently in CLHEP. 2.1 Recommended replacements for existing classes This section lists recommended classes to use in places where you would have used an existing CLHEP class. It can also be used as a starting point when figuring out which classes to look at in the Tools.h++ documentation. Of course, there may be good reasons to other classes either from Tools.h++ or elsewhere. Note that there are no, and there should not be, automatic translations between the existing classes and the recommended replacements, or in the other direction. € RWTPtrOrderedVector is similar in function to a HepAList. It can also be used with a const type to act like a HepConstAList. € RWTValOrderedVector is similar in function to a HepCList. € RWCString can replace HepString. This provides lots of additional operations for combining and using character strings, plus parsing and I/O support via other RW classes. 2.2 Limitations Use pointer-based collections instead of value-based collections of pointers. In other words, use RWTPtrDlist instead of RWTValDlist. This both reduces code complexity, and allows us to later use Rogue Wave¹s persistence system if needed. (See user guide section 14.4 for a discussion). Because they are not easily extended in length, RWTValVector and RWTPtrVector classes should only be used when their length is known at construction time. Because a class designer cannot be sure of how a user will want to construct an input list, these classes must not be specified as the type of input arguments to functions. RWTValOr- deredVector/RWTPtrOrderedVector are suitable replacements, as they can be trimmed, extended, concatenated, etc. Although Rogue Wave markets a version of the Standard Template Library (STL), it does not work with several compilers that are currently important to us. We therefore can- not use their STL, either directly or via the Tools.h++ classes. There is a discussion of this in sections 11.3 and 11.10 of the Tools.h++ User Guide. 3 Classes which should not be used 3.1 Generic collection classes All of the ³generic collection classes² should not be used. These have names of the form RWG*, and are described in chapter 12 of the User Guide. The template list classes should be used instead. 3.2 Smalltalk-like collection classes All of the ³generic collection classes² should not be used. These are described in chapter 13 of the User Guide. Unfortunately, their naming is not consistent; a complete list can be found in Table 3 of the User¹s Guide. All of these require the stored objects to inherit from RWCollectable, which no BaBar classes should do. The template list classes should be used instead. 3.3 Intrusive lists RWTIsvDlist and RWTIsvSlist are the ³intrusive lists², which require that T inherit from a specified base class. When a object is inserted on one of these lists, the superclass maintains link information. Although they can provide slightly better memory and time performance, they are basically incompatible with other forms of collections and containers. Since they are likely to cause migration problems in the future, they and their associated iterators should not be used. The RWTPtrDlist and RWTPtrSlist classes, or perhaps the RWTValDlist and RWTValSlist classes, should be used instead. 3.4 STL-specific classes As discussed above, the template classes that require STL should not be used currently. This restriction will probably be relaxed in the future. These include: RWTPtrDeque RWTPtrHashMap, RWTPtrHashMapIterator RWTPtrHashMultiMap, RWTPtrHashMultiMapIterator RWTPtrMap, RWTPtrMapIterator RWTPtrMultiMap, RWTPtrMultiMapIterator RWTPtrMultiSet, RWTPtrMultiSetIterator RWTPtrSet, RWTPtrSetIterator RWTPtrSortedDlist, RWTPtrSortedDlistIterator RWTValDeque RWTValHashMap, RWTValHashMapIterator RWTValHashMultiMap, RWTValHashMultiMapIterator RWTValMap, RWTValMapIterator RWTValMultiMap, RWTValMultiMapIterator RWTValMultiSet, RWTValMultiSetIterator RWTValSet, RWTValSetIterator RWTValSortedDlist, RWTValSortedDlistIterator Some classes have restricted interfaces, described in Appendix A of the Tools.h++ Class Reference. Only the parts of the interface available without STL should currently be used: RWTPtrDlist, RWTPtrDlistIterator RWTPtrHashMultiSet, RWTPtrHashMultiSetIterator RWTPtrHashSet, RWTPtrHashSetIterator RWTPtrHashTable, RWTPtrHashTableIterator RWTPtrOrderedVector RWTPtrSlist, RWTPtrSlistIterator RWTPtrSortedVector RWTValDlist, RWTValDlistIterator RWTValHashDictionary, RWTValHashDictionaryIterator RWTValHashMultiSet, RWTValHashMultiSetIterator RWTValHashSet, RWTValHashSetIterator RWTValHashTable, RWTValHashTableIterator RWTValOrderedVector RWTValSlist, RWTValSlistIterator RWTValSortedVector 3.5 String classes RWWString (wide character set strings) should not be used. Use RWCString instead. 4 References [1] ³Tools.h++ User¹s Guide², Version 7, Rogue Wave Software, 1996 [2] ³Tools.h++ Class Reference², Version 7, Rogue Wave Software, 1996