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.

class File

Abstract base class for file representation.

Subclassed by chemfiles::BinaryFile, chemfiles::TextFile, chemfiles::TNGFile

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

inline const std::string &path() const

Get the file path used to open this file.

inline Mode mode() const

Get the mode used to open this file.

inline 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 \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.

This class can read compressed data or in-memory data by using one of the TextFileImpl interface implementation.

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.

Throws:

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.

Throws:

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.

inline bool eof() const

Check if end-of-file has been reached.

void clear()

Clear end-of-file flags on the file.

std::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>
inline 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.

class BinaryFile : public chemfiles::File

A BinaryFile provides facilities to read/write a few primitive types from/to binary (i.e. non text) files.

Depending on the file endianness, you should use one of the two subclasses of this file: BigEndianFile or LittleEndianFile. All the functions convert from/to the native endianess to the file endianess.

Subclassed by chemfiles::BigEndianFile, chemfiles::LittleEndianFile

Public Functions

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

Open the file at the given path using the given mode

uint64_t tell() const

Get the current position in the file.

void seek(uint64_t position)

Seek to the specified position in the file.

void skip(uint64_t count)

Skip the next count Bytes in the file.

uint64_t file_size()

Get the size of the file.

void read_char(char *data, size_t count)

Read exactly count char, and store them in the data array.

inline void read_char(std::vector<char> &data)

Read exactly as many char as fit in the pre-allocated vector.

inline char read_single_char()

Read a single char value from the file.

inline void read_i8(int8_t *data, size_t count)

Read exactly count 8-bit signed integers, and store them in the data array

inline void read_i8(std::vector<int8_t> &data)

Read exactly as many 8-bit signed integers as fit in the pre-allocated vector.

inline int8_t read_single_i8()

Read a single 8-bit signed integer from the file.

inline void read_u8(uint8_t *data, size_t count)

Read exactly count 8-bit unsigned integers, and store them in the data array

inline void read_u8(std::vector<uint8_t> &data)

Read exactly as many 8-bit unsigned integers as fit in the pre-allocated vector.

inline uint8_t read_single_u8()

Read a single 8-bit unsigned integer from the file.

virtual void read_i16(int16_t *data, size_t count) = 0

Read exactly count 16-bit signed integers, and store them in the data array

inline void read_i16(std::vector<int16_t> &data)

Read exactly as many 16-bit signed integers as fit in the pre-allocated vector.

inline int16_t read_single_i16()

Read a single 16-bit signed integer from the file.

virtual void read_u16(uint16_t *data, size_t count) = 0

Read exactly count 16-bit unsigned integers, and store them in the data array

inline void read_u16(std::vector<uint16_t> &data)

Read exactly as many 16-bit unsigned integers as fit in the pre-allocated vector.

inline uint16_t read_single_u16()

Read a single 16-bit unsigned integer from the file.

virtual void read_i32(int32_t *data, size_t count) = 0

Read exactly count 32-bit signed integers, and store them in the data array

inline void read_i32(std::vector<int32_t> &data)

Read exactly as many 32-bit signed integers as fit in the pre-allocated vector.

inline int32_t read_single_i32()

Read a single 32-bit signed integer from the file.

virtual void read_u32(uint32_t *data, size_t count) = 0

Read exactly count 32-bit unsigned integers, and store them in the data array

inline void read_u32(std::vector<uint32_t> &data)

Read exactly as many 32-bit unsigned integers as fit in the pre-allocated vector.

inline uint32_t read_single_u32()

Read a single 32-bit unsigned integer from the file.

virtual void read_i64(int64_t *data, size_t count) = 0

Read exactly count 64-bit signed integers, and store them in the data array

inline void read_i64(std::vector<int64_t> &data)

Read exactly as many 64-bit signed integers as fit in the pre-allocated vector.

inline int64_t read_single_i64()

Read a single 64-bit signed integer from the file.

virtual void read_u64(uint64_t *data, size_t count) = 0

Read exactly count 64-bit unsigned integers, and store them in the data array

inline void read_u64(std::vector<uint64_t> &data)

Read exactly as many 64-bit unsigned integers as fit in the pre-allocated vector.

inline uint64_t read_single_u64()

Read a single 64-bit unsigned integer from the file.

virtual void read_f32(float *data, size_t count) = 0

Read exactly count 32-bit floating point numbers, and store them in the data array

