CCP4 Coordinate Library Project

Object interface: Data class CAtom.

Data class CAtom represents an atom in the coordinate hierarchy. As a special case, it may also represent a chain terminator - the equivalent of PDB TER card.

CAtom contains all information, which is relevant to particular atom, and reference to residue that contains the atom. Each instance of the class may be represented by several PDB records - ATOM, HETATM, SIGATM, ANISOU, SIGUIJ or TER.

Public Data Fields


Function Purpose
CAtom::CAtom Default constructor.
CAtom::CAtom Add-to-residue constructor.
CAtom::~CAtom The class' destructor.
CAtom::GetModelNum Obtaining number of model containing the atom.
CAtom::GetChainID Obtaining identifier of chain containing the atom.
CAtom::GetResName Obtaining name of residue containing the atom.
CAtom::GetSeqNum Obtaining sequence number of residue containing the atom.
CAtom::GetInsCode Obtaining insertion code of residue containing the atom.
CAtom::GetResidue Obtaining pointer on residue containing the atom.
CAtom::GetChain Obtaining pointer on chain containing the atom.
CAtom::GetModel Obtaining pointer on model containing the atom.
CAtom::isInSelection Checking if atom is selected.
CAtom::SetAtomName Setting the atom name.
CAtom::SetElementName Setting the chamical element name.
CAtom::MakeTer Converting atom into chain terminator.
CAtom::SetCoordinates Setting coordinates, occupancy and temperature factor for the atom.
CAtom::GetAtomID Obtaining a full atom's coordinate ID.
CAtom::GetAtomIDfmt Obtaining a full, formatted atom's coordinate ID.
CAtom::CheckID Checking the atom's ID by atom name, chemical element name and alternative location indicator.
CAtom::CheckIDS Checking the atom's ID by coordinate ID.
CAtom::Transform Transformation of atom coordinates with 3x3-matrix and 3-vector.
CAtom::Transform Transformation of atom coordinates with 4x4-matrix.
CAtom::isMetal Checking if the atom is identified as a metal.
CAtom::PutUDData Storing an integer User-Defined Data (UDD) in the atom.
CAtom::PutUDData Storing a real-type User-Defined Data (UDD) in the atom.
CAtom::PutUDData Storing a string-type User-Defined Data (UDD) in the atom.
CAtom::GetUDData Retrieving an integer User-Defined Data (UDD) from the atom.
CAtom::GetUDData Retrieving a real-type User-Defined Data (UDD) from the atom.
CAtom::GetUDData Retrieving a string-type User-Defined Data (UDD) from the atom, dynamic buffer.
CAtom::GetUDData Retrieving a string-type User-Defined Data (UDD) from the atom, fixed-size buffer.
CAtom::AddBond Adding an atom to the list of binded atoms.
CAtom::GetNBonds Getting the total number of bonds set up for the atom.
CAtom::FreeBonds Removing all bonds set up for the atom.
CAtom::GetBonds Getting the list of indices of bonded atoms.
CAtom::GetBonds Getting the dynamically-allocated list of bonded atoms.
CAtom::GetBonds Getting the dynamically-allocated list of bonded atoms.
CAtom::Copy Copying the atom contents.


PUBLIC DATA FIELDS

It is a good practice for any application not to modify the public fields directly if there are class' functions for doing that. Even better, avoid also direct reading them if the class provides functions for that, as the fields may be made protected in the future.

