NavItr.cxx

Go to the documentation of this file.

// $Id: NavItr.cxx,v 1.11 2003/03/25 07:43:40 west Exp $
//
// NavItr
//
// Package: Nav (Navigational Model).

// Begin_Html<img src="../../pedestrians.gif" align=center>
// <a href="../source_warning.html">Warning for beginners</a>.<br>
// Also see <a href="../../root_crib/index.html">The ROOT Crib</a> and
// <a href="../index.html">The MINOS Class User Guide</a>End_Html
//
// N. West 03/20000
//
//   
// Purpose: 
//
//

#include <string.h>
#include "MessageService/MsgService.h"
#include "LeakChecker/Lea.h"
#include "Navigation/NavItr.h"
#include "Navigation/NavPrimer.h"
#include "Navigation/NavSet.h"
#include "Lattice/Lattice.h"
#include "TCollection.h"
#include "TClass.h"


ClassImp(NavItr)

//   Definition of static data members
//   *********************************

CVSID("$Id: NavItr.cxx,v 1.11 2003/03/25 07:43:40 west Exp $");


// Definition of member functions (alphabetical order)
// ***************************************************

//.....................................................................

void NavItr:: Attach(const TCollection* source,  
                    const Text_t* classname, 
                    Int_t offset) {
//
//
//  Purpose:  Attach iterator to TCollection.
//
//  Arguments: 
//    source       in    source set for iterator.
//    classname    in    Name of class associated with NavItr.
//    offset       in    Pointer offset: Object adr - TObject adr
//
//  Return:    n/a
//
//  Contact:   N. West
//
//  Specification:-
//  =============
//
//  o Disconnect any existing collection.
//
//  o Create new NavSet derived from a TCollection and attach it.


//  Program Notes:-
//  =============

//  Can be called from ctor so long as fSet has been set to zero.

  Disconnect();
  Init();

//    NavSet will check that the supplied TCollection really does 
//    exist and contains the correct class.

  fSet = new NavSet(source, classname, offset);
  Connect();

}

//.....................................................................

void NavItr::Connect() {
//
//
//  Purpose:  Connect to current NavSet (if any)
//
//  Arguments: n/a
//
//  Return:    n/a
//
//  Contact:   N. West
//
//  Specification:-
//  =============
//
//  o If current NavSet exists connect to it.
//
//  o Set up as a rank 0 iterator.


//  Program Notes:-
//  =============

// None.

  if ( fSet ) fSet->Attach(this);
  Init(fSet);

}
//.....................................................................

NavItr& NavItr::Copy(const NavItr& from) {
//
//
//  Purpose:  Replace current state with from object.
//
//  Arguments: 
//    from         in    Object whose state is to be copied.
//
//  Return:    
//
//  Contact:   N. West
//
//  Specification:-
//  =============
//
//  o Detach object from current NavSet (if any).
//
//  o Copy state from input object and reconnect to new NavSet.

//  Program Notes:-
//  =============

//  None.

  Disconnect();
  fSet         = from.fSet;
  Connect();
  fDefaultStep = from.fDefaultStep;
  fIndex       = from.fIndex;
  fLimLo       = from.fLimLo;
  fLimHi       = from.fLimHi;
  fRank        = from.fRank;
  fZoneLo      = from.fZoneLo;
  fZoneHi      = from.fZoneHi;

  return *this;

}

//.....................................................................

 Bool_t NavItr::Decrement() {
//
//
//  Purpose:  Decrement pointer skipping unwanted objects.
//
//  Arguments: None.
//
//  Return: kTRUE if pointer is positioned on a valid object.  
//
//  Contact:   N. West
//
//  Specification:-
//  =============
//
//  o  Decrement pointer skipping unwanted objects.

//  Program Notes:-
//  =============

//  None.

   fIndex--;
   return IsValid();

}
//.....................................................................

