include/G4OCCT/G4OCCTSensitiveDetectorMap.hh

0001 // SPDX-License-Identifier: LGPL-2.1-or-later
0002 // Copyright (C) 2026 G4OCCT Contributors
0003
0004 /// @file G4OCCTSensitiveDetectorMap.hh
0005 /// @brief Declaration of G4OCCTSensitiveDetectorMap.
0006
0007 #ifndef G4OCCT_G4OCCTSensitiveDetectorMap_hh
0008 #define G4OCCT_G4OCCTSensitiveDetectorMap_hh
0009
0010 #include <G4String.hh>
0011
0012 #include <cstddef>
0013 #include <utility>
0014 #include <vector>
0015
0016 class G4VSensitiveDetector;
0017
0018 /**
0019  * @brief Maps volume name patterns to Geant4 G4VSensitiveDetector objects.
0020  *
0021  * Provides an ordered lookup table from volume name patterns to the
0022  * corresponding Geant4 `G4VSensitiveDetector` pointers.  Two matching
0023  * strategies are supported (checked in insertion order; first match wins):
0024  *
0025  * 1. **Exact match** — `volumeName == pattern`
0026  * 2. **Prefix match** — `volumeName` starts with `pattern + "_"` and the
0027  *    remaining suffix consists entirely of decimal digits.  This handles
0028  *    Geant4's `MakeUniqueName` deduplication convention (e.g. `"Absorber_1"`,
0029  *    `"Absorber_2"` are both matched by the pattern `"Absorber"`).
0030  *
0031  * Most volumes in a detector are not sensitive, so `Resolve()` returns
0032  * `nullptr` for unmatched names rather than throwing a fatal error.
0033  *
0034  * ### Usage
0035  * ```cpp
0036  * G4OCCTSensitiveDetectorMap sdMap;
0037  * sdMap.Add("Absorber", absorberSD);
0038  * sdMap.Add("Gap",      gapSD);
0039  *
0040  * G4VSensitiveDetector* sd = sdMap.Resolve("Absorber_1");  // returns absorberSD
0041  * G4VSensitiveDetector* no = sdMap.Resolve("World");       // returns nullptr
0042  * ```
0043  */
0044 class G4OCCTSensitiveDetectorMap {
0045 public:
0046   G4OCCTSensitiveDetectorMap() = default;
0047
0048   /**
0049    * Register a mapping from a volume name pattern to a sensitive detector.
0050    *
0051    * If @p pattern is already registered the previous entry is silently
0052    * overwritten.
0053    *
0054    * @param pattern Volume name pattern (case-sensitive).  Used for both exact
0055    *                and prefix matching (see class documentation).
0056    * @param sd      Non-null pointer to the sensitive detector.  A null pointer
0057    *                triggers a fatal `G4Exception` with code `G4OCCT_SDMap000`.
0058    */
0059   void Add(const G4String& pattern, G4VSensitiveDetector* sd);
0060
0061   /**
0062    * Look up the sensitive detector for a given volume name.
0063    *
0064    * Checks each registered entry in insertion order and returns the first
0065    * match (exact or prefix).  Returns `nullptr` if no entry matches — this
0066    * is the expected result for non-sensitive volumes.
0067    *
0068    * @param volumeName Geant4 logical volume name to resolve.
0069    * @return Pointer to the matching `G4VSensitiveDetector`, or `nullptr` if
0070    *         no entry matches.
0071    */
0072   G4VSensitiveDetector* Resolve(const G4String& volumeName) const;
0073
0074   /**
0075    * Return the number of registered entries.
0076    */
0077   std::size_t Size() const { return fEntries.size(); }
0078
0079 private:
0080   std::vector<std::pair<G4String, G4VSensitiveDetector*>> fEntries;
0081 };
0082
0083 #endif // G4OCCT_G4OCCTSensitiveDetectorMap_hh