mmdb::mmcif::Struct Class Reference

mmcif::Struct represents mmCIF's "structure" category, where data follows directly the corresponding tag. More...

#include <mmdb_mmcif_.h>

Inheritance diagram for mmdb::mmcif::Struct:

List of all members.

Public Member Functions
	Struct ()
	Basic constructor.
	Struct (cpstr N)
	Constructor that assigns structure name.
	Struct (io::RPStream Object)
	Constructor for MMDB data streaming functions.
	~Struct ()
	Destructor.
void	AddField (cpstr F, cpstr T, bool Concatenate=false)
	Adds field to the structure.
MMCIF_ITEM	GetCategoryID ()
	Returns category type MMCIF_Struct.
void	Optimize ()
	Optimizes structure 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 in mmCIF file. If a structure is created programmatically, the order of tags in mmCIF file will be the same as order of adding them to the structure.
pstr	GetField (int tagNo)
	Returns value of field corresponding to tag in the specified position. Tag positions are defined by the order of their appearance in mmCIF file (if structure was read from a file), or by the order of their addition to the structure (if structure was created programmatically). Tags are numbered as 0...GetNofTags()-1.
int	GetString (pstr &S, cpstr TName, bool Remove=false)
	Fetches value, corresponding to the given tag, as a string.
pstr	GetString (cpstr TName, int &RC)
	Returns pointer to value associated with given tag.
int	DeleteField (cpstr TName)
	Deletes field associated with given tag.
int	GetReal (realtype &R, cpstr TName, bool Remove=false)
	Fetches value, corresponding to the given tag, as a real number.
int	GetInteger (int &I, cpstr TName, bool Remove=false)
	Fetches value, corresponding to the given tag, as an integer number.
void	PutString (cpstr S, cpstr TName, bool NonBlankOnly=false)
	Sets string value for given tag.
void	PutDate (cpstr T)
	Sets current date in format YYYY-MM-DD as a value for given tag.
void	PutNoData (int NoDataType, cpstr T)
	Sets "data not given" or "data not available" values for given tag.
void	PutReal (realtype R, cpstr TName, int prec=8)
	Sets float-point value for given tag.
void	PutReal (realtype R, cpstr TName, cpstr format)
	Sets float-point value for given tag.
void	PutInteger (int I, cpstr TName)
	Sets integer value for given tag.
bool	WriteMMCIFStruct (cpstr FName, io::GZ_MODE gzipMode=io::GZM_CHECK)
	Writes structure data in mmCIF format into file.
void	WriteMMCIF (io::RFile f)
	Writes structure into given file.
void	Copy (PCategory Struct)
	Deep copy of structures. 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	InitStruct ()
void	FreeMemory ()
Protected Attributes
psvector	field

---

Detailed Description

mmcif::Struct represents mmCIF's "structure" category, where data follows directly the corresponding tag.

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

    _structure_name.tag0   value0
    _structure_name.tag1   value1
    ...........
    _structure_name.tagN   valueN

mmcif::Struct represents this construct by keeping category name ("_structure_name") and associated lists of tags ("tag0,tag1...tagN") and their values ("value0,value1...valueN").

The structure 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. 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.

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::Struct::Struct

(

)

Basic constructor.

mmdb::mmcif::Struct::Struct

(

cpstr

N )

Constructor that assigns structure name.

Parameters:

[in]

N

structure name (must start with underscore).

mmdb::mmcif::Struct::Struct

(

io::RPStream

Object )

Constructor for MMDB data streaming functions.

mmdb::mmcif::Struct::~Struct

(

)

Destructor.

---

Member Function Documentation

void mmdb::mmcif::Struct::AddField	(	cpstr	F,
		cpstr	T,
		bool	Concatenate = false
	)

Adds field to the structure.

Parameters:

[in]	F	field value
[in]	T	tag name
[in]	Concatenate	flag to concatenate existing field with the value of F. If tag T is already in the structure and Concatenate=true, then value of F is appended to the existing field. Otherwise, the field is replaced with the value of F

void mmdb::mmcif::Struct::Copy

(

PCategory

Struct )

[virtual]

Deep copy of structures. 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]

Struct

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

Reimplemented from mmdb::mmcif::Category.

int mmdb::mmcif::Struct::DeleteField

(

cpstr

TName )

Deletes field associated with given tag.

Parameters:

[in]

TName

character string with tag name

Returns:

>=0: field deleted

<0: either field or tag is not found

void mmdb::mmcif::Struct::FreeMemory

(

)

[protected, virtual]

Reimplemented from mmdb::mmcif::Category.

MMCIF_ITEM mmdb::mmcif::Struct::GetCategoryID