Type Field Ok to
Modify*
Description
int serNum N/R Atom's serial number as it appears in coordinate (PDB) file. Although the PDB standard requires all atoms to have unique serial numbers, increasing monotonically by one, the Library does not enforce this, unless the MMDBF_AutoSerials flag is not set prior reading the coordinate file (cf. function CMMDBManager::SetFlag. The serial numbers thus may be considered as free additional atom identifiers.
int index N Atom's index in the Manager's global atom table. This table may be retrieved by function CMMDBManager::GetAtomTable.
AtomName name N/R A PDB name of the atom, represented as null-terminated string. The name is aligned by spaces in accordance with PDB rules.
AltLoc altLoc N/R The alternative location indicator, represented as null-terminated string. If there is no alternative location of the atom, altLoc is set to empty string "" rather than to space.
PCResidue residue N,R Pointer on residue (class CResidue) containing the atom. If this pointer is NULL, it indicates a serious problem in the coordinate hierarchy, not yet a crash.
realtype x,y,z YH x,y,z orthogonal coordinates of the atom, in angstroms; see interpretation of WhatIsSet field.
realtype occupancy YH Occupancy factor of the atom; see interpretation of WhatIsSet field.
realtype tempFactor YH Isotropic temperature factor; see interpretation of WhatIsSet field.
SegID segID N/R Identifier of segment containing the atom represented as left-justified null-terimnated string.
Element element N/R Atom's chemical element name represented as null-terminated string. The field is aligned with spaces in accordance with PDB rules. Note that old PDB files do not contain the element name. After reading such files, element represents a double-space null-terminated string.
AtCharge charge N/R Charge on the atom represented as left-justified null-terminated string.
realtype sigX,sigY,
sigZ
YH Standard deviations of the x,y,z coordinates; see interpretation of WhatIsSet field.
realtype sigOcc YH Standard deviation of occupancy; see interpretation of WhatIsSet field.
realtype sigTemp YH Standard deviation of temperature factor; see interpretation of WhatIsSet field.
realtype u11,u22,
u33,u12,
u13,u23
YH Anisotropic temperature factors; see interpretation of WhatIsSet field.
realtype su11,su22,
su33,su12,
su13,su23
YH Standard deviations of anisotropic temperature factors; see interpretation of WhatIsSet field.
Boolean Het Y An indicator that the atom belongs to a non-standard residue. When Het is set to True, the corresponding PDB record is output with keyword HETATM rather than ATOM.
Boolean Ter N/R An indicator that the atom class represents a chain terminator rather than a real atom. When Ter is set to True, the corresponding PDB record is output with keyword TER rather than ATOM or HETATM. Converting an atom into chain terminator is generally somewhat more than just toggling this field, therefore use function CAtom::MakeTer for this purpose.
word WhatIsSet N/R A word of bit flags, indicating which fields have meaningful values. Many fields, such as standard deviations, have an optional character and may be missing in coordinate files. If this is the case, the corresponding bit in WhatIsSet is set to zero.

Correspondingly, if an application modifies a field that is associated with one of the set flags below, that flag should be set on in WhatIsSet. Otherwise, the field is neglected at file output.

Table of set flags:

Flag name Meaning
ASET_Coordinates x,y,z coordinates are set
ASET_Occupancy atom occupancy is set
ASET_tempFactor the temperature factor is set
ASET_CoordSigma standard deviations for atom coordinates are set
ASET_OccSigma standard deviation for occupancy is set
ASET_tFacSigma standard deviation for temperature factor is set
ASET_Anis_tFac anisotropic temperature factors are set
ASET_Anis_tFSigma  standard deviations for anisotropic temperature factors are set
*N: modification of the field by application may cause malfunction or crash;
Y: the field may be modified by application;
R: reading function is available;
Y/H: the field may be modified by application however there are conditions;
N/R: modification of the field is generally harmless but not recommended.


 CAtom::CAtom ( 
 )
PURPOSE
Default constructor.
DESCRIPTION

Default constructor creates an empty CAtom object. The object is not associated with any residue or coordinate hierarchy.

