mmdb::mmcif::Loop Class Reference

mmcif::Loop represents mmCIF's "loop" category, which keeps rows of data values associated with tags. More...

#include <mmdb_mmcif_.h>

Inheritance diagram for mmdb::mmcif::Loop:

List of all members.

Public Member Functions
	Loop ()
	Basic constructor.
	Loop (cpstr N)
	Constructor that assigns structure name.
	Loop (io::RPStream Object)
	Constructor for MMDB data streaming functions.
	~Loop ()
	Destructor.
void	AddLoopTag (cpstr T, bool Remove=true)
	Adds tag to the loop. The tag is appended to the list of existing tags. The order of tags cannot be changed.
void	AddString (cpstr S, bool NonBlankOnly=false)
	Sets string value at current loop position. When mmcif::Loop::Add[Data] functions use internal loop pointer. When category is created or cleared (by using mmcif::Loop::AddLoopTag ( T,true )) the pointer is set to 0th row and 0th column (tag). After each call to mmcif::Loop::Add[Data] function, internal pointer advances to next column (tag), and wraps over to next row, 0th tag, if list of tags is exhausted. Any remaining fields in last row will be populated with "data not given" value.
void	AddNoData (int NoDataType)
	Sets "data not given" or "data not available" at current loop position. When mmcif::Loop::Add[Data] functions use internal loop pointer. When category is created or cleared (by using mmcif::Loop::AddLoopTag ( T,true )) the pointer is set to 0th row and 0th column (tag). After each call to mmcif::Loop::Add[Data] function, internal pointer advances to next column (tag), and wraps over to next row, 0th tag, if list of tags is exhausted. Any remaining fields in last row will be populated with "data not given" value.
void	AddReal (realtype R, int prec=8)
	Sets float-point value at current loop position. When mmcif::Loop::Add[Data] functions use internal loop pointer. When category is created or cleared (by using mmcif::Loop::AddLoopTag ( T,true )) the pointer is set to 0th row and 0th column (tag). After each call to mmcif::Loop::Add[Data] function, internal pointer advances to next column (tag), and wraps over to next row, 0th tag, if list of tags is exhausted. Any remaining fields in last row will be populated with "data not given" value.
void	AddReal (realtype R, cpstr format)
	Sets float-point value at current loop position in given format. When mmcif::Loop::Add[Data] functions use internal loop pointer. When category is created or cleared (by using mmcif::Loop::AddLoopTag ( T,true )) the pointer is set to 0th row and 0th column (tag). After each call to mmcif::Loop::Add[Data] function, internal pointer advances to next column (tag), and wraps over to next row, 0th tag, if list of tags is exhausted. Any remaining fields in last row will be populated with "data not given" value.
void	AddInteger (int I)
	Sets integer value at current loop position in given format. When mmcif::Loop::Add[Data] functions use internal loop pointer. When category is created or cleared (by using mmcif::Loop::AddLoopTag ( T,true )) the pointer is set to 0th row and 0th column (tag). After each call to mmcif::Loop::Add[Data] function, internal pointer advances to next column (tag), and wraps over to next row, 0th tag, if list of tags is exhausted. Any remaining fields in last row will be populated with "data not given" value.
int	GetLoopLength ()
	Returns current length of the loop (i.e. the number of rows).
pstr	GetField (int rowNo, int tagNo)
	Returns string pointer on the field corresponding to tag in the specified position, in the specified row. Tag positions are defined by the order of their appearance in mmCIF file (if loop was read from a file), or by the order of their addition to the loop (if loop was created programmatically).
int	GetString (pstr &S, cpstr TName, int nrow, bool Remove=false)
	Fetches value, corresponding to the given tag, in the given row, as a string.
pstr	GetString (cpstr TName, int nrow, int &RC)
	Returns pointer to value associated with given tag, in the given row of the loop.
void	CopyString (pstr buf, int maxlength, cpstr TName, int nrow, int &RC)
	Copies value, associated with given tag, in the given row, into specified buffer. Terminating NULL character is appended.
int	DeleteField (cpstr TName, int nrow)
	Deletes field associated with given tag in the given row.
int	DeleteRow (int nrow)
	Deletes all fields in given row.
int	GetReal (realtype &R, cpstr TName, int nrow, bool Remove=false)
	Fetches value, corresponding to the given tag, in the given row, as a real number.
void	CopyReal (realtype &R, cpstr TName, int nrow, int &RC)
	Copies value, associated with given tag, in the given row, into specified destination as a real number.