void NavItr::Disconnect() {
//
//
//  Purpose:  Disconnect from current NavSet (if any)
//
//  Arguments: n/a
//
//  Return:    n/a
//
//  Contact:   N. West
//
//  Specification:-
//  =============
//
//  o If connected to a NavSet, and disconnecting leave it ownerless
//    then delete it.


//  Program Notes:-
//  =============

//  A single NavSet can be shared by any number of NavItrs, hence
//  this reference counting logic.

  if ( fSet && ! fSet->Detach(this) ) delete fSet;
  Init();
 
}

//.....................................................................

NavKey NavItr::GetNavKey() const {
//
//
//  Purpose:  Return associated NavKey.
//
//  Arguments: None.
//
//  Return:  Return associated NavKey or NavKey(0) if none. 
//
//  Contact:   N. West
//
//  Specification:-
//  =============
//
//  o Return associated NavKey or NavKey(0) if none. 

//  Program Notes:-
//  =============

//  None.

  return ( fSet && IsValid() ) ? fSet->GetNavKey(fIndex,fRank) : 0;

}

//.....................................................................

void NavItr::GetZone() const {
//
//
//  Purpose:  Get zone limits into fZoneLo, fZoneHi cache.
//
//  Arguments: none.
//
//  Return:   n/a
//
//  Contact:   N. West
//
//  Specification:-
//  =============
//
//  o Get zone limits into fZoneLo, fZoneHi cache.

//  Program Notes:-
//  =============

//  The zone limits is the range of indeces containing the current
//  index and bounded by (fLimLo,fLimHi) within which the associated
//  NavKey has a single value.  Finding zone limits is an expensive
//  operation so they are cached in fZoneLo, fZoneHi and reused if
//  possible.  Consequently these members are not really true state
//  but just an optimisation so this const member function is allowed
//  to modify them.

  if (    fZoneLo <= fIndex
       && fZoneHi >= fIndex ) return;

  Int_t lo = fLimLo;
  Int_t hi = fLimHi;
  if ( fSet ) fSet->GetZone(fLimLo,fLimHi,fIndex,fRank,lo,hi);
  
// Allow write access (see Program Notes).
  NavItr* itr = const_cast<NavItr*>(this);
  itr->fZoneLo = lo;
  itr->fZoneHi = hi;

}

//.....................................................................

 Bool_t NavItr::Increment() {
//
//
//  Purpose:  Increment pointer skipping unwanted objects.
//
//  Arguments: None.
//
//  Return: kTRUE if pointer is positioned on a valid object.  
//
//  Contact:   N. West
//
//  Specification:-
//  =============
//
//  o  Increment pointer skipping unwanted objects.

//  Program Notes:-
//  =============

//  None.

   fIndex++;
   return IsValid();

}
//.....................................................................

void NavItr::Init(NavSet* set) {
//
//
//  Purpose:  Initialise an empty object.
//
//  Arguments: 
//      set      in    Associated NavSet (if any).
//
//  Return:    n/a
//
//  Contact:   N. West
//
//  Specification:-
//  =============
//
//  o Initialise an empty object.

//  Program Notes:-
//  =============

//  None.

  fIndex       = 0;
  fLimLo       = 0;
  if ( set ) fLimHi = fSet->GetMaxIndex();
  else       fLimHi = -1;
  fSet         = set;
  fRank        = 0;
  fZoneLo      = 0;
  fZoneHi      = -1;
  fDefaultStep = 1;
}

//.....................................................................

Bool_t NavItr::IsValid(Int_t index) const{


//  Purpose:  Check if index is valid (i.e. within selected range).
//
//  Arguments: 
//    index        in    Index to be checked.
//
//  Return:    
//
//  Contact:   N. West
//
//  Specification:-
//  =============
//
//  o Check if index is valid.

//  Program Notes:-
//  =============

//  None.

  return index >= fLimLo && index <= fLimHi;

}

//.....................................................................

