Data class CChain represents a chain in the coordinate hierarchy.
CChain contains all information, which is relevant to particular chain, and reference to model that contains the chain. It also contains table of pointers on all residues (represented as classes of type CResidue) that belong to the chain.Function | Purpose |
CChain::CChain | Default constructor.
|
CChain::~CChain | The class' destructor.
|
CChain::GetModelNum | Obtaining number of model containing the chain.
|
CChain::GetModel | Obtaining pointer on model containing the chain.
|
CChain::isInSelection | Checking if chain is selected.
|
CChain::GetChainID | Obtaining identifier of the chain.
|
CChain::SetChainID | Setting the chain identifier.
|
CChain::GetChainID | Obtaining a full chain's coordinate ID.
|
CChain::CheckID | Checking the chain's ID by chainID.
|
CChain::CheckIDS | Checking the chain's ID by coordinate ID.
|
CChain::GetNumberOfResidues | Obtaining the number of residues in chain.
|
CChain::GetResidue | Obtaining a residue pointer by residue sequence number and
insertion code.
|
CChain::GetResidue | Obtaining a residue pointer by residue number.
|
CChain::GetResidueNo | Obtaining a residue position in the chain by residue sequence
number and insertion code.
|
CChain::GetResidueTable | Obtaining the chain's table of residues.
|
CChain::DeleteResidue | Deleting a residue by residue sequence number and
insertion code.
|
CChain::DeleteResidue | Deleting a residue by residue number.
|
CChain::GetNumberOfAtoms | Calculating the total number of atoms in the chain.
|
CChain::GetNumberOfAtoms | Obtaining the number of atoms in residue by residue sequence
number and insertion code.
|
CChain::GetNumberOfAtoms | Obtaining the number of atoms in residue by residue number.
|
CChain::GetAtom | Obtaining an atom pointer by residue sequence number,
insertion code, atom name, element name,
and alternative location indicator.
|
CChain::GetAtom | Obtaining an atom pointer by residue sequence number,
residue insertion code and atom number.
|
CChain::GetAtom | Obtaining an atom pointer by residue number, atom name,
element name and alternative location indicator.
|
CChain::GetAtom | Obtaining an atom pointer by residue number and atom number.
|
CChain::GetAtomTable | Obtaining the residue's table of atoms by residue sequence
number and insertion code.
|
CChain::GetAtomTable | Obtaining the residue's table of atoms by residue number.
|
CChain::DeleteAtom | Deleting an atom specified by residue sequence number,
insertion code, atom name, element name,
and alternative location indicator.
|
CChain::DeleteAtom | Deleting an atom specified by residue sequence number,
residue insertion code and atom number.
|
CChain::DeleteAtom | Deleting an atom specified by residue number, atom name,
element name and alternative location indicator.
|
CChain::DeleteAtom | Deleting an atom specified by residue number and atom number.
|
CChain::DeleteAllAtoms | Deleting all atoms in the residue specified by sequence
number and insertion code.
|
CChain::DeleteAllAtoms | Deleting all atoms in the residue specified by its
position in the chain.
|
CChain::DeleteAllAtoms | Deleting all atoms in the chain.
|
CChain::AddAtom | Adding an atom to the residue specified by sequence
number and insertion code.
|
CChain::AddAtom | Adding an atom to the residue specified by its
position in the chain.
|
CChain::SetEntryID | Setting the entry ID.
|
CChain::GetEntryID | Obtaining the entry ID.
|
CChain::GetAtomStatistics | Calculating the averaged properties of all atoms in the chain.
|
CChain::GetNofModResidues | Obtaining the number of modified residues annotated in the chain.
|
CChain::GetModResidues | Obtaining the information on modified residue.
|
CChain::ApplyTransform | Applying a transformation matrix to coordinates of
all atoms in the chain.
|
CChain::isSolventChain | Checking if the chain consists only of solvent molecules.
|
CChain::PutUDData | Storing an integer User-Defined Data (UDD) in the chain.
|
CChain::PutUDData | Storing a real-type User-Defined Data (UDD) in the chain.
|
CChain::PutUDData | Storing a string-type User-Defined Data (UDD) in the chain.
|
CChain::GetUDData | Retrieving an integer User-Defined Data (UDD) from the chain.
|
CChain::GetUDData | Retrieving a real-type User-Defined Data (UDD) from the chain.
|
CChain::GetUDData | Retrieving a string-type User-Defined Data (UDD) from the chain,
dynamic buffer.
|
CChain::GetUDData | Retrieving a string-type User-Defined Data (UDD) from the chain,
fixed-size buffer.
|
CChain::Copy | Copying the chain contents.
|
CChain::CChain ( |
) |
Default constructor creates an empty CChain object.
CChain::~CChain ( |
) |
The destructor is called implicitely whenever the class instance is deleted. It deletes all atoms and residues containing in the chain and the chain itself. If the chain is properly associated with the coordinate hierarchy, the destructor removes all references on the chain, its residues and atoms, from the hierarchy.
NOTE :
Deleting a chain is an editing operation. If it is done by
application explicitely, like in the following example:
PCMMDBManager MMDB;
PCChain chain;
chain = MMDB->GetChain ( "/1/A" );
delete chain; // this is where the destructor is called!
then the application must call CMMDBManager::FinishStructEdit function before using
any results of such deletion(s).
int CChain::GetModelNum ( |
) |
The function returns number of model that contains the chain. Models are numbered 1.. on. If chain is not properly associated with coordinate hierarchy, the function returns 0.
PCModel CChain::GetModel ( |
) |
The function returns pointer on model that contains the chain. If chain is not properly associated with coordinate hierarchy, the function returns NULL.
Boolean CChain::isInSelection ( |
int selHnd ) |
The function returns True if chain is selected for the specified selection handle, and False otherwise.
NOTE : The function returns False if chain is not properly associated with coordinate hierarchy.
pstr CChain::GetChainID ( |
) |
The function returns identifier of the chain. If the chain does not have an ID, the function returns empty string "".
void CChain::SetChainID ( |
ChainID chainID ) |
The function sets a new chain ID, i.e. renames the chain. Other parts of the coordinate file, such as PDB records DBREF, SEQRES and others, are updated automatically.
pstr CChain::GetChainID ( |
pstr CID ) |
The function calculates a coordinate ID of the chain and returns it in the supplied string. The same string is returned as the function value.
If chain is not properly associated with coordinate hierarchy, the coordinate ID will contain dash "-" for model number.NOTE : The function does not make any checks on the sufficiency of string buffer CID to accept the information.
int CChain::CheckID ( |
ChainID chID ) |
The function returns 1 if the chain is identified by given chain ID, and 0 otherwise. If chID is set to NULL or wildcard "*" then any chain is identified.
NOTE 1: The model serial number is not taken into account by this function.
NOTE 2: Comparison is case-sensitive. Consider that " " is not an empty string.
int CChain::CheckIDS ( |
pstr CID ) |
The function returns 1 if the chain is identified by chain ID found in the provided coordinate ID, and 0 otherwise. If CID contains a wildcard for chain ID, any chain is identified.
NOTE 1: The model serial number, as well as any residue and atom-related information in the coordinate ID are not taken into account by this function.
NOTE 2: Comparison is case-sensitive. Any spaces in the coordinate ID are ignored.
int CChain::GetNumberOfResidues ( |
) |
The function returns the number of residues currently contained in the chain.
PCResidue CChain::GetResidue ( |
int seqNum, |
The function returns pointer on the residue identified by residue sequence number and insertion code. If any of these characteristics is invalid or if such a residue does not exist in chain, the function returns NULL.
NOTE : Comparison is case-sensitive. Consider that " " is not an empty string.
PCResidue CChain::GetResidue ( |
int resNo ) |
The function returns pointer on the resNoth residue in the chain's table of residues. If resNo is invalid or if such a residue does not exist in the chain, the function returns NULL.
int CChain::GetResidueNo ( |
int seqNum, |
The function returns the residue position (residue number) in the chain. The residues are numbered as 0..NumberOfResidues-1, where NumberOfResidues is returned by CChain::GetNumberOfResidues.
The residue is identified by residue sequence number and insertion code. If any of these characteristics is invalid or if such a residue does not exist in chain, the function returns -1.NOTE : Comparison is case-sensitive. Consider that " " is not an empty string.
void CChain::GetResidueTable ( |
PPCResidue & resTable, |
The function returns table of pointers on all residues currently contained in the chain. NumberOfResidues returns the number of residues. The residues are indexed as 0..NumberOfResidues-1 in the table.
If there is no residues in the chain, the function returns NULL for resTable and 0 for NumberOfResidues.NOTE 1: Certain editing operations might dispose residues. This results in empty cells in the table of residues. Therefore, it is a good practice for application to check that resTable[i] is not NULL before using it.
NOTE 2: Under no circumstances should the application deallocate, reallocate or otherwise modify the table of residues.
int CChain::DeleteResidue ( |
int seqNum, |
The function deletes residue identified by residue sequence number and insertion code, and all atoms contained in it. If the requested residue does not exist in the chain, the function does nothing.
The function returns the number of deleted residues, that is 1 or 0.
NOTE 1: Comparison is case-sensitive. Consider that " " is not an empty string.
NOTE 2: Deleted residues and atoms are completely disposed and are not retrievable.
NOTE 3: The application must call CMMDBManager::FinishStructEdit function after a set of editing operations is complete, before using the results of the editing.
int CChain::DeleteResidue ( |
int resNo ) |
The function deletes the resNoth residue in the chain's table of residues, and all atoms contained in it. If resNo is invalid or if such a residue does not exist in the chain, the function does nothing.
The function returns the number of deleted residues, that is 1 or 0.
NOTE 1: Deleted residues and atoms are completely disposed and are not retrievable.
NOTE 2: The application must call CMMDBManager::FinishStructEdit function after a set of editing operations is complete, before using the results of the editing.
int CChain::GetNumberOfAtoms ( |
Boolean countTers ) |
The function performs an actual calculation of all atoms in the chain, not just returning the sum of lengths of atom tables. If some cells in atom tables are empty (set to NULL), they are not counted.
int CChain::GetNumberOfAtoms ( |
int seqNum, |
The function returns the number of atoms currently contained in the chain's residue identified by residue sequence number and insertion code. If the residue identification is invalid or if such a residue is not found in the chain, the function returns 0.
NOTE : The function actually returns the length of atom table of the residue. In the course of editing operations, the table may contain empty cells, which will be counted as atoms. Besides, a residue may contain a termination record ("TER"), which is kept in MMDB as a special case of CAtom object; the function will count such an object as atom.
int CChain::GetNumberOfAtoms ( |
int resNo ) |
The function returns the number of atoms currently contained in the chain's residue identified by residue number (that is, the residue position in the chain's table of residues). If the residue number is invalid or if such a residue is not found in the chain, the function returns 0.
NOTE : The function actually returns the length of atom table of the residue. In the course of editing operations, the table may contain empty cells, which will be counted as atoms. Besides, a residue may contain a termination record ("TER"), which is kept in MMDB as a special case of CAtom object; the function will count such an object as atom.
PCAtom CChain::GetAtom ( |
int seqNum, |
The function returns pointer on the atom identified by residue sequence number and insertion code, atom name, chemical element name and alternative location indicator. If any of these characteristics is invalid or if such an atom does not exist in the chain, the function returns NULL.
The atom is considered as identified, if all non-NULL, non-wildcard parameters do match. If the specified parameters allow for identification of more than one atom in the chain, the first one from the begining of the chain's table of residues and the residue's table of atoms is taken.NOTE : Comparison is case-sensitive. Consider that " " is not an empty string.
PCAtom CChain::GetAtom ( |
int seqNum, |
The function returns pointer on the atomNoth atom in the atom table of the chain's residue identified by residue sequence number and insertion code. If atom identification is invalid or if such an atom does not exist in the chain, the function returns NULL.
PCAtom CChain::GetAtom ( |
int resNo, |
The function returns pointer on the atom identified by residue number (that is, the residue's position in the chain's table of residues), atom name, chemical element name and alternative location indicator. If any of these characteristics is invalid or if such an atom does not exist in the chain, the function returns NULL.
The atom is considered as identified, if all non-NULL, non-wildcard parameters do match. If the specified parameters allow for identification of more than one atom in the chain, the first one from the begining of the chain's table of residues and the residue's table of atoms is taken.NOTE : Comparison is case-sensitive. Consider that " " is not an empty string.
PCAtom CChain::GetAtom ( |
int resNo, |
The function returns pointer on the atomNoth atom in the atom table of the resNoth residue in the chain's table of residues. If atom identification is invalid or if such an atom does not exist in the chain, the function returns NULL.
void CChain::GetAtomTable ( |
int seqNum, |
The function returns table of pointers on all atoms currently contained in the chain's residue identified by residue sequence number and insertion code. NumberOfAtoms returns the number of atoms. The atoms are indexed as 0..NumberOfAtoms-1 in the table.
If there is no atoms in the residue or if the specified residue is not found in the chain, the function returns NULL for atomTable and 0 for NumberOfAtoms.NOTE 1: Certain editing operations might dispose atoms. This results in empty cells in the table of atoms. Therefore, it is a good practice for application to check that atomTable[i] is not NULL before using it.
NOTE 2: Under no circumstances should the application deallocate, reallocate or otherwise modify the table of atoms.
void CChain::GetAtomTable ( |
int resNo, |
The function returns table of pointers on all atoms currently contained in the resNoth residue in the chain's table of residues. NumberOfAtoms returns the number of atoms. The atoms are indexed as 0..NumberOfAtoms-1 in the table.
If there is no atoms in the residue or if the specified residue is not found in the chain, the function returns NULL for atomTable and 0 for NumberOfAtoms.NOTE 1: Certain editing operations might dispose atoms. This results in empty cells in the table of atoms. Therefore, it is a good practice for application to check that atomTable[i] is not NULL before using it.
NOTE 2: Under no circumstances should the application deallocate, reallocate or otherwise modify the table of atoms.
PCAtom CChain::DeleteAtom ( |
int seqNum, |
The function deletes the specified atom from the
coordinate hierarchy: the atom
is checked out and disposed.
The function returns the number of actually deleted atoms, which
may be more than one if NULL or wildcard
parameters have been supplied (cf. above). A zero return
indicates that either the requested residue or atom in the residue
were not found.
NOTE 1: Comparison is case-sensitive. Consider that " " is not an empty string.
NOTE 2: If deletion of an atom leaves residue empty, the latter is not deleted. Empty residue gives no records in PDB file.
PCAtom CChain::DeleteAtom ( |
int seqNum, |
The function deletes the specified atom from the
coordinate hierarchy: the atom
is checked out and disposed.
The function returns the number of actually deleted atoms, which
may be more than one if NULL or wildcard
parameters have been supplied (cf. above). A zero return
indicates that either the requested residue or atom in the residue
were not found.
NOTE : If deletion of an atom leaves residue empty, the latter is not deleted. Empty residue gives no records in PDB file.
PCAtom CChain::DeleteAtom ( |
int resNo, |
The function deletes the specified atom from the
coordinate hierarchy: the atom
is checked out and disposed.
The function returns the number of actually deleted atoms, which
may be more than one if NULL or wildcard
parameters have been supplied (cf. above). A zero return
indicates that either the requested residue or atom in the residue
were not found.
NOTE 1: Comparison is case-sensitive. Consider that " " is not an empty string.
NOTE 2: If deletion of an atom leaves residue empty, the latter is not deleted. Empty residue gives no records in PDB file.
PCAtom CChain::DeleteAtom ( |
int resNo, |
The function deletes the specified atom from the
coordinate hierarchy: the atom
is checked out and disposed.
The function returns the number of actually deleted atoms, which
may be 0 or 1. A zero return indicates that either the requested
residue or atom in the residue were not found.
NOTE : If deletion of an atom leaves residue empty, the latter is not deleted. Empty residue gives no records in PDB file.
int CChain::DeleteAllAtoms ( |
int seqNo, |
The function deletes all atoms in the specified residue of the chain. The function returns the number of actually deleted atoms.
NOTE : Note that the residue is not deleted, however stays empty. Empty residue gives no records in a PDB file.
int CChain::DeleteAllAtoms ( |
int resNo ) |
The function is completely identical to CChain::DeleteAllAtoms except that the residue is specified by its position in the chain.
int CChain::DeleteAllAtoms ( |
) |
The function deletes all atoms in the chain. The function returns the number of actually deleted atoms.
NOTE : Note that the chain is not deleted, however stays empty. Empty chain gives no coordinate records in a PDB file.
int CChain::AddAtom ( |
int seqNo, |
The function adds atom atom to the specified residue, placing it on the top of the residue's table of atoms. The atom and the residue may be or may be not associated with a coordinate hierarchy.
If atom atom is not associated with a coordinate hierarchy, it is taken over by the residue, which means that its pointer is saved in the residue's table of atoms. If atom atom already belongs to a coordinate hierarchy (even though that of the residue), the residue adopts its (automatically created) copy, thus the atom is not removed from its own coordinate hierarchy. If residue is associated with a coordinate hierarchy, the newly added atom is automatically associated with it. Otherwise, the atom is checked in the hierarchy once the residue is checked in (see example below).Upon success, the function returns the number of atoms in the residue, which should be a positive integer greater than 0. A negative or zero return means that the atom is already in the residue, found at position equal to minus return. Zero return may also mean that the residue is not found in the chain.
NOTE 1: Note the difference between adding atoms associated and not associated with a coordinate hierarchy as described above.
NOTE 2: Calling CMMDBManager::FinishStructEdit function is not necessary after adding atoms. However, it is advisable to call CMMDBManager::PDBCleanup with input flags PDBCLEAN_SERIAL and PDBCLEAN_INDEX after adding all atoms (don't call CMMDBManager::PDBCleanup after every addition of an atom). PDBCLEAN_SERIAL will put atoms' serial numbers in due order, and "cleaning" on PDBCLEAN_INDEX is needed for the internal consistency of data.
int CChain::AddAtom ( |
int resNo, |
The function is completely identical to CChain::AddAtom except that the residue is specified by its position in the chain.
void CChain::SetEntryID ( |
IDCode idCode ) |
The function sets the new entry ID, that is normally the 4-letter PDB entry code. The function will accomplish successfully only if the chain is properly associated with coordinate hierarchy.
pstr CChain::GetEntryID ( |
) |
The function returns the entry ID, that is normally the 4-letter PDB entry code. The ID is returned as a null-teminated string. If chain is not properly associated with coordinate hierarchy, the function returns empty string "".
void CChain::GetAtomStatistics ( |
RSAtomStat AS ) |
The function performs an actual calculation of averaged atom properties, none of them are stored as variables. It is therefore advised to avoid unnecessary calls to this function.
int CChain::GetNofModResidues ( |
) |
The function returns the number of modified residues annotated in the chain, i.e. the number of PDB MODRES records showing the chain's ID.
PCModRes CChain::GetModResidues ( |
int modResNo ) |
The function returns pointer to the class data containing all contents of the corresponding PDB MODRES record.
The CModRes class has the following
public fields that may be read by application:
Type | Name | Description |
ResName | resName | The residue name used |
ResName | stdRes | Standard residue name |
int | seqNum | The residue sequence number |
InsCode | insCode | The residue insertion code |
pstr | comment | Description of the residue modification |
NOTE : The class returned by the function, can not be disposed. An attempt to do so by application will eventually crash the latter.
void CChain::ApplyTransform ( |
mat44 & TMatrix ) |
The function applies the rotational-translational transformation given by matrix TMatrix, to coordinates of all atoms in the chain.
The transformation matrix TMatrix contains rotational part in columns 0,1,2, rows 0,1,2 (stands for x,y,z) and translational part in column 3, rows 0,1,2.Boolean CChain::isSolventChain ( |
) |
The function returns True if the chain consists only of solvent residues.
int CChain::PutUDData ( |
int UDDhandle, |
The function stores an integer contained in iudd in the chain, associating it with UDD handle UDDhandle. The handle must be previously obtained from CMMDBManager::RegisterUDInteger in the course of UDD registration or from CMMDBManager::GetUDDHandle after the registration has been done.
The function may return:
Return | Description |
UDDATA_Ok | the data has been successfully stored |
UDDATA_WrongHandle | the UDD handle UDDhandle does not correspond to any registered UDD for the chain, the data was not stored |
UDDATA_WrongUDRType | the UDD handle UDDhandle was not registered for use in chains, the data was not stored |
int CChain::PutUDData ( |
int UDDhandle, |
The function stores the real number contained in rudd in the chain, associating it with UDD handle UDDhandle. The handle must be previously obtained from CMMDBManager::RegisterUDReal in the course of UDD registration or from CMMDBManager::GetUDDHandle after the registration has been done.
The function is conceptually identical to CChain::PutUDData, see returns there.int CChain::PutUDData ( |
int UDDhandle, |
The function stores the string pointed by sudd in the chain, associating it with UDD handle UDDhandle. The handle must be previously obtained from CMMDBManager::RegisterUDString in the course of UDD registration or from CMMDBManager::GetUDDHandle after the registration has been done.
The function is conceptually identical to CChain::PutUDData, see returns there.int CChain::GetUDData ( |
int UDDhandle, |
The function retrieves an integer previously stored in the chain by function CChain::PutUDData. The UDD handle UDDhandle identifies the data. The handle must be previously obtained from CMMDBManager::RegisterUDInteger in the course of UDD registration or from CMMDBManager::GetUDDHandle after the registration has been done.
The data is returned in iudd.The function may return:
Return | Description |
UDDATA_Ok | the data has been successfully retrieved. |
UDDATA_NoData | no data found for the handle UDDhandle in the chain. iudd returns zero. |
UDDATA_WrongHandle | the UDD handle UDDhandle does not correspond to any registered UDD for the chain. iudd returns zero. |
UDDATA_WrongUDRType | the UDD handle UDDhandle was not registered for use in chains. iudd does not change. |
int CChain::GetUDData ( |
int UDDhandle, |
The function retrieves a real number previously stored in the chain by function CChain::PutUDData. The UDD handle UDDhandle identifies the data. The handle must be previously obtained from CMMDBManager::RegisterUDReal in the course of UDD registration or from CMMDBManager::GetUDDHandle after the registration has been done.
The data is returned in rudd.The function may return:
Return | Description |
UDDATA_Ok | the data has been successfully retrieved. |
UDDATA_NoData | no data found for the handle UDDhandle in the chain. rudd returns zero. |
UDDATA_WrongHandle | the UDD handle UDDhandle does not correspond to any registered UDD for the chain. rudd returns zero. |
UDDATA_WrongUDRType | the UDD handle UDDhandle was not registered for use in chains. rudd does not change. |
int CChain::GetUDData ( |
int UDDhandle, |
The function retrieves a string previously stored in the chain by function CChain::PutUDData. The UDD handle UDDhandle identifies the data. The handle must be previously obtained from CMMDBManager::RegisterUDString in the course of UDD registration or from CMMDBManager::GetUDDHandle after the registration has been done.
The string is returned in buffer pointed by sudd. If sudd was not set to NULL, it will be deallocated first. The string is allocated within the function, and it is responsibility of the application to eventually deallocate it.The function may return:
Return | Description |
UDDATA_Ok | the data has been successfully retrieved. |
UDDATA_NoData | no data found for the handle UDDhandle in the chain. sudd returns NULL. |
UDDATA_WrongHandle | the UDD handle UDDhandle does not correspond to any registered UDD for the chain. sudd returns NULL. |
UDDATA_WrongUDRType | the UDD handle UDDhandle was not registered for use in chains. sudd does not change. |
int CChain::GetUDData ( |
int UDDhandle, |
The function retrieves a string previously stored in the chain by function CChain::PutUDData. The UDD handle UDDhandle identifies the data. The handle must be previously obtained from CMMDBManager::RegisterUDString in the course of UDD registration or from CMMDBManager::GetUDDHandle after the registration has been done.
The string is returned in buffer pointed by sudd, with no more than maxlen symbols, including the terminating NULL returned. The string sudd is not allocated or deallocated within the function.The function may return:
Return | Description |
UDDATA_Ok | the data has been successfully retrieved. |
UDDATA_NoData | no data found for the handle UDDhandle in the chain. sudd returns empty string "". |
UDDATA_WrongHandle | the UDD handle UDDhandle does not correspond to any registered UDD for the chain. sudd returns empty string "". |
UDDATA_WrongUDRType | the UDD handle UDDhandle was not registered for use in chains. sudd does not change. |
void CChain::Copy ( |
PCChain chain ) |
The function copies the content of chain chain into internal class' fields. The function does copy all the chain's table of residues and it does redefine the residues' chain for the destination one. As a result, a new chain is created that is identical to the source one, but physically they do not overlap.
NOTE :
An application should never copy contents of classes by direct
assignment; in most cases this will result in crash because
of inducing a mess in cross-references. See the following example:
PCChain chain1,chain2;
chain1 = new CChain();
chain2 = new CResidue();
// doing something with chain2
*chain1 = *chain2; // never do this!
// the right way:
chain1->Copy ( chain2 );
Function Copy is supplied for all classes
in the Library.