GenericMolFile Class Reference
[Molecular structure file formats]

Base class for all molecule file format classes. More...

#include <genericMolFile.h>

Inheritance diagram for GenericMolFile:

List of all members.

Public Member Functions
Constructors and Destructors
	GenericMolFile () throw ()
	Default constructor.
	GenericMolFile (const String &filename, File::OpenMode open_mode=std::ios::in) throw (Exception::FileNotFound)
	Detailed constructor.
	GenericMolFile (const GenericMolFile &file) throw (Exception::FileNotFound)
	Copy constructor.
virtual	~GenericMolFile () throw ()
	Destructor.
Assignment
const GenericMolFile &	operator= (const GenericMolFile &rhs) throw (Exception::FileNotFound)
	Assignment operator.
Reading and Writing of Kernel Datastructures
virtual bool	write (const System &system) throw (File::CannotWrite)
	Write the molecules of a system.
virtual bool	write (const Molecule &molecule) throw (File::CannotWrite)
	Write a molecule.
virtual bool	read (System &system) throw (Exception::ParseError)
	Read a system.
virtual Molecule *	read () throw (Exception::ParseError)
	Read a molecule.
Operators
virtual GenericMolFile &	operator>> (System &system) throw (Exception::ParseError)
	Stream operator for reading a system.
virtual GenericMolFile &	operator<< (const System &system) throw (File::CannotWrite)
	Stream operator for writing a system of molecules.
virtual GenericMolFile &	operator>> (Molecule &molecule) throw (Exception::ParseError)
	Stream operator for reading a molecule.
virtual GenericMolFile &	operator<< (const Molecule &molecule) throw (File::CannotWrite)
	Stream operator for writing a system of molecules.
Protected Member Functions
virtual void	initRead_ ()
	Initialize internals for read.
virtual void	initWrite_ ()
	Initialize internals for write.

---

Detailed Description

Base class for all molecule file format classes.

This class provides an interface for all molecular structure formats (except for PDB files, due to their complex and capricious structure and contents).

GenericMolFile supports two type of operations: reading/writing single molecules and reading/writing systems (i.e. collections of molecules).

When reading molecules, the structures are read one at a time from the file in the order they are stored. In contrast, reading systems retrieves all structures contained in the file. For file formats that do not support multiple structure in a file (e.g. the MDL MOLFile ), those two operations are basically equivalent. A fundamental difference however is the fact that reading a molecule create a new molecule, whereas reading a system adds the molecules read to an existing instance of System . This implies that the system has to be cleared prior to reading a system if that incremental behaviour is not desired.

The user interface of the class is mainly provided through the stream operator. A typical example for reading a structure from a HyperChem file might look as follows:

{verbatim} HINFile hinfile(filename); System S; hinfile >> S; {verbatim} This interface applies to all derived classes as well, so that file formats can be exchanged conveniently.

GenericMolFile is derived from LineBasedFile since most molecular structure formats are line-based tagged formats, often containing Fortran-style formatted sections. LineBasedFile provides a number of convenient methods to parse that kind of format.

---

Member Function Documentation

virtual void GenericMolFile::initRead_ (   )  [protected, virtual]

Initialize internals for read. This method is called by the default implementation of read(System& system) . Its purpose is the initialization of internal members holding, for example, header information from the file. The default implementation provided is empty. Reimplemented in GAMESSDatFile, GAMESSLogFile, and HINFile.

virtual void GenericMolFile::initWrite_ (   )  [protected, virtual]

Initialize internals for write. Same functionality as initRead , but is called prior to writing a system.

virtual GenericMolFile& GenericMolFile::operator<< (  const Molecule &  molecule  )  throw (File::CannotWrite) [virtual]

Stream operator for writing a system of molecules. Calls write() Reimplemented in PDBFile.

virtual GenericMolFile& GenericMolFile::operator<< (  const System &  system  )  throw (File::CannotWrite) [virtual]

Stream operator for writing a system of molecules. Calls write(const System& system) const . Reimplemented in PDBFile.

const GenericMolFile& GenericMolFile::operator= (  const GenericMolFile &  rhs  )  throw (Exception::FileNotFound)

Assignment operator. Create a new object pointing to the same filename.

virtual GenericMolFile& GenericMolFile::operator>> (  Molecule &  molecule  )  throw (Exception::ParseError) [virtual]

Stream operator for reading a molecule. Calls read() Reimplemented in PDBFile.

virtual GenericMolFile& GenericMolFile::operator>> (  System &  system  )  throw (Exception::ParseError) [virtual]

Stream operator for reading a system. Calls read(System&) . Reimplemented in PDBFile.

virtual Molecule* GenericMolFile::read (   )  throw (Exception::ParseError) [virtual]

Read a molecule. This method will load the first (or the next, on subsequent invocation) molecule from the file. If the file format does not support multiple molecules, only the first call to read will be successful. This method will create an instance of molecule and its the user's responsibility to destroy that molecule. Returns: a pointer to a molecule, 0 if the file was not open, empty, or at its end Exceptions: Exception::ParseError  if the contents of the file could not be parsed Reimplemented in GAMESSDatFile, GAMESSLogFile, HINFile, KCFFile, MOL2File, MOLFile, and SDFile.

virtual bool GenericMolFile::read (  System &  system  )  throw (Exception::ParseError) [virtual]

Read a system. This method will read all molecules contained in the file and add them to the system. The default implementation calls read() until false is returned and adds the molecules read to the system. Returns: true if anything could be read Exceptions: Exception::ParseError  if the file could not be parsed while reading a molecule Reimplemented in GAMESSDatFile, GAMESSLogFile, HINFile, KCFFile, MOL2File, MOLFile, PDBFile, and SDFile.

virtual bool GenericMolFile::write (  const Molecule &  molecule  )  throw (File::CannotWrite) [virtual]

Write a molecule. Repeated invocations of this method append molecules to the same file. The default implementation does nothing. Reimplemented in GAMESSDatFile, GAMESSLogFile, HINFile, KCFFile, MOL2File, MOLFile, PDBFile, and SDFile.

virtual bool GenericMolFile::write (  const System &  system  )  throw (File::CannotWrite) [virtual]

Write the molecules of a system. If the file format does not support multiple molecules in a single file, a warning should be printed and only the first molecule should be stored. The default implementation iterates over the system and calls write(const Molecule& molecule) for each molecule. Reimplemented in GAMESSDatFile, GAMESSLogFile, HINFile, KCFFile, MOL2File, MOLFile, and SDFile.