inline void read_f32(std::vector<float> &data)

Read exactly as many 32-bit floating point numbers as fit in the pre-allocated vector.

inline float read_single_f32()

Read a single 32-bit floating point number from the file.

virtual void read_f64(double *data, size_t count) = 0

Read exactly count 64-bit floating point numbers, and store them in the data array

inline void read_f64(std::vector<double> &data)

Read exactly as many 64-bit floating point numbers as fit in the pre-allocated vector.

inline double read_single_f64()

Read a single 64-bit floating point number from the file.

void write_char(const char *data, size_t count)

Write exactly count char values taken from the data array to the file

inline void write_char(const std::vector<char> data)

Write all char from the pre-allocated vector.

inline void write_single_char(char value)

Write a single char value to the file.

inline void write_i8(const int8_t *data, size_t count)

Write exactly count 8-bit signed integers taken from the data array to the file

inline void write_i8(const std::vector<int8_t> data)

Write all 8-bit signed integers from the pre-allocated vector.

inline void write_single_i8(int8_t value)

Write a single 8-bit signed integer to the file.

inline void write_u8(const uint8_t *data, size_t count)

Write exactly count 8-bit unsigned integers taken from the data array to the file

inline void write_u8(const std::vector<uint8_t> data)

Write all 8-bit unsigned integers from the pre-allocated vector.

inline void write_single_u8(uint8_t value)

Write a single 8-bit unsigned integer to the file.

virtual void write_i16(const int16_t *data, size_t count) = 0

Write exactly count 16-bit signed integers taken from the data array to the file

inline void write_i16(const std::vector<int16_t> data)

Write all 16-bit signed integers from the pre-allocated vector.

inline void write_single_i16(int16_t value)

Write a single 16-bit signed integer to the file.

virtual void write_u16(const uint16_t *data, size_t count) = 0

Write exactly count 16-bit unsigned integers taken from the data array to the file

inline void write_u16(const std::vector<uint16_t> data)

Write all 16-bit unsigned integers from the pre-allocated vector.

inline void write_single_u16(uint16_t value)

Write a single 16-bit unsigned integer to the file.

virtual void write_i32(const int32_t *data, size_t count) = 0

Write exactly count 32-bit signed integers taken from the data array to the file

inline void write_i32(const std::vector<int32_t> data)

Write all 32-bit signed integers from the pre-allocated vector.

inline void write_single_i32(int32_t value)

Write a single 32-bit signed integer to the file.

virtual void write_u32(const uint32_t *data, size_t count) = 0

Write exactly count 32-bit unsigned integers taken from the data array to the file

inline void write_u32(const std::vector<uint32_t> data)

Write all 32-bit unsigned integers from the pre-allocated vector.

inline void write_single_u32(uint32_t value)

Write a single 32-bit unsigned integer to the file.

virtual void write_i64(const int64_t *data, size_t count) = 0

Write exactly count 64-bit signed integers taken from the data array to the file

inline void write_i64(const std::vector<int64_t> data)

Write all 64-bit signed integers from the pre-allocated vector.

inline void write_single_i64(int64_t value)

Write a single 64-bit signed integer to the file.

virtual void write_u64(const uint64_t *data, size_t count) = 0

Write exactly count 64-bit unsigned integers taken from the data array to the file

inline void write_u64(const std::vector<uint64_t> data)

Write all 64-bit unsigned integers from the pre-allocated vector.

inline void write_single_u64(uint64_t value)

Write a single 64-bit unsigned integer to the file.

virtual void write_f32(const float *data, size_t count) = 0

Write exactly count 32-bit floating point numbers taken from the data array to the file

inline void write_f32(const std::vector<float> data)

Write all 32-bit floating point numbers from the pre-allocated vector.

inline void write_single_f32(float value)

Write a single 32-bit floating point number to the file.

virtual void write_f64(const double *data, size_t count) = 0

Write exactly count 64-bit floating point numbers taken from the data array to the file

inline void write_f64(const std::vector<double> data)

Write all 64-bit floating point numbers from the pre-allocated vector.

inline void write_single_f64(double value)

Write a single 64-bit floating point number to the file.

Public Static Functions

static std::unique_ptr<BinaryFile> open_native(std::string path, File::Mode mode)

Open the file at the given path using the given mode as a file with the current native endianess