void	CopyInteger (int &I, cpstr TName, int nrow, int &RC)
	Copies value, associated with given tag, in the given row, into specified destination as an integer number.
int	GetInteger (int &I, cpstr TName, int nrow, bool Remove=false)
	Fetches value, corresponding to the given tag, in the given row, as an integer number.
int	GetSVector (psvector &S, cpstr TName, int i1=0, int i2=MaxInt4, bool Remove=false)
	Fetches set of values, corresponding to the given tag, in the given range of rows, as a vector of strings.
int	GetRVector (rvector &R, cpstr TName, int i1=0, int i2=MaxInt4, bool Remove=false)
	Fetches set of values, corresponding to the given tag, in the given range of rows, as a vector of float-point numbers.
int	GetIVector (ivector &I, cpstr TName, int i1=0, int i2=MaxInt4, bool Remove=false)
	Fetches set of values, corresponding to the given tag, in the given range of rows, as a vector of integer numbers.
void	PutString (cpstr S, cpstr T, int nrow)
	Sets string value for given tag and row.
void	PutNoData (int NoDataType, cpstr T, int nrow)
	Sets "data not given" or "data not available" values for given tag and row.
void	PutReal (realtype R, cpstr T, int nrow, int prec=8)
	Sets float-point value for given tag and row.
void	PutReal (realtype R, cpstr T, int nrow, cpstr format)
	Sets float-point value for given tag and row.
void	PutInteger (int I, cpstr T, int nrow)
	Sets integer value for given tag.
void	PutSVector (psvector S, cpstr T, int i1, int i2)
	Sets a set of string values for the given tag and range of rows.
void	PutRVector (rvector R, cpstr T, int i1, int i2, int prec=8)
	Sets a set of float-point values for the given tag and range of rows.
void	PutIVector (ivector I, cpstr T, int i1, int i2)
	Sets a set of integer values for the given tag and range of rows.
MMCIF_ITEM	GetCategoryID ()
	Returns category type MMCIF_Loop.
void	Optimize ()
	Optimizes loop for RAM and data access speed. Optimized data structures take less RAM and their indexes are sorted for quicker access. Sorting is done automatically as new data is added to the category. If the structure is edited (fields/data removed), it may need optimization and re-sorting for efficiency. The sorting preserves the order of actual appearance of tags and rows in mmCIF file. If a loop is created programmatically, the order of tags and rows in mmCIF file will be the same as order of adding them to the loop.
bool	WriteMMCIFLoop (cpstr FName, io::GZ_MODE gzipMode=io::GZM_CHECK)
	Writes loop data in mmCIF format into file.
void	WriteMMCIF (io::RFile f)
	Writes loop data into given file.
void	Copy (PCategory Loop)
	Deep copy of loops. Deep copy duplicates all data and memory allocations, producing a genuine clone of the original. Only deep copy should be used for copying MMDB objects, a mere assignment operator will fail you.
void	write (io::RFile f)
	MMDB stream writer.
void	read (io::RFile f)
	MMDB stream reader.
Protected Member Functions
void	InitLoop ()
void	FreeMemory ()
void	DeleteFields ()
void	ExpandRows (int nRowsNew)
Protected Attributes
int	nRows
psmatrix	field
int	iColumn
int	nAllocRows
Friends
class	Data

---

Detailed Description

mmcif::Loop represents mmCIF's "loop" category, which keeps rows of data values associated with tags.

mmCIF's "loop" category has the following form:

    loop_
    _loop_name.tag0   value0
    _loop_name.tag1   value1
    ...........
    _loop_name.tagN   valueN
    value00 value10 ... valueN0
    value01 value11 ... valueN1
    ...........
    value0M value1M ... valueNM

mmcif::Loop represents this construct by keeping category name ("_loop_name") and associated lists of tags ("tag0,tag1...tagN") and data vectors ("[value00...value0M],[value10...value1M]...[valueN0...valueNM]").

The loop object is created automatically when an mmCIF file is read, or it may be created programatically and then pushed into file.

Access to data is provided via tags and data indexes. Internally, all values are kept as character fields, and it is only on the retrieval stage that they are converted to other data types (integers, floats or strings). If conversion is not possible, an error code is returned by the corresponding functions, which should be checked by the application.

