Avogadro::Io::FileFormat

class FileFormat

General API for file formats.

This serves as the common base class for chemical file formats. Classes deriving from this one override the read and write virtual methods and operate on the given streams. Several other signatures are available for convenience. If there is an error reading or writing a file the string returned by error() will give more details.

Author

Marcus D. Hanwell

Subclassed by CjsonFormat, CmlFormat, DcdFormat, GromacsFormat, LammpsDataFormat, LammpsTrajectoryFormat, MMTFFormat, MdlFormat, OutcarFormat, PdbFormat, PoscarFormat, TrrFormat, TurbomoleFormat, XyzFormat, GAMESSUSOutput, GaussianCube, GaussianFchk, GenericOutput, MoldenFile, MopacAux, NWChemJson, NWChemLog, ORCAOutput

Public Types

enum Operation

Flags defining supported operations.

Values:

enumerator None

enumerator Read

enumerator Write

enumerator ReadWrite

enumerator MultiMolecule

enumerator Stream

enumerator String

enumerator File

enumerator All

using Operations = int

Public Functions

FileFormat()

virtual ~FileFormat()

virtual Operations supportedOperations() const = 0

Returns:

Operation flags defining the capabilities of this format.

bool open(const std::string &fileName, Operation mode)

Open the specified file in Read or Write mode.

Returns:

True on success, false on failure.

inline Operation mode()

The mode the format is currently operating in.

Returns:

The mode the format is in.

inline bool isMode(Operation isInMode)

Check if the supplied mode(s) is being used.

Parameters:

isInMode – The mode(s) to test against

Returns:

True if the format is currently in the supplied mode(s).

void close()

Close any opened file handles.

bool readMolecule(Core::Molecule &molecule)

Read in a molecule, if there are no molecules to read molecule will be empty. This can be used to read in one or more molecules from a given file using repeated calls for each molecule.

Parameters:

molecule – The molecule the data will be read into.

Returns:

True on success, false on failure.

bool writeMolecule(const Core::Molecule &molecule)

Write out a molecule. This can be used to write one or more molecules to a given file using repeated calls for each molecule.

Parameters:

molecule – The molecule the data will be written from.

Returns:

True on success, false on failure.

virtual bool read(std::istream &in, Core::Molecule &molecule) = 0

Read the given in stream and load it into molecule.

Parameters:

• in – The input file stream.

• molecule – The molecule the data will be read into.

Returns:

True on success, false on failure.

virtual bool write(std::ostream &out, const Core::Molecule &molecule) = 0

Write to the given out stream the contents of molecule.

Parameters:

• out – The output stream to write the data to.

• molecule – The contents of this molecule will be written to output.

Returns:

True on success, false on failure.

bool readFile(const std::string &fileName, Core::Molecule &molecule)

Read the given fileName and load it into molecule.

Parameters:

• fileName – The full path to the file to be read in.

• molecule – The molecule the data will be read into.

Returns:

True on success, false on failure.

bool writeFile(const std::string &fileName, const Core::Molecule &molecule)

Write to the given fileName the contents of molecule.

Parameters:

• fileName – The full path to the file to be written.

• molecule – The contents of this molecule will be written to the file.

Returns:

True on success, false on failure.

bool readString(const std::string &string, Core::Molecule &molecule)

Read the given string and load it into molecule.

Parameters:

• string – The string containing the molecule file contents.

• molecule – The molecule the data will be read into.

Returns:

True on success, false on failure.

bool writeString(std::string &string, const Core::Molecule &molecule)

Write to the given string the contents of molecule.

Parameters:

• string – The string to write the contents of the molecule into.

• molecule – The contents of this molecule will be written to the string.

Returns:

True on success, false on failure.

inline std::string error() const

Get the error string, contains errors/warnings encountered.

Returns:

String containing any errors or warnings encountered.

inline std::string fileName() const

Get the file name (if known).

Returns:

The full path to the file name as supplied, can be empty.

inline void setOptions(const std::string &options)

Set options for the file reader.

Parameters:

options – The options, each reader chooses how to use/interpret them.

inline std::string options() const

Get the file format options, can be used to change file IO.

Returns:

The options set for the reader (defaults to empty).

virtual void clear()

Clear the format and reset all state.

virtual FileFormat *newInstance() const = 0

Create a new instance of the file format class. Ownership passes to the caller.

virtual std::string identifier() const = 0

A unique identifier, used to retrieve formats programmatically. CML, XYZ, PDB etc. A runtime warning will be generated if the identifier is not unique.

virtual std::string name() const = 0

The name of the format, should be short such as Chemical Markup Language, XYZ format, Protein Databank etc.

virtual std::string description() const = 0

A description of the format, along with any relevant help text for users.

virtual std::string specificationUrl() const = 0

The URL of the format specification if available (relevant web page/wiki otherwise).

virtual std::vector<std::string> fileExtensions() const = 0

Get the file name extension(s) that the format supports reading.

Returns:

A vector containing a list of extensions (in lower case).

virtual std::vector<std::string> mimeTypes() const = 0

Get the MIME type(s) that the format supports reading.

Returns:

A vector containing a list of MIME type(s) (in lower case).

Public Static Functions

static bool validateFileName(const std::string &fileName)

Validates the given file name.

Checks if the filename contains any invalid characters (e.g. ..) Also checks if the filename contains a restricted name on Windows. e.g., CON, PRN, AUX, NUL, COM1, COM2, COM3, COM4, COM5, etc.

Parameters:

fileName – The name of the file to be validated.

Returns:

true if the file name is valid, false otherwise.

Protected Functions

void appendError(const std::string &errorString, bool newLine = true)

Append an error to the error string for the format.

Parameters:

• errorString – The error to be added.

• newLine – Add a new line after the error string?