library: libTable #include "TDataSet.h"

# TDataSet

class description - source file - inheritance tree (.pdf)

## class TDataSet : public TNamed

| Inheritance Chart:
`TObject`
| <- | `TNamed`
| <- | `TDataSet` |
<- |
`TChair` | <- |
`TColumnView` |
`TFileSet` |
`TObjectSet` | <- |
`TVolume` |
`TVolumeView` |
`TTable` | <- |
`TGenericTable` | <- |
`TResponseTable` |
`TIndexTable` |
| [more...]

        private:

          void operator=(const TDataSet&)

        protected:

                                        TDataSet(const char* name, const char* title)
                                   void AddMain(TDataSet* set)
                              TDataSet* GetRealParent()
                                   void MakeCollection()
                           virtual void SetMother(TObject* mother)
          static TDataSet::EDataSetPass SortIt(TDataSet* ds)
          static TDataSet::EDataSetPass SortIt(TDataSet* ds, void* user)

        public:

                                         TDataSet(const char* name = "", TDataSet* parent = 0, Bool_t arrayFlag = kFALSE)
                                         TDataSet(const TDataSet& src, TDataSet::EDataSetPass iopt = kAll)
                                         TDataSet(TNode& src)
                                 virtual ~TDataSet()
                            virtual void Add(TDataSet* dataset)
                            virtual void AddAt(TDataSet* dataset, Int_t idx = 0)
                            virtual void AddAtAndExpand(TDataSet* dataset, Int_t idx = 0)
                            virtual void AddFirst(TDataSet* dataset)
                            virtual void AddLast(TDataSet* dataset)
                               TDataSet* At(Int_t idx) const
                            virtual void Browse(TBrowser* b)
                          static TClass* Class()
                        virtual TObject* Clone(const char* newname = "") const
                            virtual void Delete(Option_t* opt = "")
                       virtual TDataSet* Find(const char* path) const
                       virtual TDataSet* FindByName(const char* name, const char* path = "", Option_t* opt = "") const
                       virtual TDataSet* FindByPath(const char* path) const
                       virtual TDataSet* FindByTitle(const char* title, const char* path = "", Option_t* opt = "") const
                        virtual TObject* FindObject(const char* name) const
                        virtual TObject* FindObject(const TObject* o) const
                       virtual TDataSet* First() const
                 virtual TSeqCollection* GetCollection() const
                                  TList* GetList() const
                           virtual Int_t GetListSize() const
                        static TDataSet* GetMainSet()
                                TObject* GetMother() const
                              TObjArray* GetObjArray() const
                        virtual TObject* GetObject() const
                       virtual TDataSet* GetParent() const
                          virtual Long_t HasData() const
                       virtual TDataSet* Instance() const
                        static TDataSet* instance()
                                    void InvertAllMarks()
                         virtual TClass* IsA() const
                          virtual Bool_t IsEmpty() const
                          virtual Bool_t IsFolder() const
                          virtual Bool_t IsMarked() const
                          virtual Bool_t IsThisDir(const char* dirname, int len = -1, int ignorecase = 0) const
                       virtual TDataSet* Last() const
                            virtual void ls(Option_t* option = "") const
                            virtual void ls(Int_t depth) const
                                    void Mark()
                                    void Mark(UInt_t flag, TDataSet::EBitOpt reset = kSet)
                                    void MarkAll()
                       virtual TDataSet* Next() const
          virtual TDataSet::EDataSetPass Pass(void callback, Int_t depth = 0)
          virtual TDataSet::EDataSetPass Pass(void callback, void* user, Int_t depth = 0)
                         virtual TString Path() const
                       virtual TDataSet* Prev() const
                            virtual void PrintContents(Option_t* opt = "") const
                           virtual Int_t Purge(Option_t* opt = "")
                            virtual void Remove(TDataSet* set)
                       virtual TDataSet* RemoveAt(Int_t idx)
                            virtual void SetMother(TDataSet* parent = 0)
                            virtual void SetObject(TObject* obj)
                            virtual void SetParent(TDataSet* parent = 0)
                            virtual void SetWrite()
                            virtual void ShowMembers(TMemberInspector& insp, char* parent)
                            virtual void Shunt(TDataSet* newParent = 0)
                            virtual void Sort()
                            virtual void Streamer(TBuffer& b)
                                    void StreamerNVirtual(TBuffer& b)
                                    void UnMark()
                                    void UnMarkAll()
                            virtual void Update()
                            virtual void Update(TDataSet* set, UInt_t opt = 0)
                           virtual Int_t Write(const Text_t* name = "0", Int_t option = 0, Int_t bufsize = 0)
                           virtual Int_t Write(const Text_t* name = "0", Int_t option = 0, Int_t bufsize = 0) const