The following code gives an example of creating mmCIF loop category and populating it with data:

    mmcif::Loop loop;
    char       S[100];
    int        i;

      // Specify loop name:
      loop.SetCategoryName ( "_sample_loop" );

      // Create loop structure, i.e., list of tags first:
      loop.AddLoopTag ( "id"    );
      loop.AddLoopTag ( "name"  );
      loop.AddLoopTag ( "value" );

      // Now populate it with data. This my be done in 2 ways.
      // Here is how you write loop data in stream fashion,
      // value-after-value:
      for (i=0;i<3;i++)  {
        loop.AddInteger ( i );
        sprintf ( S,"1st_way-%i",i );
        loop.AddString ( S );
        loop.AddReal ( 2.5*(i+1) );
      }

      // Here is how you populate loop data using direct-access
      // functions:
      for (i=3;i<6;i++)  {
        loop.PutReal ( 2.5*(i+1),"value",i );
        loop.PutInteger ( i,"id" );
        sprintf ( S,"2nd way: %i",i );
        loop.PutString ( S,"name" );
      }

      loop.WriteMMCIFLoop ( "sample_loop.cif" );

The resulting file sample_loop.cif will contain:

    loop_
    _sample_loop.id
    _sample_loop.name
    _sample_loop.value
    0   1st_way-0     2.5
    1   1st_way-1     5.0
    2   1st_way-2     7.5
    3   "2nd way: 3"  10.0
    4   "2nd way: 4"  12.5
    5   "2nd way: 5"  15.0

See general principles of working with mmCIF files and mmCIF hierarchies, as well as some code samples, in Section "mmcif_handler".

---

Constructor & Destructor Documentation

mmdb::mmcif::Loop::Loop

(

)

Basic constructor.

mmdb::mmcif::Loop::Loop

(

cpstr

N )

Constructor that assigns structure name.

Parameters:

[in]

N

structure name (must start with underscore).

mmdb::mmcif::Loop::Loop

(

io::RPStream

Object )

Constructor for MMDB data streaming functions.

mmdb::mmcif::Loop::~Loop

(

)

Destructor.

---

Member Function Documentation

void mmdb::mmcif::Loop::AddInteger

(

int

I )

Sets integer value at current loop position in given format. When mmcif::Loop::Add[Data] functions use internal loop pointer. When category is created or cleared (by using mmcif::Loop::AddLoopTag ( T,true )) the pointer is set to 0th row and 0th column (tag). After each call to mmcif::Loop::Add[Data] function, internal pointer advances to next column (tag), and wraps over to next row, 0th tag, if list of tags is exhausted. Any remaining fields in last row will be populated with "data not given" value.

Parameters:

[in]

I

integer number with value to be set.

void mmdb::mmcif::Loop::AddLoopTag	(	cpstr	T,
		bool	Remove = true
	)

Adds tag to the loop. The tag is appended to the list of existing tags. The order of tags cannot be changed.

Parameters:

[in]	T	tag name
[in]	Remove	flag to remove all fields in the loop.

void mmdb::mmcif::Loop::AddNoData

(

int

NoDataType )

Sets "data not given" or "data not available" at current loop position. When mmcif::Loop::Add[Data] functions use internal loop pointer. When category is created or cleared (by using mmcif::Loop::AddLoopTag ( T,true )) the pointer is set to 0th row and 0th column (tag). After each call to mmcif::Loop::Add[Data] function, internal pointer advances to next column (tag), and wraps over to next row, 0th tag, if list of tags is exhausted. Any remaining fields in last row will be populated with "data not given" value.

Parameters:

[in]

NoDataType

integer key specifying which type of data absence should be set as a value: CIF_NODATA_DOT for "data not given" CIF_NODATA_QUESTION for "data not available"

void mmdb::mmcif::Loop::AddReal	(	realtype	R,
		int	prec = 8
	)

Sets float-point value at current loop position. When mmcif::Loop::Add[Data] functions use internal loop pointer. When category is created or cleared (by using mmcif::Loop::AddLoopTag ( T,true )) the pointer is set to 0th row and 0th column (tag). After each call to mmcif::Loop::Add[Data] function, internal pointer advances to next column (tag), and wraps over to next row, 0th tag, if list of tags is exhausted. Any remaining fields in last row will be populated with "data not given" value.

Parameters:

[in]	R	real number with value to be set.
[in]	prec	float-point precision; g-format with given precision will be used

void mmdb::mmcif::Loop::AddReal	(	realtype	R,
		cpstr	format
	)

Sets float-point value at current loop position in given format. When mmcif::Loop::Add[Data] functions use internal loop pointer. When category is created or cleared (by using mmcif::Loop::AddLoopTag ( T,true )) the pointer is set to 0th row and 0th column (tag). After each call to mmcif::Loop::Add[Data] function, internal pointer advances to next column (tag), and wraps over to next row, 0th tag, if list of tags is exhausted. Any remaining fields in last row will be populated with "data not given" value.