void* NavItr::Map(const void* far) {


//  Purpose:  Select objects associated with supplied object
//            on far side of Lattice.
//
//  Arguments: 
//    far          in    Far side object.
//
//  Return:   First object in the set or = 0 if none. 
//
//  Contact:   N. West
//
//  Specification:-
//  =============
//
//  o Select the objects associated with the Lattice far object and 
//    return the first of them.

//  Program Notes:-
//  =============

//  CAUTION: This member function directly effects the associated
//           NavSet and causes all its iterators to reposition at 
//           start of their range.  This would be more apparent if
//           the user did the longer equivalent:-
//
//           XxxItr* myItr;
//           myItr->GetSet()->Map(far);
//           Xxx* myObj = myItrPtr();

  fSet->Map(far);
  return Ptr();

}

//.....................................................................

NavItr::NavItr(const Text_t* classname, Int_t offset) {
//
//
//  Purpose:  Construct iterator over TCollection.
//
//  Arguments: 
//    classname    in    Name of class associated with NavItr.
//    offset       in    Pointer offset: Object adr - TObject adr
//
//  Return:   n/a
//
//  Contact:   N. West
//
//  Specification:-
//  =============
//
//  o Ask NavPrimer for the default TCollection for this type of
//    object.
//
//  o Create new NavSet derived from a TCollection and attach it.

//  Program Notes:-
//  =============

//  None.

  LEA_CTOR  //Leak Checker

  Init();

  const TCollection* source = NavPrimer::Instance()->
                              FindTCollection(classname);
  if ( source ) {
    fSet = new NavSet(source, classname, offset);
    Connect();
  }

}
//.....................................................................

NavItr::NavItr() {
//
//
//  Purpose:  Default constructor.
//
//  Arguments: 
//    None.
//
//  Return:   n/a
//
//  Contact:   N. West
//
//  Specification:-
//  =============
//
//  o Default constructor.

//  Program Notes:-
//  =============

//  None.

  LEA_CTOR  //Leak Checker

  Init();

}
//.....................................................................

NavItr::NavItr(const NavItr& from, Bool_t subSlice) {
//
//
//  Purpose:  Copy or sub-slice constructor.
//
//  Arguments: 
//    from      in    Iterator to be copied from
//    subSlice  in    = kFALSE (default) to make copy
//                    = kTRUE to form a subslice
//
//  Return:   n/a
//
//  Contact:   N. West
//
//  Specification:-
//  =============
//
//  o Copy or sub-slice constructor.

//  Program Notes:-
//  =============

//  None.

  LEA_CTOR  //Leak Checker

  Init();
  if ( subSlice) SubSlice(from);
  else           Copy(from);

}
//.....................................................................

NavItr::NavItr(const TIter* sourceItr,  
               const Text_t* classname, 
               Int_t offset) {
//
//
//  Purpose:  Construct iterator over TCollection.
//
//  Arguments: 
//    sourceItr    in    source set TIter for iterator.
//    classname    in    Name of class associated with NavItr.
//    offset       in    Pointer offset: Object adr - TObject adr
//
//  Return:    n/a
//
//  Contact:   N. West
//
//  Specification:-
//  =============
//
//  o Create new NavSet derived from a TCollection and attach it.


//  Program Notes:-
//  =============

//  None.

  LEA_CTOR  //Leak Checker

  Init();

//    NavSet will check that the supplied TCollection really does 
//    exist and contains the correct class.

  const TCollection* source = sourceItr->GetCollection();
  fSet = new NavSet(source, classname, offset);
  Connect();

}
//.....................................................................

NavItr::NavItr(const TCollection* source,  
               const Text_t* classname, 
               Int_t offset) {
//
//
//  Purpose:  Construct iterator over TCollection.
//
//  Arguments: 
//    source       in    source set for iterator.
//    classname    in    Name of class associated with NavItr.
//    offset       in    Pointer offset: Object adr - TObject adr
//
//  Return:    n/a
//
//  Contact:   N. West
//
//  Specification:-
//  =============
//
//  o Create new NavSet derived from a TCollection and attach it.


//  Program Notes:-
//  =============

//  None.

  LEA_CTOR  //Leak Checker

// Clear fSet (Attach only assumes this data member is defined)
  fSet = 0;

  Attach(source,classname,offset);

}

