library: libCore #include "TKey.h"

# TKey

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

## class TKey : public TNamed

| Inheritance Chart:
`TObject`
| <- | `TNamed`
| <- | `TKey` |
<- |
`TBasket` |
`TKeyXML` |

        protected:

           virtual void Create(Int_t nbytes)
          virtual Int_t Read(const char* name)

        public:

                              TKey()
                              TKey(const char* name, const char* title, const TClass* cl, Int_t nbytes)
                              TKey(const TString& name, const TString& title, const TClass* cl, Int_t nbytes)
                              TKey(const TObject* obj, const char* name, Int_t bufsize)
                              TKey(const void* obj, const TClass* cl, const char* name, Int_t bufsize)
                              TKey(Long64_t pointer, Int_t nbytes)
                              TKey(const TKey&)
                      virtual ~TKey()
                 virtual void Browse(TBrowser* b)
               static TClass* Class()
                 virtual void Delete(Option_t* option = "")
                 virtual void DeleteBuffer()
                 virtual void FillBuffer(char*& buffer)
                virtual char* GetBuffer() const
                     TBuffer* GetBufferRef() const
          virtual const char* GetClassName() const
                      Short_t GetCycle() const
               const TDatime& GetDatime() const
          virtual const char* GetIconName() const
                      Short_t GetKeep() const
                        Int_t GetKeylen() const
                        Int_t GetNbytes() const
                        Int_t GetObjlen() const
             virtual Long64_t GetSeekKey() const
             virtual Long64_t GetSeekPdir() const
          virtual const char* GetTitle() const
                        Int_t GetVersion() const
              virtual ULong_t Hash() const
              virtual TClass* IsA() const
               virtual Bool_t IsFolder() const
                 virtual void Keep()
                 virtual void ls(Option_t* option = "") const
                        TKey& operator=(const TKey&)
                 virtual void Print(Option_t* option = "") const
                virtual Int_t Read(TObject* obj)
                 virtual void ReadBuffer(char*& buffer)
                 virtual void ReadFile()
             virtual TObject* ReadObj()
                virtual void* ReadObjectAny(const TClass* expectedClass)
                 virtual void SetBuffer()
                 virtual void SetParent(const TObject* parent)
                 virtual void ShowMembers(TMemberInspector& insp, char* parent)
                virtual Int_t Sizeof() const
                 virtual void Streamer(TBuffer& b)
                         void StreamerNVirtual(TBuffer& b)
                virtual Int_t WriteFile(Int_t cycle = 1)

### Data Members

        protected:

             Int_t fVersion    Key version identifier
             Int_t fNbytes     Number of bytes for the object on file
             Int_t fObjlen     Length of uncompressed object in bytes
           TDatime fDatime     Date/Time of insertion in file
           Short_t fKeylen     Number of bytes for the key itself
           Short_t fCycle      Cycle number
          Long64_t fSeekKey    Location of object on file
          Long64_t fSeekPdir   Location of parent directory on file
           TString fClassName  Object Class name
             Int_t fLeft       Number of bytes left in current segment
             char* fBuffer     Object buffer
          TBuffer* fBufferRef  Pointer to the TBuffer object

## Class Description

      The TKey class includes functions to book space on a file,
       to create I/O buffers, to fill these buffers,
       to compress/uncompress data buffers.

      Before saving (making persistent) an object on a file, a key must
      be created. The key structure contains all the information to
      uniquely identify a persistent object on a file.
         fNbytes    = number of bytes for the compressed object+key
         fObjlen    = Length of uncompressed object
         fDatime    = Date/Time when the object was written
         fKeylen    = number of bytes for the key structure
         fCycle     = cycle number of the object
         fSeekKey   = Address of the object on file (points to fNbytes)
                      This is a redundant information used to cross-check
                      the data base integrity.
         fSeekPdir  = Pointer to the directory supporting this object
         fClassName = Object class name
         fName      = name of the object
         fTitle     = title of the object

      The TKey class is used by ROOT to:
        - to write an object in the Current Directory
        - to write a new ntuple buffer

      The structure of a file is shown in TFile::TFile.
      The structure of a directory is shown in TDirectory::TDirectory.
      The TKey class is used by the TBasket class.
      See also TTree.