Sets float-point value for given tag.

Parameters:

[in]	R	real number with value to be set.
[in]	format	format string to convert R.

void mmdb::mmcif::Loop::AddString	(	cpstr	S,
		bool	NonBlankOnly = false
	)

Sets string value at current loop position. When mmcif::Loop::Add[Data] functions use internal loop pointer. When category is created or cleared (by using mmcif::Loop::AddLoopTag ( T,true )) the pointer is set to 0th row and 0th column (tag). After each call to mmcif::Loop::Add[Data] function, internal pointer advances to next column (tag), and wraps over to next row, 0th tag, if list of tags is exhausted. Any remaining fields in last row will be populated with "data not given" value.

Parameters:

[in]	S	character string with value to be set. If S==NULL, the "data not given" value will be set. If S=="" (empty string), the "data not available" value is stored.
[in]	NonBlankOnly	flag to treat white-space-only strings: false: set as is true: set "data not available" value instead.

void mmdb::mmcif::Loop::Copy

(

PCategory

Loop )

[virtual]

Deep copy of loops. Deep copy duplicates all data and memory allocations, producing a genuine clone of the original. Only deep copy should be used for copying MMDB objects, a mere assignment operator will fail you.

Parameters:

[in]

Loop

a pointer to mmcif::Loop, the content of which is copied into 'this' loop.

Reimplemented from mmdb::mmcif::Category.

void mmdb::mmcif::Loop::CopyInteger	(	int &	I,
		cpstr	TName,
		int	nrow,
		int &	RC
	)

Copies value, associated with given tag, in the given row, into specified destination as an integer number.

Parameters:

[out]	I	reference to integer number to accept the value
[in]	TName	character string with tag name
[in]	nrow	row number (0...GetLoopLength()-1)
[out]	RC	return code: CIFRC_NoTag: tag is not found CIFRC_WrongIndex: row is not found CIFRC_NoField: value is not found CIFRC_Ok: success.

Remarks:

Destination I is set 0 if RC!=CIFRC_Ok.

void mmdb::mmcif::Loop::CopyReal	(	realtype &	R,
		cpstr	TName,
		int	nrow,
		int &	RC
	)

Copies value, associated with given tag, in the given row, into specified destination as a real number.

Parameters:

[out]	R	reference to real number to accept the value
[in]	TName	character string with tag name
[in]	nrow	row number (0...GetLoopLength()-1)
[out]	RC	return code: CIFRC_NoTag: tag is not found CIFRC_WrongIndex: row is not found CIFRC_NoField: value is not found CIFRC_Ok: success.

Remarks:

Destination R is set 0 if RC!=CIFRC_Ok.

void mmdb::mmcif::Loop::CopyString	(	pstr	buf,
		int	maxlength,
		cpstr	TName,
		int	nrow,
		int &	RC
	)

Copies value, associated with given tag, in the given row, into specified buffer. Terminating NULL character is appended.

Parameters:

[out]	buf	character string to accept the value
[in]	maxlength	maximum number of bytes to copy
[in]	TName	character string with tag name
[in]	nrow	row number (0...GetLoopLength()-1)
[out]	RC	return code: CIFRC_NoTag: tag is not found CIFRC_WrongIndex: row is not found CIFRC_NoField: value is not found CIFRC_Ok: success.

Remarks:

Destination string buf is not modified if RC!=CIFRC_Ok .

int mmdb::mmcif::Loop::DeleteField	(	cpstr	TName,
		int	nrow
	)

Deletes field associated with given tag in the given row.

Parameters:

[in]	TName	character string with tag name
[in]	nrow	row number (0...GetLoopLength()-1)

Returns:

>=0: field deleted

<0: either field or tag is not found

void mmdb::mmcif::Loop::DeleteFields

(

)

[protected]

int mmdb::mmcif::Loop::DeleteRow

(

int

nrow )

Deletes all fields in given row.

Parameters:

[in]

nrow

row number (0...GetLoopLength()-1)

Returns:

CIFRC_Ok: fields deleted

CIFRC_WrongIndex: row not found

Remarks:

Note that this function delets just the fields, but not the row. If you wish the row to be deleted, call mmcif::Loop::Optimize() function after this one.

void mmdb::mmcif::Loop::ExpandRows

(

int

nRowsNew )

[protected]

void mmdb::mmcif::Loop::FreeMemory

(

)

[protected, virtual]

Reimplemented from mmdb::mmcif::Category.

MMCIF_ITEM mmdb::mmcif::Loop::GetCategoryID

(

)

[inline, virtual]