//.....................................................................

NavItr::NavItr(const Text_t* classname,
               const Text_t* farclass,
               Int_t rship) {
//
//
//  Purpose:  Construct iterator over Lattice.
//
//  Arguments: 
//    classname    in    Name of class associated with NavItr.
//    farclass     in    Name of class on far side of Lattice.
//    rship        in    Relationship number or 0.
//
//  Return:   
//
//  Contact:   N. West
//
//  Specification:-
//  =============
//
//  o Ask NavPrimer for the default Lattice for this type of object
//    in specified relationship with farclass objects.
//
//  o Create new NavSet derived from one side of a Lattice and attach it.

//  Program Notes:-
//  =============

//  None.

  LEA_CTOR  //Leak Checker

  Init();

  NavPrimer* primer = NavPrimer::Instance();

  NavSet::ESide side = NavSet::kLeft;
  const Lattice* source = primer
                          ->FindLattice(classname, farclass, rship);

// If cannot find Lattice with class on left, try on right.

  if ( ! source ) {
    side = NavSet::kRight;
    source = primer->FindLattice(farclass, classname, rship);
  }

  if ( source ) {
    fSet = new NavSet(source, (NavSet::ESide) side);
    Connect();
  }
  else {
    MSG("Nav", Msg::kWarning) << "Cannot find Lattice for" 
       << classname << ":" << farclass << endl;
  }

}
//.....................................................................

NavItr::NavItr(const Lattice* source,
               const Text_t* classname,
               ESide side){
//
//
//  Purpose:  Construct iterator over Lattice.
//
//  Arguments: 
//    source       in    Source relationship set
//    classname    in    Name of class associated with NavItr.
//    side         in    Side of reltionship (either kLeft or kRight).
//
//  Return:    n/a
//
//  Contact:   N. West
//
//  Specification:-
//  =============
//
//  o Create new NavSet derived from one side of a Lattice and attach it.


//  Program Notes:-
//  =============

//  None.

  LEA_CTOR  //Leak Checker

  MSG("Nav", Msg::kVerbose) << "Creating iterator over Lattice for" 
                            << classname << endl;

  Init();

  fSet = new NavSet(source, (NavSet::ESide) side);
  Connect();

}
//.....................................................................

NavItr::~NavItr() {
//
//
//  Purpose:  Destructor.
//
//  Arguments: 
//    None.
//
//  Return:   n/a
//
//  Contact:   N. West
//
//  Specification:-
//  =============
//
//  o Destructor.

//  Program Notes:-
//  =============

//  None.

  LEA_DTOR  //Leak Checker

    Disconnect();

}
//.....................................................................

 Bool_t NavItr::NextKey() {
//
//
//  Purpose:  Increment pointer skipping unwanted objects until
//            associated NavKey changes value.
//
//  Arguments: None.
//
//  Return: kTRUE if pointer is positioned on a valid object.  
//
//  Contact:   N. West
//
//  Specification:-
//  =============
//
//  o  Increment pointer skipping unwanted objects until
//     associated NavKey changes value.

//  Program Notes:-
//  =============

//  None.

  GetZone();
  fIndex = fZoneHi+1;
  return IsValid();

}

//.....................................................................

void NavItr::NotReady(const char* mem) const {
//
//
//  Purpose:  Warning for unimplemented member functions.
//
//  Arguments: 
//    mem          in    Member function name.
//
//  Return:    
//
//  Contact:   N. West
//
//  Specification:-
//  =============
//
//  o Display error message giving name of unimplemented member
//    function.

//  Program Notes:-
//  =============

//  None.

  MSG("Nav", Msg::kError) << "Sorry, member function NavItr:::" << mem
                          << " is not yet ready" << endl;

}
//.....................................................................

