`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 chemfiles::File¶

Abstract base class for file representation.

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

Public Types

enum Mode¶

Possible modes for opening a file.

Values:

enumerator READ¶: Open in read-only mode.

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

enumerator APPEND¶: 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:

enumerator DEFAULT¶: Default method: plain text or binary formats.

enumerator GZIP¶: gzip compression

enumerator BZIP2¶: bzip2 compression

enumerator 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 chemfiles::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 \n or \r\n) 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

TextFile(std::shared_ptr<MemoryBuffer> memory, File::Mode mode, File::Compression compression)¶

Use the given MemoryBuffer with the requested mode and compression method. A MemoryFile will be used as the TextFileImpl.

Exceptions

FileError: if the file mode is append, or if trying to write to a compressed file.

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 chemfiles::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) override¶

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

FileError: in case of I/O error

void write(const char *data, size_t count) override¶

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() noexcept override¶: clear error and eof flags on the file

void seek(uint64_t position) override¶

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

Exceptions

FileError: in case of I/O error while seeking

class chemfiles::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) override¶

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

FileError: in case of I/O error

void write(const char *data, size_t count) override¶

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() noexcept override¶: clear error and eof flags on the file

void seek(uint64_t position) override¶

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

Exceptions

FileError: in case of I/O error while seeking

class chemfiles::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) override¶

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

FileError: in case of I/O error

void write(const char *data, size_t count) override¶

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() noexcept override¶: clear error and eof flags on the file

void seek(uint64_t position) override¶

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

Exceptions

FileError: in case of I/O error while seeking

class chemfiles::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:

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

enumerator 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 attribute from the file.

void add_global_attribute(const std::string &name, const std::string &value)¶: Create a global attribute 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.

class chemfiles::XDRFile : public chemfiles::File ¶

Simple RAII capsule for XDRFILE*, handling the creation and destruction of the file as needed. Reads the file header and stores the offsets for individual frames.

Public Types

enum Variants¶

Possible variants of the XDR file.

Values:

enumerator XTC¶: XTC trajectory.

enumerator TRR¶: TRR trajectory.

Public Functions

unsigned long nframes() const¶: get the number of frames/steps in the file, as indicated in the file header

int64_t offset(size_t step) const¶: get the offset corresponding to a specific frame/step

int natoms() const¶: get the number of atoms, as indicated in the file header

void set_natoms(int natoms)¶: set the number of atoms

File classes¶

Interface for files¶

Implemented classes¶

`File` classes¶