### Data Members

        protected:

          static TDataSet* fgMainSet  pointer the main dataset;
                 TDataSet* fParent    pointer to mother of the directory
           TSeqCollection* fList      List of the the the objects included into this dataset

        public:

          static const TDataSet::EDataSetPass kContinue
          static const TDataSet::EDataSetPass kPrune
          static const TDataSet::EDataSetPass kStop
          static const TDataSet::EDataSetPass kUp
          static const TDataSet::EDataSetPass kStruct
          static const TDataSet::EDataSetPass kAll
          static const TDataSet::EDataSetPass kRefs
          static const TDataSet::EDataSetPass kMarked
              static const TDataSet::ESetBits kMark
              static const TDataSet::ESetBits kArray
               static const TDataSet::EBitOpt kSet
               static const TDataSet::EBitOpt kReset

## Class Description

     TDataSet

     TDataSet class is to create a special compound object-container:

     ====================================================================
        TDataSet object ::= the "named" list of TDataSet objects
     ====================================================================
     where the "list" (the pointer to TList object) may contain no object

      TDataSet object has a back pointer to its "parent" TDataSet
      object, the "character" *name* and "character" *title*

      The service this class does provide is to help the user to build
      and manage the hierarchy of his/her data but the data itself.

      So it is not "Container" itself rather the basement (base class)
      to built the containers.

      One may derive the custom container classes from TDataSet.
      See for example TObjectSet, TTable, TVolume, TFileSet
      These classes  derived from TDataSet:

       Class Name
       ----------
      TObjectSet::public TDataSet - is a container for TObject
      TTable::public TDataSet - is a container for the array
                                        of any "plain" C-structure
      TNode::public TDataSet - is a container for 3D objects
      TMaker::     public TDataSet - is a container for STAR "control"
                                        objects
       etc etc

      TDataSet class is a base class to implement the directory-like
      data structures and maintain it via TDataSetIter class iterator

     TDataSet can be iterated using an iterator object (see TDataSetIter)
                or by TDataSet::Pass method (see below)

      Terms:    Dataset       - any object from the list above
      =====     Member          is called "DataSet Member"

              Structural      - the "Dataset Member" is its
                member          "Structural member" if its "back pointer"
                                points to this object

               Dataset        - we will say this TDataSet object "OWNs"
                Owner           (or is an OWNER / PARENT of ) another
              (parent)          TDataSet object if the last one is its
                                "Structural Member"

              Associated      - If some object is not "Structural member"
                member          of this object we will say it is an
                                "Associated Member" of this dataset

               Orphan         - If some dataset is a member of NO other
               dataset          TDataSet object it is called an "orphan"
                                dataset object

     - Any TDataSet object may be "Owned" by one and only one another
       TDataSet object if any.

     - Any TDataSet object can be the "Structural Member" of one and
       only one another TDataSet

     - Any TDataSet object may be an "Associated Member" for any number
       of other TDataSet objects if any

     - NAME issue:
       Each "dataset member" is in possession of some "alpha-numerical"
       NAME as defined by TNamed class.
       The NAME may contain any "printable" symbols but "SLASH" - "/"
       The symbol "RIGHT SLASH" - "/" can not be used as any part of the
       "DataSet Member" NAME
        Any DataSet  can be found by its NAME with TDataSetIter object

     - TITLE issue:
       Each "dataset member" is in possession of the "alpha-numerical"
       TITLE as defined by TNamed class. The meaning of the TITLE is
       reserved for the derived classes to hold there some indetification
       that is special for that derived class.

       This means the user must be careful about  the "TDataSet
       NAME and TITLE since this may cause some "side effects" of the
       particular class functions

     - It is NOT required those all "DataSet Members" are in possession
       of the unique names, i.e. any number of "DataSet Members"
       may bear one and the same name

       Actions:
       ========
       Create  DataSet is born either as "Orphan" or
                                      as "Structural Member"
               of another TDataSet object

       Add     One dataset can be included into another dataset.
               Upon adding:
               -  the "Orphan dataset" becomes "Structural Member"
               - "Structural Members" of another dataset becomes the
                 "Associated Member" of this datatset

       Delete  - Upon deleting the "Structural Member":
                 - "REMOVES" itself  from the "Parent DataSet".
                 - Its "Associated memberships" is not changed though

                  The last means the DataSet with the "Associated Members"
                  may contain a DIED pointers to unexisting "Associated"
                  objects !!!

      Further information is provided my the particular method
      descriptions.

      The TDataSet class has several methods to control object('s)
      memberships

TDataSet(const Char_t *name, TDataSet *parent, Bool_t arrayFlag) : TNamed(name,"TDataSet"),fParent(0),fList(0)

      cout << "ctor for " << GetName() << " - " << GetTitle() << endl;

TDataSet* GetRealParent()

TDataSet(const TDataSet &pattern,EDataSetPass iopt):TNamed(pattern.GetName(),pattern.GetTitle()), fParent(0),fList(0)

     Creates TDataSet (clone) with a topology similar with TDataSet *pattern

      Parameters:
      -----------
      pattern        - the pattern dataset
      iopt = kStruct - clone only my structural links
             kAll    - clone all links
             kRefs   - clone only refs
             kMarked - clone marked (not implemented yet) only

       All new-created sets become the structural ones anyway.

      cout << "ctor for " << GetName() << " - " << GetTitle() << endl;

TDataSet(TNode &)

~TDataSet()

                  cout << "Default destructor for " << GetName() << " - " << GetTitle() << endl;

void MakeCollection()

void AddAt(TDataSet *dataset,Int_t idx)

     Add TDataSet object at the "idx" position in ds
     or at the end of the dataset
     The final result is defined by either TList::AddAt or TObjArray::AddAt
     methods

void AddAtAndExpand(TDataSet *dataset, Int_t idx)

       !!!! Under construction !!!!!
     Add TDataSet object at the "idx" position in ds
     or at the end of the dataset
     The final result is defined by either TList::AddAt or TObjArray::AddAt
     methods

void AddLast(TDataSet *dataset)

     Add TDataSet object at the end of the dataset list of this dataset

void AddFirst(TDataSet *dataset)

     Add TDataSet object at the beginning of the dataset list of this dataset

void Browse(TBrowser *b)

     Browse this dataset (called by TBrowser).

TObject* Clone(const char*) const

void Delete(Option_t *opt)

     Delete - deletes the list of the TDataSet objects and all "Structural Members"
              as well
              This method doesn't affect the "Associated Members"

TDataSet* FindByPath(const Char_t *path) const

     Aliase for TDataSet::Find(const Char_t *path) method

TDataSet* Find(const Char_t *path) const

     Full description see: TDataSetIter::Find

     Note. This method is quite expansive.
     ----- It is done to simplify the user's code when one wants to find ONLY object.
           If you need to find more then 1 object in this dataset,
           regard using TDataSetIter class yourself.

TDataSet* FindByName(const Char_t *name,const Char_t *path,Option_t *opt) const

     Full description see: TDataSetIter::Find

     Note. This is method is quite expansive.
     ----- It is done to simplify the user's code when one wants to find ONLY object.
           If you need to find more then 1 object in this dataset,
           regard using TDataSetIter class yourself.

TDataSet* FindByTitle(const Char_t *title,const Char_t *path,Option_t *opt) const

     Full description see: TDataSetIter::Find

     Note. This method is quite expansive.
     ----- It is done to simplify the user's code when one wants to find ONLY object.
           If you need to find more then 1 object in this dataset,
           regard using TDataSetIter class yourself.

TDataSet* First() const

      Return the first object in the list. Returns 0 when list is empty.

TObject* GetObject() const

TDataSet* Last() const

     Return the last object in the list. Returns 0 when list is empty.

TDataSet* Next() const

     Return the object next to this one in the parent structure
     This convinient but time-consuming. Don't use it in the inner loops

TDataSet* Prev() const

     Return the object that is previous to this one in the parent structure
     This convinient but time-consuming. Don't use it in the inner loops

void SetObject(TObject * /*obj*/)

void ls(Option_t *option) const

      ls(Option_t *option)

        option       - defines the path to be listed
               = "*" -  means print all levels

void ls(Int_t depth) const

      ls(Int_t depth)

      Prints the list of the this TDataSet.

      Parameter:
      =========
        Int_t depth >0 the number of levels to be printed
                   =0 all levels will be printed
                No par - ls() prints only level out

TDataSet* Instance() const

     apply the class default ctor to instantiate a new object of the same kind.
     This is a base method to be overriden by the classes
     derived from TDataSet (to support TDataSetIter::Mkdir for example)

Bool_t IsThisDir(const Char_t *dirname,int len,int ignorecase) const

void MarkAll()

     Mark all members of this dataset

void UnMarkAll()

     UnMark all members of this dataset

void InvertAllMarks()

     Invert mark bit for all members of this dataset

Bool_t IsEmpty() const

     return kTRUE if the "internal" collection has no member

void PrintContents(Option_t *opt) const

     Callback method to complete ls() method recursive loop
     This is to allow to sepoarate navigation and the custom invormation
     in the derived classes (see; TTable::PrintContents for example

TString Path() const

     return the full path of this data set

void Remove(TDataSet *set)

TDataSet* RemoveAt(Int_t idx)

     Remove object from the "idx" cell of this set and return
     the pointer to the removed object if any

Int_t Purge(Option_t *)

     Purge  - deletes all "dummy" "Structural Members" those are not ended
              up with some dataset with data inside (those return HasData() = 0)

     Purge does affect only the "Structural Members" and doesn't "Associated" ones

void SetParent(TDataSet *parent)

      Break the "parent" relationship with the current object parent if present
      parent != 0   Makes this object the "Structural Member"
                    of the "parent" dataset
              = 0   Makes this object the "pure Associator", i.e it makes this
                    object the "Structural Member" of NO other TDataSet

void SetWrite()

     One should not use this method but TDataSet::Write instead
     This method os left here for the sake of the backward compatibility
     To Write object first we should temporary break the
     the backward fParent pointer (otherwise ROOT follows this links
     and will pull fParent out too.

void Shunt(TDataSet *newParent)

      Remove the object from the original and add it to dataset
      TDataSet dataset   != 0  -  Make this object the "Structural Member"
                                    of "dataset"
                            = 0  -  Make this object "Orphan"

void Update(TDataSet* set,UInt_t opt)

     Update this TDataSet with "set"

     ATTENTION !!!
     ---------
     This method changes the parent relationships of the input "set"

void Update()

      Update()

      Recursively updates all tables for all nested datasets
      in inverse order

void Sort()

Int_t Write(const Text_t *name, Int_t option, Int_t bufsize)

     To Write object first we should temporary break the
     the backward fParent pointer (otherwise ROOT follows this links
     and will pull fParent out too.

Int_t Write(const Text_t *name, Int_t option, Int_t bufsize) const

     To Write object first we should temporary break the
     the backward fParent pointer (otherwise ROOT follows this links
     and will pull fParent out too.

### Inline Functions

                              void operator=(const TDataSet&)
                              void SetMother(TObject* mother)
                              void AddMain(TDataSet* set)
            TDataSet::EDataSetPass SortIt(TDataSet* ds)
            TDataSet::EDataSetPass SortIt(TDataSet* ds, void* user)
                          TDataSet TDataSet(TNode& src)
                              void Add(TDataSet* dataset)
                         TDataSet* At(Int_t idx) const
                          TObject* FindObject(const char* name) const
                          TObject* FindObject(const TObject* o) const
                        TObjArray* GetObjArray() const
                   TSeqCollection* GetCollection() const
                            TList* GetList() const
                             Int_t GetListSize() const
                         TDataSet* GetMainSet()
                          TObject* GetMother() const
                         TDataSet* GetParent() const
                            Long_t HasData() const
                         TDataSet* instance()
            TDataSet::EDataSetPass Pass(void callback, Int_t depth = 0)
            TDataSet::EDataSetPass Pass(void callback, void* user, Int_t depth = 0)
                              void SetMother(TDataSet* parent = 0)
                            Bool_t IsFolder() const
                            Bool_t IsMarked() const
                              void Mark()
                              void UnMark()
                              void Mark(UInt_t flag, TDataSet::EBitOpt reset = kSet)
                           TClass* Class()
                           TClass* IsA() const
                              void ShowMembers(TMemberInspector& insp, char* parent)
                              void Streamer(TBuffer& b)
                              void StreamerNVirtual(TBuffer& b)

Author: Valery Fine(fine@mail.cern.ch) 03/07/98
Last update: root/star:$Name: $:$Id: TDataSet.cxx,v 1.9 2005/06/06 14:36:06 brun Exp $