(

)

[inline, virtual]

Returns category type MMCIF_Struct.

Reimplemented from mmdb::mmcif::Category.

pstr mmdb::mmcif::Struct::GetField

(

int

tagNo )

Returns value of field corresponding to tag in the specified position. Tag positions are defined by the order of their appearance in mmCIF file (if structure was read from a file), or by the order of their addition to the structure (if structure was created programmatically). Tags are numbered as 0...GetNofTags()-1.

Parameters:

[in]

tagNo

tag number (position in the structure)

Returns:

NULL: tag does 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

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

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

Parameters:

[out]	I	reference to integer number to accept the value. In case of failure, I returns zero, except when value is "data not available" or "data not given", when I returns MinInt4.
[in]	TName	character string with tag name
[in]	Remove	flag to remove the tag and its value from structure after it is read.

Returns:

• CIFRC_NoTag: tag is not found

CIFRC_NoField: field is not found

CIFRC_WrongFormat: value is not an integer number.

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

CIFRC_Ok: success.

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

Fetches value, corresponding to the given tag, 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]	Remove	flag to remove the tag and its value from structure after it is read.

Returns:

CIFRC_NoTag: tag is 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::Struct::GetString	(	pstr &	S,
		cpstr	TName,
		bool	Remove = false
	)

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

Parameters:

[out]	S	pointer to string, which will point to newly allocated character string, containing value associated with tag TName. If tag 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]	Remove	flag to remove the tag and its value from structure after it is read.

Returns:

CIFRC_NoTag: tag 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::Struct mmCIFStruct;
  pstr S;  // this is merely "char *S"
  int  rc;

    S  = NULL; // null pointer before first use
    rc = mmCIFStruct.GetString ( S,"id" );
    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 = mmCIFStruct.GetString ( S,"property" );
    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::Struct::GetString	(	cpstr	TName,
		int &	RC
	)

Returns pointer to value associated with given tag.

Parameters:

[in]	TName	character string with tag name
[out]	RC	return code: CIFRC_NoTag: tag 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 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.

void mmdb::mmcif::Struct::InitStruct

(

)

[protected]

void mmdb::mmcif::Struct::Optimize

(

)

[virtual]

Optimizes structure 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 in mmCIF file. If a structure is created programmatically, the order of tags in mmCIF file will be the same as order of adding them to the structure.

Reimplemented from mmdb::mmcif::Category.

void mmdb::mmcif::Struct::PutDate

(

cpstr

T )

Sets current date in format YYYY-MM-DD as a value for given tag.

Parameters:

[in]

T

character string with tag name. If tag is not found, it will be added to the structure.

void mmdb::mmcif::Struct::PutInteger	(	int	I,
		cpstr	TName
	)

Sets integer value for given tag.

Parameters:

[in]	I	integer number with value to be set.
[in]	TName	character string with tag name. If tag is not found, it will be added to the structure.

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

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

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 to the structure.

void mmdb::mmcif::Struct::PutReal	(	realtype	R,
		cpstr	TName,
		int	prec = 8
	)

Sets float-point value for given tag.

Parameters:

[in]	R	real number with value to be set.
[in]	TName	character string with tag name. If tag is not found, it will be added to the structure.
[in]	prec	float-point precision; g-format with given precision will be used

void mmdb::mmcif::Struct::PutReal	(	realtype	R,
		cpstr	TName,
		cpstr	format
	)

Sets float-point value for given tag.

Parameters:

[in]	R	real number with value to be set.
[in]	TName	character string with tag name. If tag is not found, it will be added to the structure.
[in]	format	format string to convert R.

void mmdb::mmcif::Struct::PutString	(	cpstr	S,
		cpstr	TName,
		bool	NonBlankOnly = false
	)

Sets string value for given tag.

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]	TName	character string with tag name. If tag is not found, it will be added to the structure.
[in]	NonBlankOnly	flag to treat white-space-only strings: false: set as is true: set "data not available" value instead.

void mmdb::mmcif::Struct::read

(

io::RFile

f )

MMDB stream reader.

Reimplemented from mmdb::mmcif::Category.

void mmdb::mmcif::Struct::write

(

io::RFile

f )

MMDB stream writer.

Reimplemented from mmdb::mmcif::Category.

void mmdb::mmcif::Struct::WriteMMCIF

(

io::RFile

f )

[virtual]

Writes structure 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::Struct::WriteMMCIFStruct	(	cpstr	FName,
		io::GZ_MODE	gzipMode = io::GZM_CHECK
	)

Writes structure 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.

---

Member Data Documentation

psvector mmdb::mmcif::Struct::field [protected]

---

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

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