TKey() : TNamed(), fDatime((UInt_t)0)

    *-*-*-*-*-*-*-*-*-*-*TKey default constructor*-*-*-*-*-*-*-*-*-*-*-*-*
    *-*                  ========================

TKey(Long64_t pointer, Int_t nbytes) : TNamed()

    *-*-*-*-*-*-*-*-*-*-*-*-*Create a TKey object to read keys*-*-*-*-*-*-*-*
    *-*                      =================================
      Constructor called by TDirectory::ReadKeys and by TFile::TFile
      A TKey object is created to read the keys structure itself

TKey(const char *name, const char *title, const TClass *cl, Int_t nbytes) : TNamed(name,title)

TKey(const TString &name, const TString &title, const TClass *cl, Int_t nbytes) : TNamed(name,title)

TKey(const TObject *obj, const char *name, Int_t bufsize) : TNamed(name, obj->GetTitle())

     Create a TKey object for a TObject* and fill output buffer

TKey(const void *obj, const TClass *cl, const char *name, Int_t bufsize) : TNamed(name, "object title")

     Create a TKey object for any object obj of class cl  and fill output buffer

void Browse(TBrowser *b)

     Read object from disk and call its Browse() method.
     If object with same name already exist in memory delete it (like
     TDirectory::Get() is doing), except when the key references a
     folder in which case we don't want to re-read the folder object
     since it might contain new objects not yet saved.

void Create(Int_t nbytes)

    *-*-*-*-*-*-*-*-*-*-*-*-*Create a TKey object *-*-*-*-*-*-*-*-*-*-*-*-*-*
    *-*                      ====================

~TKey()

    *-*-*-*-*-*-*-*-*-*-*TKey default destructor*-*-*-*-*-*-*-*-*-*-*-*-*
    *-*                  =======================

void Delete(Option_t *option)

    *-*-*-*-*-*-*-*-*-*-*-*Delete an object from the file*-*-*-*-*-*-*-*-*-*-*
    *-*                    ==============================
     Note: the key is not deleted. You still have to call "delete key".
     This is different from the behaviour of TObject::Delete()!

void DeleteBuffer()

    *-*-*-*-*-*-*-*-*-*-*-*Delete key buffer(s)*-*-*-*-*-*-*-*-*-*-*-*-*-*-*
    *-*                    ====================

Short_t GetCycle() const

    *-*-*-*-*-*-*-*-*-*-*-*-*Return cycle number associated to this key*-*-*-*
    *-*                      ==========================================

Short_t GetKeep() const

    *-*-*-*-*-*-*-*-*-*-*-*-*Returns the "KEEP" status*-*-*-*-*-*-*-*-*-*-*-*
    *-*                      =========================

void FillBuffer(char *&buffer)

    *-*-*-*-*-*-*-*-*-*-*-*Encode key header into output buffer-*-*-*-*-*-*-*
    *-*                    ====================================

ULong_t Hash() const

     This Hash function should redefine the default from TNamed

Bool_t IsFolder() const

     Check if object referenced by the key is a folder.

void Keep()

    *-*-*-*-*-*-*-*-*-*-*-*-*Set the "KEEP" status*-*-*-*-*-*-*-*-*-*-*-*-*-*
    *-*                      =====================
     When the KEEP flag is set to 1 the object cannot be purged

void ls(Option_t *) const

    *-*-*-*-*-*-*-*-*-*-*-*-*List Key contents-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*
    *-*                      =================

void Print(Option_t *) const

    *-*-*-*-*-*-*-*-*-*-*-*-*Print key contents*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*
    *-*                      ==================

TObject* ReadObj()

     To read a TObject* from the file

      The object associated to this key is read from the file into memory
      Once the key structure is read (via Streamer) the class identifier
      of the object is known.
      Using the class identifier we find the TClass object for this class.
      A TClass object contains a full description (i.e. dictionary) of the
      associated class. In particular the TClass object can create a new
      object of the class type it describes. This new object now calls its
      Streamer function to rebuilt itself.

      see TKey::ReadObjectAny to read any object non-derived from TObject

      NOTE:
      In case the class of this object derives from TObject but not
      as a first inheritance, one must cast the return value twice.
      Example1: Normal case:
          class MyClass : public TObject, public AnotherClass
       then on return, one can do:
        MyClass *obj = (MyClass*)key->ReadObj();

      Example2: Special case:
          class MyClass : public AnotherClass, public TObject
       then on return, one must do:
        MyClass *obj = dynamic_cast<MyClass*>(key->ReadObj());

      Of course, dynamic_cast<> can also be used in the example 1.