Returns category type MMCIF_Loop.

Reimplemented from mmdb::mmcif::Category.

pstr mmdb::mmcif::Loop::GetField	(	int	rowNo,
		int	tagNo
	)

Returns string pointer on the field corresponding to tag in the specified position, in the specified row. Tag positions are defined by the order of their appearance in mmCIF file (if loop was read from a file), or by the order of their addition to the loop (if loop was created programmatically).

Parameters:

[in]	rowNo	row number (0...GetLoopLength()-1)
[in]	tagNo	tag number (0...GetNofTags()-1)

Returns:

NULL: tag or row do not exist

CIF_NODATA_DOT_FIELD the field contains "data not given" value

CIF_NODATA_QUESTION_FIELD the field contains "data not available" value

not NULL: string value of the field

Remarks:

Never try to dispose memory pointed by the return value, or your program will crash.

int mmdb::mmcif::Loop::GetInteger	(	int &	I,
		cpstr	TName,
		int	nrow,
		bool	Remove = false
	)

Fetches value, corresponding to the given tag, in the given row, as an integer number.

Parameters:

[out]	I	reference to integer number to accept the value. In case of failure, R returns zero.
[in]	TName	character string with tag name
[in]	nrow	row number (0...GetLoopLength()-1)
[in]	Remove	flag to remove the field from the loop after it is read.

Returns:

CIFRC_NoTag: tag is not found

CIFRC_WrongIndex: row not found

CIFRC_NoField: field is not found

CIFRC_WrongFormat: value is not a real or integer number.

CIFRC_NoData: value is either "data not available" or "data not given".

CIFRC_Ok: success.

int mmdb::mmcif::Loop::GetIVector	(	ivector &	I,
		cpstr	TName,
		int	i1 = 0,
		int	i2 = MaxInt4,
		bool	Remove = false
	)

Fetches set of values, corresponding to the given tag, in the given range of rows, as a vector of integer numbers.

Parameters:

[out]	I	reference to float-point vector to accept the values. if I==NULL , the vector will be allocated with starting index of i1.
[in]	TName	character string with tag name
[in]	i1	minimum row number to fetch, the actual index will be calculated as max(0,min(i1,i2))
[in]	i2	maximum row number to fetch, the actual index will be calculated as min(GetLoopLength()-1,max(i1,i2))
[in]	Remove	flag to remove fetched fields from the loop after they are read.

Returns:

CIFRC_NoTag: tag is not found

CIFRC_WrongIndex: invalid range of rows

CIFRC_Ok: success.

For safe use, I should be pre-allocated by calling process. Only elements I[i1] to I[i2] will contain fetched data, others remain untouched. The calling process is responsible for the disposal of I. See example in mmcif::Loop::GetRVector documentation for details.

int mmdb::mmcif::Loop::GetLoopLength

(

)

[inline]

Returns current length of the loop (i.e. the number of rows).

Returns:

number of data rows in the loop.

int mmdb::mmcif::Loop::GetReal	(	realtype &	R,
		cpstr	TName,
		int	nrow,
		bool	Remove = false
	)

Fetches value, corresponding to the given tag, in the given row, as a real number.

Parameters:

[out]	R	reference to real number to accept the value. In case of failure, R returns zero.
[in]	TName	character string with tag name
[in]	nrow	row number (0...GetLoopLength()-1)
[in]	Remove	flag to remove the field from the loop after it is read.

Returns:

CIFRC_NoTag: tag is not found

CIFRC_WrongIndex: row not found

CIFRC_NoField: field is not found

CIFRC_WrongFormat: value is not a real or integer number.

CIFRC_NoData: value is either "data not available" or "data not given".

CIFRC_Ok: success.

int mmdb::mmcif::Loop::GetRVector	(	rvector &	R,
		cpstr	TName,
		int	i1 = 0,
		int	i2 = MaxInt4,
		bool	Remove = false
	)

Fetches set of values, corresponding to the given tag, in the given range of rows, as a vector of float-point numbers.

Parameters:

[out]	R	reference to float-point vector to accept the values. if R==NULL , the vector will be allocated with starting index of i1.
[in]	TName	character string with tag name
[in]	i1	minimum row number to fetch, the actual index will be calculated as max(0,min(i1,i2))
[in]	i2	maximum row number to fetch, the actual index will be calculated as min(GetLoopLength()-1,max(i1,i2))
[in]	Remove	flag to remove fetched fields from the loop after they are read.

Returns:

CIFRC_NoTag: tag is not found

CIFRC_WrongIndex: invalid range of rows

CIFRC_Ok: success.