void* NavItr::operator*() const {
//
//
//  Purpose:  Return object pointer at current index if valid.
//
//  Arguments: None
//
//  Return:    Object pointer, or 0 if current index invalid.
//
//  Contact:   N. West
//
//  Specification:-
//  =============
//
//  o 

//  Program Notes:-
//  =============

//  None.

  return ( IsValid() ) ? fSet->At(fIndex) : 0;

}
//.....................................................................

 Bool_t NavItr::PrevKey() {
//
//
//  Purpose:  Decrement pointer skipping unwanted objects until
//            associated NavKey changes value.
//
//  Arguments: None.
//
//  Return: kTRUE if pointer is positioned on a valid object.  
//
//  Contact:   N. West
//
//  Specification:-
//  =============
//
//  o  Decrement pointer skipping unwanted objects until
//     associated NavKey changes value.

//  Program Notes:-
//  =============

//  None.

  GetZone();
  fIndex = fZoneLo-1;
  return IsValid();

}

//.....................................................................

void* NavItr::Ptr(Bool_t warnIfNull) const {
//
//
//  Purpose:  Return pointer to object at current index.
//
//  Arguments: 
//    warnIfNull   in    = kTRUE to give warning if null.
//
//  Return:    Object pointer, or 0 if current index invalid.
//
//  Contact:   N. West
//
//  Specification:-
//  =============
//
//  o Return pointer to object at current index.  If required issue
//    warning if pointer is null.

//  Program Notes:-
//  =============

//  None.

  void* ptr = ( IsValid() ) ? fSet->At(fIndex) : 0;

  if ( ! ptr && warnIfNull )
    MSG("Nav", Msg::kError) << "There is no object at index: " 
       << fIndex << "! The code will attempt to create an object." 
       << endl
       << "At the very least this will be a memory leak!" << endl;
  return ptr;

}
//.....................................................................

void NavItr::Reset() {
//
//
//  Purpose: Set to first valid entry in the default direction. 
//
//  Arguments: None.
//
//  Return:    n/a
//
//  Contact:   N. West
//
//  Specification:-
//  =============
//
//  o Move to first valid entry.

//  Program Notes:-
//  =============

//  None.

  if ( fDefaultStep > 0 ) ResetFirst();
  else                    ResetLast();
 
}
//.....................................................................

void NavItr::ResetFirst() {
//
//
//  Purpose: Set to first valid entry and set default direction to 
//           forwards. 
//
//  Arguments: None.
//
//  Return:    n/a
//
//  Contact:   N. West
//
//  Specification:-
//  =============
//
//  o Move to last valid entry or to 0 if none.

//  Program Notes:-
//  =============

//  None.

  fIndex = fLimLo;
  fDefaultStep = +1;

}
//.....................................................................

void NavItr::ResetLast() {
//
//
//  Purpose: Set to last valid entry and set default direction to 
//           backwards. 
//
//  Arguments: None.
//
//  Return:    n/a
//
//  Contact:   N. West
//
//  Specification:-
//  =============

//  o Move to last valid entry or to 0 if none.

//  Program Notes:-
//  =============

//  None.

  fIndex = fLimHi;
  fDefaultStep = -1;

}

void NavItr::ResetSet() {
//
//
//  Purpose: Reset after change in underlying set.
//
//  Arguments: None.
//
//  Return:    n/a
//
//  Contact:   N. West
//
//  Specification:-
//  =============

//  Reset after change in underlying set.

//  Program Notes:-
//  =============

//  None.

  Init(fSet);

}
//.....................................................................

void NavItr::SetDirection(Int_t dir) {
//
//
//  Purpose:  Set default direction.
//
//  Arguments: 
//    dir          in    Direction: > 0 Forwards 
//                                  < 0 Backwards
//                                  = 0 Leave default direction.
//
//  Return:   
//
//  Contact:   N. West
//
//  Specification:-
//  =============
//
//  o Set default direction.

//  Program Notes:-
//  =============

//  None.

  if ( dir >  0 ) fDefaultStep =  1;
  if ( dir <  0 ) fDefaultStep = -1;

}

