mmcif::Category is a base class for mmcif::Struct and mmcif::Loop, implementations of mmCIF's "structure" and "loop" categories. More...

#include <mmdb_mmcif_.h>

Inheritance diagram for mmdb::mmcif::Category:

[legend]

List of all members.

Public Member Functions
	Category ()
	Basic constructor.
	Category (cpstr N)
	Constructor that assigns category name.
	Category (io::RPStream Object)
	Constructor for MMDB data streaming functions.
	~Category ()
	Destructor.
pstr	GetCategoryName ()
	Returns category name.
void	SetCategoryName (cpstr N)
	Sets category name.
virtual MMCIF_ITEM	GetCategoryID ()
	Returns category type. This function may be used when retrieving categories (structures and loops) from data blocks (mmcif::Data).
virtual void	WriteMMCIF (io::RFile)
	Virtual function for writing category's content into mmCIF file. Default implementation does nothing.
virtual void	Optimize ()
	Virtual function for optimizig data structures. 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 category 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 category is created programmatically, the order of tags in mmCIF file will be the same as order of adding them to the category.
void	Sort ()
	Sorts category's data for quicker access. The sorting is essentially re-indexing of data for quicker access. It does not change the order of data in both mmCIF hierarchy and mmCIF file. E.g., if tag "serial_no" was 2nd one in given category before sorting, it will remain on 2nd place after it, therefore no change in tag number passed to functions in mmcif::Struct, mmcif::Loop and mmcif::Data.
int	GetTagNo (cpstr ttag)
	Returns serial number of a tag in the category.
int	AddTag (cpstr ttag)
	Adds a tag to the category. Adding a tag in mmcif::Category does not reserve any placeholder for the corresponding value. All tags get automatically sorted (reindexed) for quicker access. Tags will appear in mmCIF file in order of their addition to the category.
int	GetNofTags ()
	Returns the total number of tags in the category.
pstr	GetTag (int tagNo)
	Returns tag with the specified serial number. The tags are enumerated as 0..GetNofTags()-1.
void	PrintTags ()
	Prints list of tags to stdout. Both sorted and unsorted tags are printed to standard output. This function may be used for debugging.
bool	CheckTags (cpstr *tagList)
	Returns true if all tags from the list are found in the category. The size of the list of tags may be less than the number of tags in the category, and order of tags is disregarded.
virtual void	Copy (PCategory Category)
	Deep copy of categories. 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	InitCategory ()
virtual void	FreeMemory ()
void	ExpandTags (int nTagsNew)
void	PutCategoryName (cpstr newName)
Protected Attributes
int	nTags
pstr	name
psvector	tag
ivector	index
int	nAllocTags
Friends
class	Data

Detailed Description

mmcif::Category is a base class for mmcif::Struct and mmcif::Loop, implementations of mmCIF's "structure" and "loop" categories.

This class is not instantiated independently in any applications, however, it provides a few public functions which work for both mmcif::Struct and mmcif::Loop.

All data in mmCIF hierarchy is addressed using construct "category.tag" plus row number (>=0) for loops. Category names should always start from underscore, while tags normally start with a letter, e.g. "_barrel.id".

See general principles of working with mmCIF files and mmCIF hierarchies in Section "mmcif_handler".

Constructor & Destructor Documentation

mmdb::mmcif::Category::Category ( )

Basic constructor.

mmdb::mmcif::Category::Category ( cpstr N )

Constructor that assigns category name.

Parameters:

[in] N category name (must start with underscore).

mmdb::mmcif::Category::Category ( io::RPStream Object )

Constructor for MMDB data streaming functions.

mmdb::mmcif::Category::~Category ( )

Destructor.

Member Function Documentation

int mmdb::mmcif::Category::AddTag ( cpstr ttag )

Adds a tag to the category. Adding a tag in mmcif::Category does not reserve any placeholder for the corresponding value. All tags get automatically sorted (reindexed) for quicker access. Tags will appear in mmCIF file in order of their addition to the category.

Parameters:

[in] ttag tag to be added.

Returns:: >=0 the tag is already in the category, and return is its serial number. No changes to the category is done; <0 the tag was added to the list of tags, and return is minus total number of tags in the category.

bool mmdb::mmcif::Category::CheckTags ( cpstr * tagList )

Returns true if all tags from the list are found in the category. The size of the list of tags may be less than the number of tags in the category, and order of tags is disregarded.