void* ReadObjectAny(const TClass* expectedClass)

      To read an object (non deriving from TObject)  from the file

      If expectedClass is not null, we checked that that actual class of
      the object stored is suitable to be stored in a pointer pointing
      to an object of class 'expectedClass'.  We also adjust the value
      of the returned address so that it is suitable to be cast (C-Style)
      a  a pointer pointing to an object of class 'expectedClass'.

      So for example if the class Bottom inherits from Top and the object
      stored is of type Bottom you can safely do:

         TClass *TopClass = TClass::GetClass("Top");
         Top *ptr = (Top*) key->ReadObjectAny( TopClass );
         if (ptr==0) printError("the object stored in the key is not of the expected type\n");

      The object associated to this key is read from the file into memory
      Once the key structure is read (via Streamer) the class identifier
      of the object is known.
      Using the class identifier we find the TClass object for this class.
      A TClass object contains a full description (i.e. dictionary) of the
      associated class. In particular the TClass object can create a new
      object of the class type it describes. This new object now calls its
      Streamer function to rebuilt itself.

Int_t Read(TObject *obj)

    *-*-*-*-*-*-*-*-*-*-*-*-*To read an object from the file*-*-*-*-*-*-*-*-*
    *-*                      ===============================
      The object associated to this key is read from the file into memory
      Before invoking this function, obj has been created via the
      default constructor.

void ReadBuffer(char *&buffer)

    *-*-*-*-*-*-*-*-*-*-*-*Decode input buffer-*-*-*-*-*-*-*-*-*-*-*-*-*-*
    *-*                    ===================

void ReadFile()

    *-*-*-*-*-*-*-*-*-*-*-*-*Read the key structure from the file-*-*-*-*-*-*
    *-*                      ====================================

void SetParent(const TObject *parent)

      Set parent in key buffer

Int_t Sizeof() const

    *-*-*-*-*-*-*-*Return the size in bytes of the key header structure*-*-*-*
    *-*-*-*-*-*-*-*====================================================
    Int_t nbytes = sizeof fNbytes;      4
                += sizeof(Version_t);   2
                += sizeof fObjlen;      4
                += sizeof fKeylen;      2
                += sizeof fCycle;       2
                += sizeof fSeekKey;     4 or 8
                += sizeof fSeekPdir;    4 or 8
                 =                     22

void Streamer(TBuffer &b)

    *-*-*-*-*-*-*-*-*Stream a class object*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*
    *-*              =========================================

Int_t WriteFile(Int_t cycle)

    *-*-*-*-*-*-*-*-*-*-*Write the encoded object supported by this key*-*-*-*
    *-*                  ==============================================

     The function returns the number of bytes committed to the file.
     If a write error occurs, the number of bytes returned is -1.

const char* GetIconName() const

     title can keep 32x32 xpm thumbnail/icon of the parent object.

const char* GetTitle() const

     returns title (title can contain 32x32 xpm thumbnail/icon)

### Inline Functions

               const char* GetClassName() const
                     char* GetBuffer() const
                  TBuffer* GetBufferRef() const
            const TDatime& GetDatime() const
                     Int_t GetKeylen() const
                     Int_t GetNbytes() const
                     Int_t GetObjlen() const
                     Int_t GetVersion() const
                  Long64_t GetSeekKey() const
                  Long64_t GetSeekPdir() const
                     Int_t Read(TObject* obj)
                      void SetBuffer()
                   TClass* Class()
                   TClass* IsA() const
                      void ShowMembers(TMemberInspector& insp, char* parent)
                      void StreamerNVirtual(TBuffer& b)
                      TKey TKey(const TKey&)
                     TKey& operator=(const TKey&)

Author: Rene Brun 28/12/94
Last update: root/base:$Name: $:$Id: TKey.cxx,v 1.48 2005/05/15 05:53:44 brun Exp $
Copyright (C) 1995-2000, Rene Brun and Fons Rademakers. *