By Hand (vi)

Starlib

Parallel Copying Functions.

Sometimes it is useful to make a copy of a starfile tree in such a way that, given a node in one of the trees, it is possible to find the same corresponding node in the other tree. (At least, we found it useful to do this at BMRB, so we are including the functions that did this in the public distribution of the library, in the hopes that someone else might find it useful also.)

If you do not need to use this parallel link feature, then it is highly reccomended that you use the ordinary copy constructor to create a copy of a starfile tree.

Specificly, the place where we found this a useful thing to do was in our "s2nmr" program. This program converted Star files from an intermediate format used by the web pages into the final NMR-STAR format. This program required that we make a copy of the starfile tree, search for some tags in the original tree, and then perform certain operations, not on those tags themselves, but on their counterparts in the new copy of the tree.

This ability is admitedly limited, though. You can only make one copy of a tree at a time using these functions, due to the limited way this feature is implemented behind the scenes. If you want to copy tree A into tree B, and then copy tree A into tree C, using these parallel links, then you will have to delete tree A or tree B first. A starfile tree cannot be linked to more than one other 'parallel' partner starfile tree at a time. This rule is enforced in the parallel copy function. If you attempt to use the parallel copy function to create a parallel copy of a tree that already has a parallel peer, the function will fail and return NULL.

Again, it should be repeated that: If you do not need to use this parallel link feature, then it is highly reccomended that you use the ordinary copy constructor to create a copy of a starfile tree.

When two starfile trees are linked in parallel like this, you can simply delete one of them to break the link. The destructors will unlink it from its parallel peer, and the parallel peer can then be used to make another parallel copy.

Note that once the copy is made, the two trees are indeed "peers" in that they retain no knowlede of which tree was the original tree and which was the copy. Either one can deleted when finished, and the other one will automatically 'lose' all knowlege of its parallel peer.

Methods list:

These methods (functions) are all part of the main base type ASTnode. Thus they can be used at any level of the star tree. (For example, you could call a DataLoopNode's parallel copy constructor method to copy just that DataLoopNode rather than an entire Star File tree. Normally, when an entire star file needs to be parallel copied, you would call the StarFileNode's parallel copy constructor method.
- previous topic - - next topic -