Parameters:

[in] tagList list of tags to be checked for presence in the category. The list must end with NULL pointer, or your program will crash.

Returns:: true if all tags from the list were found in the category; false if one or more tags from the list were not found in the category.

Example:

  cpstr tagList[] = {"id","type","date",NULL};
  mmcif::Struct cifStruct;
  if (cifStruct.CheckTags(tagList))
    printf ( " all tags are found in category %s\n",
             cifStruct.GetCategoryName() );

This function is useful for finding categories in "dirty cifs", where category name is not given.

void mmdb::mmcif::Category::Copy ( PCategory Category ) [virtual]

Deep copy of categories. 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] Category a pointer to mmcif::Category, the content of which is copied into 'this' category.

Reimplemented in mmdb::mmcif::Struct, and mmdb::mmcif::Loop.

void mmdb::mmcif::Category::ExpandTags ( int nTagsNew ) [protected]

void mmdb::mmcif::Category::FreeMemory ( ) [protected, virtual]

Reimplemented in mmdb::mmcif::Struct, and mmdb::mmcif::Loop.

virtual MMCIF_ITEM mmdb::mmcif::Category::GetCategoryID ( ) [inline, virtual]

Returns category type. This function may be used when retrieving categories (structures and loops) from data blocks (mmcif::Data).

Returns:: MMCIF_Category for mmcif::Category; MMCIF_Struct for mmcif::Struct; MMCIF_Loop for mmcif::Loop

Reimplemented in mmdb::mmcif::Struct, and mmdb::mmcif::Loop.

pstr mmdb::mmcif::Category::GetCategoryName ( ) [inline]

Returns category name.

Returns:: NULL if name was not set; pointer to character string if name was set

int mmdb::mmcif::Category::GetNofTags ( ) [inline]

Returns the total number of tags in the category.

pstr mmdb::mmcif::Category::GetTag ( int tagNo )

Returns tag with the specified serial number. The tags are enumerated as 0..GetNofTags()-1.

Parameters:

tagNo tag's serial number

Returns:: NULL: tagNo is outside the range of 0..GetNofTags()-1; not NULL: tag in tagNo'th position

int mmdb::mmcif::Category::GetTagNo ( cpstr ttag )

Returns serial number of a tag in the category.

Parameters:

[in] ttag tag (or name of a field in category)

Returns:: >=0 : the tag is in given position; <0 : the tag was not found, but it could be inserted before tag with (-rc-1)th index, where 'rc' is the return.

void mmdb::mmcif::Category::InitCategory ( ) [protected]

void mmdb::mmcif::Category::Optimize ( ) [virtual]

Virtual function for optimizig data structures. 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 category 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 category is created programmatically, the order of tags in mmCIF file will be the same as order of adding them to the category.

Reimplemented in mmdb::mmcif::Struct, and mmdb::mmcif::Loop.

void mmdb::mmcif::Category::PrintTags ( )

Prints list of tags to stdout. Both sorted and unsorted tags are printed to standard output. This function may be used for debugging.

void mmdb::mmcif::Category::PutCategoryName ( cpstr newName ) [protected]

void mmdb::mmcif::Category::read ( io::RFile f )

MMDB stream reader.

Reimplemented in mmdb::mmcif::Struct, and mmdb::mmcif::Loop.

void mmdb::mmcif::Category::SetCategoryName ( cpstr N )

Sets category name.

Parameters:

N	new category name

void mmdb::mmcif::Category::Sort ( )

Sorts category's data for quicker access. The sorting is essentially re-indexing of data for quicker access. It does not change the order of data in both mmCIF hierarchy and mmCIF file. E.g., if tag "serial_no" was 2nd one in given category before sorting, it will remain on 2nd place after it, therefore no change in tag number passed to functions in mmcif::Struct, mmcif::Loop and mmcif::Data.

void mmdb::mmcif::Category::write ( io::RFile f )

MMDB stream writer.

Reimplemented in mmdb::mmcif::Struct, and mmdb::mmcif::Loop.

virtual void mmdb::mmcif::Category::WriteMMCIF ( io::RFile ) [inline, virtual]

Virtual function for writing category's content into mmCIF file. Default implementation does nothing.

Reimplemented in mmdb::mmcif::Struct, and mmdb::mmcif::Loop.