For safe use, R should be pre-allocated by calling process. Only elements R[i1] to R[i2] will contain fetched data, others remain untouched. The calling process is responsible for the disposal of R. Example:

 mmcif::Loop loop;
 rvector    R;  // equivalent to realtype *R
 int        i,i1,i2,rc,n;

    // ... get loop data

    n  = loop.GetLoopLength();
    i1 = 5;  i2 = n - 5;  // could be wrong!

    //  allocate a vector of real numbers
    GetVectorMemory ( R,n,0 );  // "0" for starting index
    // no need to initiaize unless required for the
    // application

    rc = loop.GetRVector ( R,"value",i1,i2 );
    printf ( " Fetched with return code rc=%i\n",rc );
        // you may want a more thorough treatment of
        // the return code here
    for (i=i1;i<=i2;i++)
      printf ( " value[%4i] = %15.7g\n",i,R[i] );

    //  R[] may be re-used for as many fetches as necessary
    //  without cleaning or disposals

    //  dispose of the vector
    FreeVectorMemory ( R,0 );  // "0" for starting index

int mmdb::mmcif::Loop::GetString	(	pstr &	S,
		cpstr	TName,
		int	nrow,
		bool	Remove = false
	)

Fetches value, corresponding to the given tag, in the given row, as a string.

Parameters:

[out]	S	pointer to string, which will point to newly allocated character string, containing value associated with tag TName and row nrow. If tag, row or value is not found, or if value corresponds to mmCIF's "data not given" or "data not available", S returns NULL.
[in]	TName	character string with tag name
[in]	nrow	row number (0...GetLoopLength()-1)
[in]	Remove	flag to remove the field from structure after it is read.

Returns:

CIFRC_NoTag: tag is not found

CIFRC_WrongIndex: row is not found

CIFRC_NoField: value is not found

CIFRC_Ok: success. If S returns NULL, then the value corresponds to either "data not available" or "data not given".

Remarks:

If S!=NULL at time of call, the function will try to dispose the string it points on. This allows a slick re-use of the same pointer in consequitive calls. This also means that one should never pass unallocated pointer to this function. Safe use assumes the following patern:

  mmcif::Loop mmCIFLoop;
  pstr S;  // this is merely "char *S"
  int  rc;

    S  = NULL; // null pointer before first use
    rc = mmCIFLoop.GetString ( S,"id",1 );
    if (rc)  CreateCopy ( S,"*** data not found" );
    if (!S)  CreateCopy ( S,"*** data not given or not available" );
    printf ( " rc=%i, S='%s'\n",rc,S );

    rc = mmCIFLoop.GetString ( S,"property",0 );
    if (rc)  CreateCopy ( S,"*** data not found" );
    if (!S)  CreateCopy ( S,"*** data not given or not available" );
    printf ( " rc=%i, S='%s'\n",rc,S );

    // etc etc etc

    delete[] S;  // application is responsible for final
                 // disposal of memory

pstr mmdb::mmcif::Loop::GetString	(	cpstr	TName,
		int	nrow,
		int &	RC
	)

Returns pointer to value associated with given tag, in the given row of the loop.

Parameters:

[in]	TName	character string with tag name
[in]	nrow	row number (0...GetLoopLength()-1)
[out]	RC	return code: CIFRC_NoTag: tag is not found CIFRC_WrongIndex: row is not found CIFRC_NoField: value is not found CIFRC_Ok: success. If function returns NULL, then the value corresponds to either "data not available" or "data not given".

Returns:

NULL: either tag, row or value is not found, or the value is "data not available" or "data not given". Read return code RC in order to interpret NULL return.

not NULL: pointer (char *) to value associated with TName.

Remarks:

Never try to dispose memory pointed by the return value, or your program will crash.

int mmdb::mmcif::Loop::GetSVector	(	psvector &	S,
		cpstr	TName,
		int	i1 = 0,
		int	i2 = MaxInt4,
		bool	Remove = false
	)

Fetches set of values, corresponding to the given tag, in the given range of rows, as a vector of strings.

Parameters:

[out]	S	reference to string vector to accept the values. if S==NULL , the vector will be allocated with starting index of i1.
[in]	TName	character string with tag name
[in]	i1	minimum row number to fetch, the actual index will be calculated as max(0,min(i1,i2))
[in]	i2	maximum row number to fetch, the actual index will be calculated as min(GetLoopLength()-1,max(i1,i2))
[in]	Remove	flag to remove fetched fields from the loop after they are read.

Returns:

CIFRC_NoTag: tag is not found

CIFRC_WrongIndex: invalid range of rows