NOTE : The atom should be stuffed with data (set up using the class' functions or copied from another atom) and added to a residue (unless it has a special use like temporary storage). Empty atom does not make any record in PDB output.


 CAtom::CAtom ( 
PCResidue  res )
PURPOSE
Add-to-residue constructor.
ARGUMENTS
PCResidue res
The residue that should be the atom's owner.

DESCRIPTION

The constructor creates an empty CAtom object and adds it to the specified residue. If the residue is associated with a coordinate hierarchy, the atom is automatically associated with it.

NOTE 1: The atom should be stuffed with data (set up using the class' functions or copied from another atom). Empty atom does not make any record in PDB output.

NOTE 2: Statement "new CAtom(NULL)" is equivalent to "new CAtom()".


 CAtom::~CAtom ( 
 )
PURPOSE
The class' destructor.
DESCRIPTION

The destructor is called implicitely whenever the class instance is deleted. If the atom is properly associated with the coordinate hierarchy, the destructor removes all references on the atom from the hierarchy.

NOTE : Deleting an atom is an editing operation. If it is done by application explicitely, like in the following example:

    PCMMDBManager MMDB;
    PCAtom        atom;
      atom = MMDB->GetAtom ( "/1/A/33(SER).A/CA[C]" );
      delete atom;  // this is where the destructor is called!
    
then the application must call CMMDBManager::FinishStructEdit function before using any results of such deletion(s).

If the deletion is done implicitely by a Library function in the course of other action(s), there is no need for application to call CMMDBManager::FinishStructEdit after that.


int CAtom::GetModelNum ( 
 )
PURPOSE
Obtaining number of model containing the atom.
DESCRIPTION

The function returns number of model that contains the atom. Models are numbered 1.. on. If atom is not properly associated with coordinate hierarchy, the function returns 0.


pstr CAtom::GetChainID ( 
 )
PURPOSE
Obtaining identifier of chain containing the atom.
DESCRIPTION

The function returns identifier of chain that contains the atom. If the chain does not have an ID, the function returns empty string "". If atom is not properly associated with coordinate hierarchy, the function returns NULL.


pstr CAtom::GetResName ( 
 )
PURPOSE
Obtaining name of residue containing the atom.
DESCRIPTION

The function returns name of residue that contains the atom. If atom is not properly associated with coordinate hierarchy, the function returns NULL.


int CAtom::GetSeqNum ( 
 )
PURPOSE
Obtaining sequence number of residue containing the atom.
DESCRIPTION

The function returns sequence number of residue that contains the atom. If atom is not properly associated with coordinate hierarchy, the function returns ATOM_NoSeqNum.


pstr CAtom::GetInsCode ( 
 )
PURPOSE
Obtaining insertion code of residue containing the atom.
DESCRIPTION

The function returns insertion code of residue that contains the atom. If the residue does not have insertion code, the function returns empty string "". If atom is not properly associated with coordinate hierarchy, the function returns NULL.


PCResidue CAtom::GetResidue ( 
 )
PURPOSE
Obtaining pointer on residue containing the atom.
DESCRIPTION

The function returns pointer on residue that contains the atom. If atom is not properly associated with coordinate hierarchy, the function returns NULL.


PCChain CAtom::GetChain ( 
 )
PURPOSE
Obtaining pointer on chain containing the atom.
DESCRIPTION

The function returns pointer on chain that contains the atom. If atom is not properly associated with coordinate hierarchy, the function returns NULL.


PCModel CAtom::GetModel ( 
 )
PURPOSE
Obtaining pointer on model containing the atom.
DESCRIPTION

The function returns pointer on model that contains the atom. If atom is not properly associated with coordinate hierarchy, the function returns NULL.


Boolean CAtom::isInSelection ( 
int  selHnd )
PURPOSE
Checking if atom is selected.
ARGUMENTS
int selHnd
Selection handle.

DESCRIPTION

The function returns True if atom is selected for the specified selection handle, and False otherwise.

NOTE : The function returns False if atom is not properly associated with coordinate hierarchy.


pstr CAtom::SetAtomName ( 
AtomName  atomName )
PURPOSE
Setting the atom name.
ARGUMENTS
AtomName atomName
The new atom name.

DESCRIPTION

This function assigns a new name to the atom, i.e. renames it.

NOTE : The function does not align atom names. It is responsibility of application to check that the new atom name complies with PDB standard.


pstr CAtom::SetElementName ( 
Element  elName )
PURPOSE
Setting the chamical element name.
ARGUMENTS
Element elName
The new chemical element name.

DESCRIPTION

This function assigns a new chemical element name to the atom, i.e. renames its chemical name.

NOTE : The function does align the chemical element name to the right of 2-character field, if necessary. The function however does not check validity of the new name.


void CAtom::MakeTer ( 
 )
PURPOSE
Converting atom into chain terminator.
DESCRIPTION

The function converts atom into chain terminator. Using this function is the only proper way of setting a terminator in the end of chain. An application should simply add an atom to chain and then convert it to chain terminator.


void CAtom::SetCoordinates ( 
realtype  xx, 
realtype yy,
realtype zz,
realtype occ,
realtype tFac )
PURPOSE
Setting coordinates, occupancy and temperature factor for the atom.
ARGUMENTS
realtype xx
The x-coordinate of the atom, in angstroms.

realtype yy
The y-coordinate of the atom, in angstroms.

realtype zz
The z-coordinate of the atom, in angstroms.

realtype occ
The atom occupancy factor.

realtype tFac
The atom temperature factor.

DESCRIPTION

The function writes the values of x,y,z coordinates, occupancy and temperature factors into the corresponding class' fields, and set up the relevant bits in WhatIsSet word.


pstr CAtom::GetAtomID ( 
pstr  AtomID )
PURPOSE
Obtaining a full atom's coordinate ID.
ARGUMENTS
pstr AtomID
A string to accept the atom's coordinate ID.

DESCRIPTION

The function calculates a full coordinate ID of the atom and returns it in the supplied string. The same string is returned as the function value.

If atom is not properly associated with coordinate hierarchy, the coordinate ID will contain dashes "-" for those elements that could not be identified.

NOTE : The function does not make any checks on the sufficiency of string buffer AtomID to accept the information. A value of 100 characters for the buffer length is recommended.


pstr CAtom::GetAtomIDfmt ( 
pstr  AtomID )
PURPOSE
Obtaining a full, formatted atom's coordinate ID.
ARGUMENTS
pstr AtomID
A string to accept the atom's coordinate ID.

DESCRIPTION

The function is similar to CAtom::GetAtomID, but it produces CIDs aligned with spaces such that they look uniformly when output tablewise.

The alignment is reached by giving all necessary space for the model number (depends on the total number of models present in the coordinate hierarchy, not less than 3 symbols for the sequence number and exactly 1, 3, 1, 4, 2 and 1 symbols for the chain ID, residue name, insertion code, atom name, chemical element name and alternative location indicator, respectively.

If atom is not properly associated with coordinate hierarchy, the coordinate ID will contain dashes "-" for those elements that could not be identified. The number of dashes is chosen such that to suite the alignment criteria.

NOTE : The function does not make any checks on the sufficiency of string buffer AtomID to accept the information. A value of 100 characters for the buffer length is recommended.


int CAtom::CheckID ( 
AtomName  aname, 
Element elname,
AltLoc aloc )
PURPOSE
Checking the atom's ID by atom name, chemical element name and alternative location indicator.
ARGUMENTS
AtomName aname
The atom name. It may or may not be aligned (as in a PDB file), only first word of the name will be considered (thus "CA", " CA" and " CA B" are all considered as "CA"). aname may be set to NULL or to wildcard "*", then this parameter is ignored.

Element elname
The atom's chemical element code. This parameter will work only if the element code was set up for the atom (which may take place in the case of reading atoms from old PDB files that do not contain the chemical element names; or if the atom was created in a tricky way by application). elname should be used to distinguish between, e.g. "Ca" and "C_alpha". All spaces in elname are ignored. elname may be set to NULL (default), or to wildcard "*", then this parameter is ignored.

AltLoc aloc
The atom's alternative location indicator. If atom does not have alternative location, this is indicated by empty string ""(default). aloc may be set to NULL or to wildcard "*", then this parameter is ignored.

DESCRIPTION

The function returns 1 if the atom is identified by given atom name, chemical element and alternative location indicator, and 0 otherwise.

The atom is considered as identified, if all non-NULL, non-wildcard parameters do match. If all parameters are set NULL or wildcard, any atom is identified. Default values for elname and aloc correspond to 'any element' and 'no alternative location indicator'.

NOTE 1: The model serial number, chain ID, residue sequence number and insertion code are not taken into account by this function.

NOTE 2: Comparison is case-sensitive. Consider that " " is not an empty string.


int CAtom::CheckIDS ( 
pstr  CID )
PURPOSE
Checking the atom's ID by coordinate ID.
ARGUMENTS
pstr CID
The atom's coordinate ID. Only the part of coordinate ID containing atom name, chemical element name and alternative location indicator is taken into consideration.

DESCRIPTION

The function returns 1 if the atom is identified by atom name, chemical element and alternative location indicator found in the provided coordinate ID, and 0 otherwise.

The atom is considered as identified, if all identifying items in the provided coordinate ID do match those of atom. If all coordinate ID items are set to wildcards "*", any atom is identified.

NOTE 1: The model serial number, chain ID, residue sequence number and insertion code are not taken into account by this function.

NOTE 2: Comparison is case-sensitive. Any spaces in the coordinate ID are ignored.

NOTE 3: This function allows for coordinate ID containing only atom name, e.g. "CA", without accompanying square brackets or colon, as is generally required by the coordinate ID syntax.


void CAtom::Transform ( 
mat33 &  m, 
vect3 & v )
PURPOSE
Transformation of atom coordinates with 3x3-matrix and 3-vector.
ARGUMENTS
mat33 & m
The transformation matrix.

vect3 & v
The translation vector.

DESCRIPTION

The function performs the following transformation of atom's x,y,z coordinates:

      x := m[0][0]*x + m[0][1]*y + m[0][2]*z + v[0]
      y := m[1][0]*x + m[1][1]*y + m[1][2]*z + v[1]
      z := m[2][0]*x + m[2][1]*y + m[2][2]*z + v[2]
    


void CAtom::Transform ( 
mat44 &  m )
PURPOSE
Transformation of atom coordinates with 4x4-matrix.
ARGUMENTS
mat44 & m
The transformation matrix.

DESCRIPTION

The function performs the following transformation of atom's x,y,z coordinates:

      x := m[0][0]*x + m[0][1]*y + m[0][2]*z + m[0][3]
      y := m[1][0]*x + m[1][1]*y + m[1][2]*z + m[1][3]
      z := m[2][0]*x + m[2][1]*y + m[2][2]*z + m[2][3]
    


Boolean CAtom::isMetal ( 
 )
PURPOSE
Checking if the atom is identified as a metal.
DESCRIPTION

The function returns True if the atom is identified as a metal.


int CAtom::PutUDData ( 
int  UDDhandle, 
int iudd )
PURPOSE
Storing an integer User-Defined Data (UDD) in the atom.
ARGUMENTS
int UDDhandle
The UDD handle.

int iudd
The integer number to be stored in the atom.

DESCRIPTION

The function stores an integer contained in iudd in the atom, 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.


RETURN

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 atom, the data was not stored
UDDATA_WrongUDRType    the UDD handle UDDhandle was not registered for use in atoms, the data was not stored


int CAtom::PutUDData ( 
int  UDDhandle, 
realtype rudd )
PURPOSE
Storing a real-type User-Defined Data (UDD) in the atom.
ARGUMENTS
int UDDhandle
The UDD handle.

realtype rudd
The real number to be stored in the atom.

DESCRIPTION

The function stores the real number contained in rudd in the atom, 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 CAtom::PutUDData, see returns there.


int CAtom::PutUDData ( 
int  UDDhandle, 
pstr sudd )
PURPOSE
Storing a string-type User-Defined Data (UDD) in the atom.
ARGUMENTS
int UDDhandle
The UDD handle.

pstr sudd
The string to be stored in the atom.

DESCRIPTION

The function stores the string pointed by sudd in the atom, 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 CAtom::PutUDData, see returns there.


int CAtom::GetUDData ( 
int  UDDhandle, 
int & iudd )
PURPOSE
Retrieving an integer User-Defined Data (UDD) from the atom.
ARGUMENTS
int UDDhandle
The UDD handle.

int & iudd
The buffer to accept the integer data.

DESCRIPTION

The function retrieves an integer previously stored in the atom by function CAtom::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.


RETURN

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 atom. iudd returns zero.
UDDATA_WrongHandle    the UDD handle UDDhandle does not correspond to any registered UDD for the atom. iudd returns zero.
UDDATA_WrongUDRType    the UDD handle UDDhandle was not registered for use in atoms. iudd does not change.


int CAtom::GetUDData ( 
int  UDDhandle, 
real & rudd )
PURPOSE
Retrieving a real-type User-Defined Data (UDD) from the atom.
ARGUMENTS
int UDDhandle
The UDD handle.

real & rudd
The buffer to accept the real-type data.

DESCRIPTION

The function retrieves a real number previously stored in the atom by function CAtom::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.


RETURN

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 atom. rudd returns zero.
UDDATA_WrongHandle    the UDD handle UDDhandle does not correspond to any registered UDD for the atom. rudd returns zero.
UDDATA_WrongUDRType    the UDD handle UDDhandle was not registered for use in atoms. rudd does not change.


int CAtom::GetUDData ( 
int  UDDhandle, 
pstr & sudd )
PURPOSE
Retrieving a string-type User-Defined Data (UDD) from the atom, dynamic buffer.
ARGUMENTS
int UDDhandle
The UDD handle.

pstr & sudd
A pointer to dynamically-allocated string accepting the data.

DESCRIPTION

The function retrieves a string previously stored in the atom by function CAtom::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.


RETURN

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 atom. sudd returns NULL.
UDDATA_WrongHandle    the UDD handle UDDhandle does not correspond to any registered UDD for the atom. sudd returns NULL.
UDDATA_WrongUDRType    the UDD handle UDDhandle was not registered for use in atoms. sudd does not change.


int CAtom::GetUDData ( 
int  UDDhandle, 
pstr sudd,
int maxlen )
PURPOSE
Retrieving a string-type User-Defined Data (UDD) from the atom, fixed-size buffer.
ARGUMENTS
int UDDhandle
The UDD handle.

pstr sudd
A pointer to a string accepting the data.

int maxlen
A maximal number of characters, including the terminating NULL that sudd may to accept (not more than the physical length of sudd).

DESCRIPTION

The function retrieves a string previously stored in the atom by function CAtom::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.


RETURN

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 atom. sudd returns empty string "".
UDDATA_WrongHandle    the UDD handle UDDhandle does not correspond to any registered UDD for the atom. sudd returns empty string "".
UDDATA_WrongUDRType    the UDD handle UDDhandle was not registered for use in atoms. sudd does not change.


int CAtom::AddBond ( 
PCAtom  bond_atom, 
int bond_order,
int nAdd_bonds )
PURPOSE
Adding an atom to the list of binded atoms.
ARGUMENTS
PCAtom bond_atom
The atom that should be considered as bonded to "this one". Both atoms must be belong to the same coordinate hierarchy, which essentially means that application may establish bond relations only between atoms, whose pointers were obtained from CMMDBManager (or from CModel/CChain/CResidue contained in CMMDBManager).

int bond_order
The bond order. Although an arbitrary integer < 256 may be employed, use of MMDB's constants BOND_SINGLE, BOND_DOUBLE, BOND_AROMATIC and BOND_TRIPLE is recommended.

int nAdd_bonds
The number of memory units to be reserved (not less than 1) additionally in the case the atom's bond memory is exchausted. Setting this parameter to a value greater than 1 deacreases the number of memory reallocations, which results in a better performance and a possible waste of RAM. Ideally, this parameter should be set to the number of atom's bonds if that is known a priori. This parameter has default setting of 1.

DESCRIPTION

The function adds pointer on the bond_atom and bond order characteristics bond_order to the atom's list of bonds.


RETURN

The function returns a positive (>0) number of total bonds for the atom in the case of successful completion. A zero or negative return means that the atom has already been added into the list of bonds and if found there at position -return.

NOTE : Setting bond_atom bonded to "this" atom does not imply that "this" atom is automatically bonded to bond_atom. The application should take care of setting symmetrical bonds if necessary.


int CAtom::GetNBonds ( 
 )
PURPOSE
Getting the total number of bonds set up for the atom.
DESCRIPTION

The function returns the total number of bonds set up for the atom by function CAtom::AddBond.


void CAtom::FreeBonds ( 
 )
PURPOSE
Removing all bonds set up for the atom.
DESCRIPTION

The function removes all bonds set up for the atom by function CAtom::AddBond.


void CAtom::GetBonds ( 
RPSAtomBondI  AtomBondI, 
int & nAtomBonds )
PURPOSE
Getting the list of indices of bonded atoms.
ARGUMENTS
RPSAtomBondI AtomBondI
A pointer to the list of indices of bonded atoms.

int & nAtomBonds
Returns the total number of bonds set up for the atom by function CAtom::AddBond.

DESCRIPTION

The function returns the list of indices of bonded atoms. Each item is represented by SAtomBondI structure:

struct SAtomBondI  {
  int  index;  // bonded atom index
  byte order;  // bond order
}
where index is the absolute position of atom in coordinate hierarchy plus one. In an ideal PDB file, index is equal to the atom's serial number, however in MMDB these generally do not coincide.

If no bonds were set for the atom, the function returns AtomBondI=NULL and nAtomBonds=0.

NOTE : The application must not attempt to deallocate or alterate AtomBondI obtained from this function. Violation of this will eventually cause a crash.


void CAtom::GetBonds ( 
RPSAtomBond  AtomBond, 
int & nAtomBonds )
PURPOSE
Getting the dynamically-allocated list of bonded atoms.
ARGUMENTS
RPSAtomBond AtomBond
A pointer to the dynamically-allocated list of bonded atoms.

int & nAtomBonds
Returns the total number of bonds set up for the atom by function CAtom::AddBond.

DESCRIPTION

The function returns the list of bonded atoms. Each item is represented by SAtomBond structure:

struct SAtomBond  {
  PCAtom atom;  // bonded atom pointer
  byte  order;  // bond order
}
If AtomBond was not set to NULL before calling this function, the latter will first try to deallocate it. The list of atoms is then allocated in memory, and filled up with atom pointers retrieved from coordinate hierarchy.

If no bonds were set for the atom, the function returns AtomBond=NULL and nAtomBonds=0.

NOTE : It is responsibility of the application to deallocate AtomBond obtained from this function.


void CAtom::GetBonds ( 
PSAtomBond  AtomBond, 
int & nAtomBonds,
int maxlength )
PURPOSE
Getting the dynamically-allocated list of bonded atoms.
ARGUMENTS
PSAtomBond AtomBond
A vector of SAtomBond structures to accept the bond data.

int & nAtomBonds
Returns the total number of bonds set up for the atom by function CAtom::AddBond.

int maxlength
The length of vector AtomBond.

DESCRIPTION

The function returns the list of bonded atoms (no more than maxlength first items) in the vector AtomBond allocated by the application. The structure SAtomBond is defined as follows:

struct SAtomBond  {
  PCAtom atom;  // bonded atom pointer
  byte  order;  // bond order
}

If no bonds were set for the atom, the function returns nAtomBonds=0.

NOTE : It is responsibility of the application to allocate and deallocate vector AtomBond.


void CAtom::Copy ( 
PCAtom  atom )
PURPOSE
Copying the atom contents.
ARGUMENTS
PCAtom atom
The source atom, whose contents is to be copied.

DESCRIPTION

The function copies the content of atom atom into internal class' fields. The function does not copy the residue pointer. As a result, a new atom 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:

      PCAtom a1,a2;
      a1 = new CAtom();
      a2 = new CAtom();
      a2->SetCoordinates ( 1.0,2.0,3.0,1.0,1.0 );
      
      *a1 = *a2;  // never do this!
      
      // the right way:
      a1->Copy ( a2 );
    
Function Copy is supplied for all classes in the Library.



Back to index