include/root/TLeaf.h

0001 // @(#)root/tree:$Id$
0002 // Author: Rene Brun   12/01/96
0003
0004 /*************************************************************************
0005  * Copyright (C) 1995-2000, Rene Brun and Fons Rademakers.               *
0006  * All rights reserved.                                                  *
0007  *                                                                       *
0008  * For the licensing terms see $ROOTSYS/LICENSE.                         *
0009  * For the list of contributors see $ROOTSYS/README/CREDITS.             *
0010  *************************************************************************/
0011
0012 #ifndef ROOT_TLeaf
0013 #define ROOT_TLeaf
0014
0015
0016 //////////////////////////////////////////////////////////////////////////
0017 //                                                                      //
0018 // TLeaf                                                                //
0019 //                                                                      //
0020 // A TTree object is a list of TBranch.                                 //
0021 // A TBranch object is a list of TLeaf.  In most cases, the TBranch     //
0022 // will have one TLeaf.                                                 //
0023 // A TLeaf describes the branch data types and holds the data.          //
0024 //                                                                      //
0025 // A few notes about the data held by the leaf.  It can contain:        //
0026 //   1 a single object or primitive (e.g., one float),                  //
0027 //   2 a fixed-number of objects (e.g., each entry has two floats).     //
0028 //     The number of elements per entry is saved in `fLen`.             //
0029 //   3 a dynamic number of primitives.  The number of objects in each   //
0030 //     entry is saved in the `fLeafCount` branch.                       //
0031 //                                                                      //
0032 // Note options (2) and (3) can combined - if fLeafCount says an entry  //
0033 // has 3 elements and fLen is 2, then there will be 6 objects in that   //
0034 // entry.                                                               //
0035 //                                                                      //
0036 // Additionally, `fNdata` is transient and generated on read to         //
0037 // determine the necessary size of a buffer to hold event data;         //
0038 // depending on the call-site, it may be sized larger than the number   //
0039 // of elements                                                          //
0040 //                                                                      //
0041 //////////////////////////////////////////////////////////////////////////
0042
0043
0044 #include "TNamed.h"
0045
0046 #include <vector>
0047
0048 #ifdef R__LESS_INCLUDES
0049 class TBranch;
0050 #else
0051 #include "TBranch.h"
0052 #endif
0053
0054 class TClonesArray;
0055 class TBrowser;
0056
0057 class TLeaf : public TNamed {
0058
0059 private:
0060
0061    virtual Int_t GetOffsetHeaderSize() const {return 0;}
0062
0063 protected:
0064
0065    using Counts_t = std::vector<Int_t>;
0066    struct LeafCountValues {
0067       Counts_t fValues;
0068       Long64_t fStartEntry{-1}; ///<! entry number of corresponding to element 0 of the vector.
0069    };
0070
0071    Int_t            fNdata;           ///<! Number of elements in fAddress data buffer.
0072    Int_t            fLen;             ///<  Number of fixed length elements in the leaf's data.
0073    Int_t            fLenType;         ///<  Number of bytes for this data type
0074    Int_t            fOffset;          ///<  Offset in ClonesArray object (if one)
0075    bool             fIsRange;         ///<  (=true if leaf has a range, false otherwise).  This is equivalent to being a 'leafcount'.  For a TLeafElement the range information is actually store in the TBranchElement.
0076    bool             fIsUnsigned;      ///<  (=true if unsigned, false otherwise)
0077    TLeaf           *fLeafCount;       ///<  Pointer to Leaf count if variable length (we do not own the counter)
0078    TBranch         *fBranch;          ///<! Pointer to supporting branch (we do not own the branch)
0079    LeafCountValues *fLeafCountValues; ///<! Cache of collection/array sizes
0080
0081    TLeaf(const TLeaf&);
0082    TLeaf& operator=(const TLeaf&);
0083
0084   template <typename T> struct GetValueHelper {
0085     static T Exec(const TLeaf *leaf, Int_t i = 0) { return leaf->GetValue(i); }
0086   };
0087
0088   Int_t *GenerateOffsetArrayBase(Int_t base, Int_t events) const; // For leaves containing fixed-size objects (no
0089                                                                   // polymorphism!), this will generate an appropriate
0090                                                                   // offset array.
0091
0092
0093 public:
0094    enum EStatusBits {
0095       kIndirectAddress = BIT(11), ///< Data member is a pointer to an array of basic types.
0096       kNewValue = BIT(12)         ///< Set if we own the value buffer and so must delete it ourselves.
0097    };
0098
0099    enum class DeserializeType {
0100       kInvalid = 0,      // Invalid deserialization information.
0101       kExternal,         // Deserialization of this Leaf requires a separate output buffer, i.e. the on-disk and in-memory representation are likely to be different sizes.
0102       kDestructive = kExternal, // For backward compatibility
0103       kInPlace,          // Deserialization can be done directly in the input buffer.
0104       kZeroCopy,         // In-memory and on-disk representation of this object are identical.
0105    };
0106
0107    TLeaf();
0108    TLeaf(TBranch *parent, const char *name, const char *type);
0109    ~TLeaf() override;
0110
0111            void     Browse(TBrowser *b) override;
0112    virtual bool     CanGenerateOffsetArray() {return fLeafCount;} // overload and return true if this leaf can generate its own offset array.
0113    virtual void     Export(TClonesArray *, Int_t) {}
0114    virtual void     FillBasket(TBuffer &b);
0115    virtual Int_t   *GenerateOffsetArray(Int_t base, Int_t events) { return GenerateOffsetArrayBase(base, events); }
0116    TBranch         *GetBranch() const { return fBranch; }
0117    virtual DeserializeType GetDeserializeType() const { return DeserializeType::kExternal; }
0118    virtual TString  GetFullName() const;
0119    ///  If this leaf stores a variable-sized array or a multi-dimensional array whose last dimension has variable size,
0120    ///  return a pointer to the TLeaf that stores such size. Return a nullptr otherwise.
0121    virtual TLeaf   *GetLeafCount() const { return fLeafCount; }
0122    virtual TLeaf   *GetLeafCounter(Int_t &countval) const;
0123
0124    virtual const Counts_t *GetLeafCountValues(Long64_t start, Long64_t len);
0125
0126    virtual Int_t    GetLen() const;
0127    /// Return the fixed length of this leaf.
0128    /// If the leaf stores a fixed-length array, this is the size of the array.
0129    /// If the leaf stores a non-array or a variable-sized array, this method returns 1.
0130    /// If the leaf stores an array with 2 or more dimensions, this method returns the total number of elements in the
0131    /// dimensions with static length: for example for float[3][2][] it would return 6.
0132    virtual Int_t    GetLenStatic() const { return fLen; }
0133    virtual Int_t    GetLenType() const { return fLenType; }
0134    virtual Int_t    GetMaximum() const { return 0; }
0135    virtual Int_t    GetMinimum() const { return 0; }
0136    virtual Int_t    GetNdata() const { return fNdata; }
0137    virtual Int_t    GetOffset() const { return fOffset; }
0138    virtual void    *GetValuePointer() const { return nullptr; }
0139    virtual const char *GetTypeName() const { return ""; }
0140
0141    virtual Double_t GetValue(Int_t i = 0) const;
0142    virtual Long64_t GetValueLong64(Int_t i = 0) const { return GetValue(i); }         // overload only when it matters.
0143    virtual LongDouble_t GetValueLongDouble(Int_t i = 0) const { return GetValue(i); } // overload only when it matters.
0144    template <typename T> T GetTypedValue(Int_t i = 0) const { return GetValueHelper<T>::Exec(this, i); }
0145
0146    virtual bool     IncludeRange(TLeaf *) { return false; } // overload to copy/set fMinimum and fMaximum to include/be wide than those of the parameter
0147    virtual void     Import(TClonesArray *, Int_t) {}
0148    virtual bool     IsOnTerminalBranch() const { return true; }
0149    virtual bool     IsRange() const { return fIsRange; }
0150    virtual bool     IsUnsigned() const { return fIsUnsigned; }
0151    virtual void     PrintValue(Int_t i = 0) const;
0152    virtual void     ReadBasket(TBuffer &) {}
0153    virtual void     ReadBasketExport(TBuffer &, TClonesArray *, Int_t) {}
0154    virtual bool     ReadBasketFast(TBuffer&, Long64_t) { return false; }  // Read contents of leaf into a user-provided buffer.
0155    virtual bool     ReadBasketSerialized(TBuffer&, Long64_t) { return true; }
0156    virtual void     ReadValue(std::istream & /*s*/, Char_t /*delim*/ = ' ') {
0157       Error("ReadValue", "Not implemented!");
0158    }
0159            Int_t    ResetAddress(void *add, bool calledFromDestructor = false);
0160    virtual void     SetAddress(void *add = nullptr);
0161    virtual void     SetBranch(TBranch *branch) { fBranch = branch; }
0162    virtual void     SetLeafCount(TLeaf *leaf);
0163    virtual void     SetLen(Int_t len = 1) { fLen = len; }
0164    virtual void     SetOffset(Int_t offset = 0) { fOffset = offset; }
0165    virtual void     SetRange(bool range = true) { fIsRange = range; }
0166    virtual void     SetUnsigned() { fIsUnsigned = true; }
0167
0168    ClassDefOverride(TLeaf, 2); // Leaf: description of a Branch data type
0169 };
0170
0171
0172 template <> struct TLeaf::GetValueHelper<Long64_t> {
0173    static Long64_t Exec(const TLeaf *leaf, Int_t i = 0) { return leaf->GetValueLong64(i); }
0174 };
0175 template <> struct TLeaf::GetValueHelper<ULong64_t> {
0176    static ULong64_t Exec(const TLeaf *leaf, Int_t i = 0) { return (ULong64_t)leaf->GetValueLong64(i); }
0177 };
0178 template <> struct TLeaf::GetValueHelper<LongDouble_t> {
0179    static LongDouble_t Exec(const TLeaf *leaf, Int_t i = 0) { return leaf->GetValueLongDouble(i); }
0180 };
0181
0182
0183 inline Double_t TLeaf::GetValue(Int_t /*i = 0*/) const { return 0.0; }
0184 inline void     TLeaf::PrintValue(Int_t /* i = 0*/) const {}
0185 inline void     TLeaf::SetAddress(void* /* add = 0 */) {}
0186
0187 #endif