CIFRC_Ok: success.

For safe use, S should be pre-allocated by calling process. Only elements S[i1] to S[i2] will contain fetched data, others remain untouched. The calling process is responsible for the disposal of S. Example:

 mmcif::Loop loop;
 psvector   S;  // equivalent to char **S
 int        i,i1,i2,rc,n;

    // ... get loop data

    n  = loop.GetLoopLength();
    i1 = 5;  i2 = n - 5;  // could be wrong!

    //  allocate vector of strings
    GetVectorMemory ( S,n,0 );  // "0" for starting index
    for (i=0;i<n;i++)
      S[i] = NULL;  // initialize NULL string pointers

    loop.GetSVector ( S,"name",i1,i2 );
    printf ( " Fetched with return code rc=%i\n",rc );
        // you may want a more thorough treatment of
        // the return code here
    for (i=i1;i<=i2;i++)
      if (S[i])  printf ( " %4i. name='%s'\n",i,S[i] );
           else  printf ( " %4i. name is not available\n",i );

    //  S[] may be re-used for as many fetches as necessary
    //  without cleaning or disposals

    //  dispose of vector of strings
    for (i=0;i<n;i++)
      if (S[i])  delete[] S[i];
    FreeVectorMemory ( S,0 );  // "0" for starting index

void mmdb::mmcif::Loop::InitLoop

(

)

[protected]

void mmdb::mmcif::Loop::Optimize

(

)

[virtual]

Optimizes loop for RAM and data access speed. Optimized data structures take less RAM and their indexes are sorted for quicker access. Sorting is done automatically as new data is added to the category. If the structure is edited (fields/data removed), it may need optimization and re-sorting for efficiency.

The sorting preserves the order of actual appearance of tags and rows in mmCIF file. If a loop is created programmatically, the order of tags and rows in mmCIF file will be the same as order of adding them to the loop.

Reimplemented from mmdb::mmcif::Category.

void mmdb::mmcif::Loop::PutInteger	(	int	I,
		cpstr	T,
		int	nrow
	)

Sets integer value for given tag.

Parameters:

[in]	I	integer number with value to be set.
[in]	T	character string with tag name. If tag is not found, it will be added, and all data in the loop will be reindexed accordingly.
[in]	nrow	row number. If the row does not exist then it will be created, along with all other rows between GetLoopLength()-1 and nrow as necessary. All newly created fields will be initialised with "data not given" value.

void mmdb::mmcif::Loop::PutIVector	(	ivector	I,
		cpstr	T,
		int	i1,
		int	i2
	)

Sets a set of integer values for the given tag and range of rows.

Parameters:

[in]	I	vector of integers to store in the loop
[in]	T	character string with tag name. If tag is not found, it will be added, and all data in the loop will be reindexed accordingly.
[in]	i1	minimum data index in S to set in the loop
[in]	i2	maximum data index in S to set in the loop.

The data will be set in rows i1 to i2 (inclusive) in the loop. If range [i1,i2] is not contained in the loop, all missing rows will be created and initialised to "data not given" value.

void mmdb::mmcif::Loop::PutNoData	(	int	NoDataType,
		cpstr	T,
		int	nrow
	)

Sets "data not given" or "data not available" values for given tag and row.

Parameters:

[in]	NoDataType	can be either CIF_NODATA_DOT for "data not given" CIF_NODATA_QUESTION for "data not available"
[in]	T	character string with tag name. If tag is not found, it will be added, and all data in the loop will be reindexed accordingly.
[in]	nrow	row number. If the row does not exist then it will be created, along with all other rows between GetLoopLength()-1 and nrow as necessary. All newly created fields will be initialised with "data not given" value.

void mmdb::mmcif::Loop::PutReal	(	realtype	R,
		cpstr	T,
		int	nrow,
		cpstr	format
	)

Sets float-point value for given tag and row.

Parameters:

[in]	R	real number with value to be set.
[in]	T	character string with tag name. If tag is not found, it will be added, and all data in the loop will be reindexed accordingly.
[in]	nrow	row number. If the row does not exist then it will be created, along with all other rows between GetLoopLength()-1 and nrow as necessary. All newly created fields will be initialised with "data not given" value.
[in]	format	format string to convert R.

void mmdb::mmcif::Loop::PutReal	(	realtype	R,
		cpstr	T,
		int	nrow,
		int	prec = 8
	)

Sets float-point value for given tag and row.

Parameters:

[in]	R	real number with value to be set.
[in]	T	character string with tag name. If tag is not found, it will be added, and all data in the loop will be reindexed accordingly.
[in]	nrow	row number. If the row does not exist then it will be created, along with all other rows between GetLoopLength()-1 and nrow as necessary. All newly created fields will be initialised with "data not given" value.
[in]	prec	float-point precision; g-format with given precision will be used

void mmdb::mmcif::Loop::PutRVector	(	rvector	R,
		cpstr	T,
		int	i1,
		int	i2,
		int	prec = 8
	)

Sets a set of float-point values for the given tag and range of rows.

Parameters:

[in]	R	vector of real numbers to store in the loop
[in]	T	character string with tag name. If tag is not found, it will be added, and all data in the loop will be reindexed accordingly.
[in]	i1	minimum data index in S to set in the loop
[in]	i2	maximum data index in S to set in the loop
[in]	prec	float-point precision; g-format with given precision will be used.

The data will be set in rows i1 to i2 (inclusive) in the loop. If range [i1,i2] is not contained in the loop, all missing rows will be created and initialised to "data not given" value.

void mmdb::mmcif::Loop::PutString	(	cpstr	S,
		cpstr	T,
		int	nrow
	)

Sets string value for given tag and row.

Parameters:

[in]	S	character string with value to be set. If S==NULL, the "data not given" value will be set. If S=="" (empty string), the "data not available" value is stored.
[in]	T	character string with tag name. If tag is not found, it will be added, and all data in the loop will be reindexed accordingly.
[in]	nrow	row number. If the row does not exist then it will be created, along with all other rows between GetLoopLength()-1 and nrow as necessary. All newly created fields will be initialised with "data not given" value.

void mmdb::mmcif::Loop::PutSVector	(	psvector	S,
		cpstr	T,
		int	i1,
		int	i2
	)

Sets a set of string values for the given tag and range of rows.

Parameters:

[in]	S	string vector with values to store in the loop
[in]	T	character string with tag name. If tag is not found, it will be added, and all data in the loop will be reindexed accordingly.
[in]	i1	minimum data index in S to set in the loop
[in]	i2	maximum data index in S to set in the loop.

The data will be set in rows i1 to i2 (inclusive) in the loop. If range [i1,i2] is not contained in the loop, all missing rows will be created and initialised to "data not given" value. Example:

 mmcif::Loop loop("_sample_loop");
 pstr       S[100];
 int        i;

    //  initialize vector of strings
    for (i=0;i<100;i++)  {
      S[i] = new char[20];
      sprintf ( S[i],"value i=%i",i );
    }

    //  put data in loop
    loop.PutSVector ( S,"made_up_string_value",0,99 );

    //  dispose of vector of strings
    for (i=0;i<100;i++)
      if (S[i])  delete[] S[i];

void mmdb::mmcif::Loop::read

(

io::RFile

f )

MMDB stream reader.

Reimplemented from mmdb::mmcif::Category.

void mmdb::mmcif::Loop::write

(

io::RFile

f )

MMDB stream writer.

Reimplemented from mmdb::mmcif::Category.

void mmdb::mmcif::Loop::WriteMMCIF

(

io::RFile

f )

[virtual]

Writes loop data into given file.

Parameters:

f	reference to MMDB's file class. The file should be opened and closed by application.

Remarks:

There is a very limited use of this function on application level. It is primarily used by mmcif::Data class.

Reimplemented from mmdb::mmcif::Category.

bool mmdb::mmcif::Loop::WriteMMCIFLoop	(	cpstr	FName,
		io::GZ_MODE	gzipMode = io::GZM_CHECK
	)

Writes loop data in mmCIF format into file.

Parameters:

[in]	FName	character string with file name.
[in]	gzipMode	flag to controll compression of files: GZM_NONE: do not compress GZM_CHECK: check file name suffix and compress (or not) accordingly GZM_ENFORCE_GZIP: force gzip compression despite suffix GZM_ENFORCE_COMPRESS: force using compress despite suffix

Returns:

true: success

false: can not open file for writing.

Remarks:

This function does not create a valid mmCIF file as "data_XXX" record will be missing. It may be used for debugging though.

---

Friends And Related Function Documentation

friend class Data [friend]

Reimplemented from mmdb::mmcif::Category.

---

Member Data Documentation

psmatrix mmdb::mmcif::Loop::field [protected]

int mmdb::mmcif::Loop::iColumn [protected]

int mmdb::mmcif::Loop::nAllocRows [protected]

int mmdb::mmcif::Loop::nRows [protected]

---

The documentation for this class was generated from the following files:

• src/mmdb_mmcif_.h
• src/mmdb_mmcif_.cpp