Construction & Remodeling

Constructing a new Lattice:

For legibility, _left_lattice_type_, _right_lattice_type_, and _linkdata_type_ are denoted by L, R, and LD.

If F1 and F2 exist:

FATable<L> F1; or FAPtrTable<L> F1;
FATable<R> F2; or FAPtrTable<R> F2;

then:

Lattice<L,R,LD>* pLattice = new Lattice<L,R,LD>(F1,F2,{LatticeTopology});

Unfortunately, the compilers don't allow default template parameters, so if you want the dafault (empty) link data, you must specify LD to be DefaultLinkData.
{LatticeTopology} is 0 or more items from the following enumeration (declared in Lattice.h):

enum LatticeTopology
{LNodeMulti, RNodeMulti, LLinkMulti, RLinkMulti};

The presence of an item enables multiple connections to one particular part of the Lattice. For example, LLinkMulti allows a link to have several nodes on its left side. Similarly, LNodeMulti allows a left node to be connected to several links. If it's omitted, only single connections are allowed to that part. If they are all omitted, the Lattice can only have simple one-to-one L/R connections.

No links are made by the constructor.

If F1 and F2 don't exist:

Lattice<L,R,LD>* pLattice = new Lattice<L,R,LD>({LatticeTopology});

This constructor (which includes the default constructor) constructs an empty Lattice (no nodes or links) that has the desired topology. Nodes will automatically be added when the user makes connections between the data. This allows the user to recreate a Lattice from information saved in a file, even if the FATables no longer exist.

A warning about type safety: When making connections or accessing data, the user can specify data with identifiers or iterators. In general, iterators are more type safe, because identifiers are almost always ints, and Lattice cannot distinguish LeftIDs from RightIDs. Unless the two FATables contain the same kind of data, ILeft and IRight are distinct types, and Lattice can avoid some simple errors.

Making and modifying connections:
All versions of connect return a pointer to the link. The pointer is zero if the connection fails (e.g., if the topology constraint would be violated). All versions accept either FATable iterators or identifiers as arguments.

typedefs assumed below (you can use them in your code): typedef FATableItr<L> ILeft; typedef FATableItr<R> IRight; typedef Lattice<L,R,LD> Lattice; typedef Lattice::LinkData LinkData; // _linkdata_type_ typedef Lattice::LeftID LeftID; typedef Lattice::RightID RightID; typedef Lattice::VectorLeftID VectorLeftID; // vector<LeftID> typedef Lattice::VectorRightID VectorRightID; // vector<RightID> typedef Lattice::LeftItr LeftItr; // VectorLeftID ::const_iterator typedef Lattice::RightItr RightItr; // VectorRightID::const_iterator typedef Lattice::Links Links; // vector<Link*> typedef Lattice::LinkItr LinkItr; // Links::const_iterator

• Connect left and right nodes through a new link:
  The user defines his LinkData to contain whatever information the s/he wants to associate with the link (e.g., hit residuals on a track).

Call:

Link* pLink = pLattice->connect(ILeft,  IRight,  LinkData&); or
Link* pLink = pLattice->connect(LeftID, RightID, LinkData&);

This creates a new link connecting the specified nodes and containing a copy of the link data. The user's copy of LinkData is not used by the Lattice, and can be deleted or overwritten.

LinkData can be omitted, in which case the default constructor will be used. Your LinkData must have a default constructor.

The Lattice will always connect two identifiers. It does not know about FATables, so it cannot perform any data integrity checks. It is the user's responsibility to make sure that identifiers are not bogus.

• Add nodes to an existing link:
  You can add left and right nodes at the same time, or left or right separately. It is the user's responsibility to update LinkData. The user has write access to the LinkData stored inside the Lattice.

Add left and right nodes to the link:

Link* pLink = connect(LeftID, Link&, RightID);or
Link* pLink = connect(ILeft,  Link&, IRight);

Add a left node to the link:

Link* pLink = connect(LeftID, Link&); or
Link* pLink = connect(ILeft,  Link&);

Add a right node to the link:

Link* pLink = connect(        Link&, RightID); or
Link* pLink = connect(        Link&, IRight);

• Connect nodes using a new or existing link:
  Create a new link or use an existing one, depending on whether the second argument, a Link*, is zero or not. If a new link is created, the pointer passed in is not modified; the return value must be used. This syntax is designed to simplify link building in for loops.

Link* pLink = connect(LeftID, Link*, RightID); or
Link* pLink = connect(ILeft,  Link*, IRight);

• Remove nodes from an existing link:
  It is the user's responsibility to update LinkData.
  Not yet implemented.

DABoolean success = disconnect(LeftID, Link&, RightID);

success is false if the disconnect failed (one or both nodes weren't connected to the link).

• Remove a link:
  Remove the specified link, deleting its data.
  Not yet implemented.

void disconnect(Link&);

$Id: LatticeConstruction.html,v 1.1 1999/07/18 23:00:34 jjt Exp $