//.....................................................................

Bool_t NavItr::SetIndex( Int_t index){
//
//
//  Purpose:  Set index if valid.
//
//  Arguments: 
//    index        in    Required position.
//
//  Return:    kTRUE if index is valid.
//
//  Contact:   N. West
//
//  Specification:-
//  =============
//
//  o If new index valid update iterator, otherwise leave where it is
//    even if this is also invalid.


//  Program Notes:-
//  =============

//  None.

  if ( IsValid(index) ) {
    fIndex = index;
    return kTRUE;
  }

  return kFALSE;

}
//.....................................................................

UInt_t NavItr::Size() const {
//
//
//  Purpose:  Return current size of set.
//
//  Arguments: None.
//
//  Return:  Current size of set  
//
//  Contact:   N. West
//
//  Specification:-
//  =============
//
//  o Return current size of set.

//  Program Notes:-
//  =============

//  None.

   return ( fSet ) ? fSet->Size() : 0;

}
//.....................................................................

UInt_t NavItr::SizeSelect() const {
//
//
//  Purpose:  Return current size of selected set.
//
//  Arguments: None.
//
//  Return:  Current size of selected set  
//
//  Contact:   N. West
//
//  Specification:-
//  =============
//
//  o Return current size of selected set.

//  Program Notes:-
//  =============

//  None.

   return ( fSet ) ? fSet->SizeSelect() : 0;

}
//.....................................................................

void* NavItr::Step(Int_t dir/*=0*/) {
//
//
//  Purpose:  Step iterator in required direction and return object pointed
//            before the step.
//
//  Arguments: 
//    dir          in    Direction: > 0 Forwards 
//                                  < 0 Backwards
//                                  = 0 Default direction.
//
//  Return:   
//
//  Contact:   N. West
//
//  Specification:-
//  =============
//
//  o Step iterator in required direction and return object pointed
//    before the step.

//  Program Notes:-
//  =============

//  Returning the object in the old position allows this access
//  method to be handled consistantly with the Ptr() and
//  Obj() methods.  In all cases Reset() can move to the first valid.


  void* old = Ptr();

  if ( dir >  0 ) Increment();
  if ( dir <  0 ) Decrement();
  if ( dir == 0 && IsValid() ) fIndex += fDefaultStep;

  return old;

}

//.....................................................................

void NavItr::SubSlice(const NavItr& parent) {
//
//
//  Purpose: Set up iterator over sub-slice of supplied parent iterator.
//
//  Arguments: 
//    parent        in    The parent iterator defining the sub-slice.
//
//  Return:   n/a
//
//  Contact:   N. West
//
//  Specification:-
//  =============
//
//  o Set up iterator to be one rank higher than the supplied parent 
//    and set its range to be the current parent zone.

//  Program Notes:-
//  =============

//  By setting the this iterator's range to be the current zone of its 
//  parent  means that this iterator is limits to the range in which 
//  the parent has a constant NavKey value.

  Disconnect();
  fSet         = parent.fSet;
  Connect();
  fDefaultStep = parent.fDefaultStep;
  parent.GetZone(fLimLo,fLimHi);
  fIndex       = (fDefaultStep > 0 ) ? fLimLo : fLimHi;
  fRank        = parent.fRank+1;
  fZoneLo      = 0;
  fZoneHi      = -1;
  
}


/*    Template for New Member Function

//.....................................................................

NavItr:: {
//
//
//  Purpose:  
//
//  Arguments: 
//    xxxxx        in    xxxxxxxxxxxxxxxxxx
//
//  Return:   
//
//  Contact:   N. West
//
//  Specification:-
//  =============
//
//  o 

//  Program Notes:-
//  =============

//  None.


}

*/

---