File classes

The File classes provide abstraction of the IO operation, allowing for the same format to be used with on-disk files, network files, memory-mapped files, compressed files, etc.

Interface for files

class File

Abstract base class for file representation.

Subclassed by chemfiles::NcFile, chemfiles::TextFile, chemfiles::TNGFile

Public Types

enum Mode

Possible modes for opening a file.

Values:

READ = 'r'

Open in read-only mode.

WRITE = 'w'

Open in read-write mode, and replace the file if it is already present.

APPEND = 'a'

Open in read-write mode, and append new data at the end of the file.

enum Compression

Possible compression methods for opening a file.

Values:

DEFAULT

Default method: plain text or binary formats.

GZIP

gzip compression

LZMA

lzma compression (.xz)

Public Functions

const std::string &path() const

Get the file path used to open this file.

Mode mode() const

Get the mode used to open this file.

Compression compression() const

Get the compression used to open this file.

class TextFile : public chemfiles::File, public iostream

Abstract base class representing a text file. This class is inteded to be inherited by any form of text files: compressed files, memory-mapped files, etc.

All failling operations should throw a FileError instead of waiting for the user of the class to the current state.

Subclassed by chemfiles::GzFile, chemfiles::PlainFile, chemfiles::XzFile

Public Functions

std::string readline()

Read a line from the file.

std::vector<std::string> readlines(size_t n)

Read n lines from the file.

void rewind()

Reset the file cursor.

bool eof()

Are we at the end of the file ?

Public Static Functions

static std::unique_ptr<TextFile> open(std::string path, File::Mode mode, File::Compression compression)

Open the file at the given path with the requested mode and compression method using the most adapted child class of TextFile.

Protected Functions

TextFile(std::string path, File::Mode mode, File::Compression compression, std::streambuf *buffer)

Initialize the TextFile at the given path and mode, with the specified ‘compression’ method. All read and write operations will go through the provided buffer.

Implemented classes

These classes implement the File interface defined previously.

class PlainFile : public chemfiles::TextFile

Simple TextFile implementation, only a thin wrapper on top of standard C++ fstreams. Reads plain, uncompressed files

Public Functions

PlainFile(std::string path, File::Mode mode)

Open a text file with name filename and mode mode.

class GzFile : public chemfiles::TextFile

A gziped text file.

Public Functions

GzFile(std::string path, File::Mode mode)

Open the file at the given path using the specified mode

class XzFile : public chemfiles::TextFile

A xz-compressed text file.

Public Functions

XzFile(std::string path, File::Mode mode)

Open the file at the given path using the specified mode

class NcFile : public chemfiles::File

RAII wrapper around NetCDF 3 binary files

This interface only provide basic functionalities needed by the Amber NetCDF format. All the operation are guaranteed to return a valid value or throw an error.

The template functions are manually specialized for float and char data types.

Public Types

enum NcMode

Possible file mode. By default, files are in the DATA mode.

Values:

DEFINE

Files in DEFINE mode can have there attributes, dimmensions and variables modified, but no data can be read or written using NcVariable.

DATA

Files in data mode acces read and write access to NcVariables.

Public Functions

void set_nc_mode(NcMode mode)

Set the file mode for this file.

NcMode nc_mode() const

Get the file mode for this file.

nc::netcdf_id_t netcdf_id() const

Get the NetCDF id of this file.

std::string global_attribute(const std::string &name) const

Get a global string attribut from the file.

void add_global_attribute(const std::string &name, const std::string &value)

Create a global attribut in the file_.

size_t dimension(const std::string &name) const

Get the value of a specific dimmension.

size_t optional_dimension(const std::string &name, size_t value) const

Get the value of an optional dimmension, or the default value if the dimmension is not in the file

void add_dimension(const std::string &name, size_t value = NC_UNLIMITED)

Create a dimmension with the specified value. If value == NC_UNLIMITED, then the dimension is infinite.

bool variable_exists(const std::string &name) const

Check if a variable exists.

template<typename NcType>
NcType variable(const std::string &name)

Get a NetCDF variable.

template<typename NcType, typename ...Dims>
NcType add_variable(const std::string &name, Dims... dims)

Create a new variable of type NcType with name name along the dimensions in dims. dims must be string or string-like values.

class TNGFile : public chemfiles::File

Simple RAII capsule for tng_trajectory_t, handling the creation and destruction of the file as needed.