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, chemfiles::XDRFile

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

BZIP2

bzip2 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

Line-oriented text file reader and writer, using buffered read and fast lines search.

This class reads text file line by line. It does so in a efficient way by storing a chunk of the file in a memory buffer, and searching for new line indicators (either ‘

’ or ‘

’) in this buffer. It then returns

string_view inside this buffer, removing the need to allocate a new std::string for each line.

Writing to the files is done without buffering or considering lines.

Public Functions

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

Open the file at the given path with the requested mode and compression method, picking the best TextFileImpl.

Exceptions

  • FileError: if the file does not exist in read mode, or if the file is invalid for the given compression method

uint64_t tellpos() const

Returns the current position indicator, i.e. the number of characters from the beginning of the file.

void seekpos(uint64_t position)

Set the position indicator to position.

void rewind()

Reset the position indicator to the beginning of the file, and clear end-of-file flag.

bool eof() const

Check if end-of-file has been reached.

void clear()

Clear end-of-file flags on the file.

string_view readline()

Read a single line from the file. The returned string_view points into an internal buffer, and can be invalidated after another call to readline. If storing the line is necessary, transform it to an owned string using string_view::to_string().

std::string readall()

Read the full file into an owned string. This is a convenience method for format that need the full file read before parsing can start.

template<typename Str, typename ...Args>
void print(const Str &format, const Args&... args)

Format and write some data to the file using the fmt library.

This function has the same interface as fmt::print(...), writting data to the file instead of stdout.

Implemented classes

These classes implement the File interface defined previously.

class PlainFile : public chemfiles::TextFileImpl

Simple TextFileImpl reading plain, uncompressed files using FILE*.

Public Functions

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

Open a text file with name filename and mode mode.

size_t read(char *data, size_t count)

Fill up the data buffer reading at most count characters from the file.

Returns the amount of characters read. A return value of 0 indicates that the end of file has been reached.

Exceptions

void write(const char *data, size_t count)

Write count characters starting at data to the file.

Exceptions

  • FileError: if it could not write all of the data to the file

void clear()

clear error and eof flags on the file

void seek(uint64_t position)

Set file indicator to position characters after the start of the file.

Exceptions

  • FileError: in case of I/O error while seeking

class GzFile : public chemfiles::TextFileImpl

An implementation of TextFile for gzip files.

Public Functions

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

Open a text file with name filename and mode mode.

size_t read(char *data, size_t count)

Fill up the data buffer reading at most count characters from the file.

Returns the amount of characters read. A return value of 0 indicates that the end of file has been reached.

Exceptions

void write(const char *data, size_t count)

Write count characters starting at data to the file.

Exceptions

  • FileError: if it could not write all of the data to the file

void clear()

clear error and eof flags on the file

void seek(uint64_t position)

Set file indicator to position characters after the start of the file.

Exceptions

  • FileError: in case of I/O error while seeking

class XzFile : public chemfiles::TextFileImpl

An implementation of TextFile for lzma/xz files.

Public Functions

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

Open a text file with name filename and mode mode.

size_t read(char *data, size_t count)

Fill up the data buffer reading at most count characters from the file.

Returns the amount of characters read. A return value of 0 indicates that the end of file has been reached.

Exceptions

void write(const char *data, size_t count)

Write count characters starting at data to the file.

Exceptions

  • FileError: if it could not write all of the data to the file

void clear()

clear error and eof flags on the file

void seek(uint64_t position)

Set file indicator to position characters after the start of the file.

Exceptions

  • FileError: in case of I/O error while seeking

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.