Input and output module. More...

Classes
class	hdf5_file
	High-level interface for managing an HDF5 file, its structure, and operations. More...

class	hdf5_handle
	RAII wrapper for managing HDF5 C-style handles, allowing direct API usage. More...

class	hdf5_node
	Represents a single node (group or dataset) in the HDF5 file hierarchy. More...

Enumerations
enum class	IoError : int { None = 0x00 , FileNotFound = 0x01 , PermissionDenied = 0x02 , ReadError = 0x04 , WriteError = 0x08 , FormatError = 0x10 , EndOfFile = 0x20 }
	IO error enumeration. More...

enum class	HDF5NodeType { UNKNOWN , GROUP , DATASET }
	Type of node inside an HDF5 file. More...

Functions
std::vector< std::string >	parse_csv (const std::string &line, char delimiter=',')
	Parse a CSV line handling quoted fields.

std::string	quote_csv (const std::string &str)
	Given a string entry, sanitize it for printing to a CSV file.

template<typename Type , unsigned int N>
void	write_csv (const std::string &filename, const vec< Type, N > &v, unsigned int precision=8)
	Write a vector to file in the CSV format.

template<typename Type , unsigned int N>
void	write_csv (const std::string &filename, const std::string &header, const vec< Type, N > &v, unsigned int precision=8)
	Write a vector to file in the CSV format, with a column header.

template<typename Type , unsigned int N, enable_real< Type > = true>
void	read_csv (const std::string &filename, vec< Type, N > &v)
	Read a vector from a file in the CSV format.

template<typename Type , unsigned int N, enable_real< Type > = true>
void	read_csv (const std::string &filename, const std::string &col_name, vec< Type, N > &v, bool trim_nan=true)
	Read a specific column of a CSV file as a vector.

template<typename Type , unsigned int N, unsigned int M>
void	write_csv (const std::string &filename, const mat< Type, N, M > &A, const std::string &delimiter=", ", unsigned int precision=8)
	Write a matrix to file in the CSV format.

template<unsigned int N, unsigned int K>
void	read_csv (const std::string &filename, mat< real, N, K > &A)
	Read a matrix from a file in the CSV format.

void	write_csv (const std::string &filename, const data_table &table, const std::string &delimiter=", ", unsigned int precision=8)
	Write a data_table to file in the CSV format.

void	read_csv (const std::string &filename, data_table &table)
	Read a data_table from a file in the CSV format.

void	write_csv (const std::string &filename, const histogram &hist, bool normalized=false, bool lower_extreme=false, const std::string &delimiter=", ", unsigned int precision=8)
	Write histogram data to file in the CSV format.

void	read_csv (const std::string &filename, histogram &hist, bool lower_extreme=false)
	Read a histogram from file, expecting a CSV format with columns "bins", "counts", "number", "average", "tss", "min" and "max", as written by write_csv(histogram).

template<typename Type >
Type	read_csv (const std::string &filename)
	Read a generic data structure from a file in the CSV format, specifying the target type.

int	to_errno (IoError err)
	Convert an IoError class enum to conventional errno codes.

const char *	to_cstring (IoError err)
	Convert an IoError class enum to a string description.

std::string	to_string (const hdf5_node &node)
	Generates a string representation of the HDF5 tree structure.

std::ostream &	operator<< (std::ostream &os, const hdf5_node &node)
	Prints the HDF5 file tree to a stream.

hdf5_handle	hdf5_open (const std::string &filename, bool write=false)
	Open an HDF5 file with the given filename, returning a file handle.

bool	hdf5_is_valid (const hdf5_handle &handle)
	Check whether a given HDF5 handle is valid.

hdf5_node	hdf5_load (const hdf5_handle &id)
	Recursively loads the structure of an active HDF5 group or file.

void	hdf5_create_group (const hdf5_handle &id, const std::string &path)
	Create a new group at the given path under an already open HDF5 location.

void	hdf5_delete_group (const hdf5_handle &id, const std::string &path)
	Delete a group (link) at the given path under an already open HDF5 location.

template<typename Type >
Type	hdf5_read_attribute (const hdf5_handle &id, const std::string &path, const std::string &attr_name)
	Reads an attribute attached to a specific node.

void	hdf5_delete_attribute (const hdf5_handle &id, const std::string &path, const std::string &attr_name)
	Deletes an attribute attached to a specific node, if it exists.

template<typename Type >
void	hdf5_write_attribute (const hdf5_handle &id, const std::string &path, const std::string &attr_name, const Type &value)
	Writes or overwrites an attribute attached to a specific node.

template<typename Vector = vec<real>>
Vector &	hdf5_read_vec (const hdf5_handle &id, const std::string &path, Vector &v)
	Loads a 1D dataset array into a vector.

template<typename Vector = vec<real>>
Vector	hdf5_read_vec (const hdf5_handle &id, const std::string &path)
	Loads a 1D dataset array into a vector.

template<typename Vector >
void	hdf5_write_vec (const hdf5_handle &id, const std::string &path, const Vector &v)
	Writes a 1D vector to an HDF5 dataset, overwriting if it exists.

void	hdf5_delete_dataset (const hdf5_handle &id, const std::string &path)
	Deletes a dataset at the given path if it exists.

template<typename Matrix = mat<real>>
Matrix	hdf5_read_mat (const hdf5_handle &id, const std::string &path, Matrix &m)
	Loads a 2D dataset array into a matrix.

template<typename Matrix = mat<real>>
Matrix	hdf5_read_mat (const hdf5_handle &id, const std::string &path)
	Loads a 2D dataset array into a matrix.

template<typename Matrix >
void	hdf5_write_mat (const hdf5_handle &id, const std::string &path, const Matrix &m)
	Writes a 2D matrix to an HDF5 dataset, overwriting if it exists.

template<typename Type >
void	print (const Type &curr)
	Print the given argument to standard output.

template<typename Type , typename ... Args>
void	print (const Type &curr, Args... args)
	Print the given arguments to standard output separated by a space.

void	println ()
	Print a newline to standard output.

template<typename Type >
void	println (const Type &curr)
	Print the given argument to standard output followed by a newline.

template<typename Type , typename ... Args>
void	println (const Type &curr, Args... args)
	Print the given arguments to standard output separated by a space and followed by a newline.

std::string	readln ()
	Read a line from standard input, up to a line return.

template<typename Type >
void	readln (Type &last)
	Read a single object from standard input, ended by a line return.

template<typename Type , typename ... Args>
void	readln (Type &curr, Args &... args)
	Read objects from standard input, ended by a line return.

bool	is_number (const std::string &str)
	Check if a given string could be correctly interpreted as a number.

std::string	trim (const std::string &str)
	Remove all leading and trailing whitespace from a string, returning the resulting string.

std::string	unquote (const std::string &str)
	Remove leading and trailing double quotes from a string, if both are present.

Detailed Description

Input and output module.

Enumeration Type Documentation

◆ HDF5NodeType

enum class theoretica::io::HDF5NodeType

strong

Type of node inside an HDF5 file.

Enumerator
UNKNOWN	An unsupported node type.
GROUP	A structural grouping containing other groups or datasets.
DATASET	A node containing multi-dimensional array data.

◆ IoError

enum class theoretica::io::IoError : int

strong

IO error enumeration.

Enumerator
None	No error.
FileNotFound	File or directory not found.
PermissionDenied	Permission denied when accessing the file or directory.
ReadError	Error occurred while reading from the file or stream.
WriteError	Error occurred while writing to the file or stream.
FormatError	The file format is invalid or the data is corrupted.
EndOfFile	The end of the file was reached unexpectedly during a read operation.

Function Documentation

◆ hdf5_create_group()

void theoretica::io::hdf5_create_group	(	const hdf5_handle &	id,
		const std::string &	path
	)

inline

Create a new group at the given path under an already open HDF5 location.

Parameters

id	Open HDF5 file/group identifier.
path	Absolute or relative group path to create.

◆ hdf5_delete_attribute()

void theoretica::io::hdf5_delete_attribute	(	const hdf5_handle &	id,
		const std::string &	path,
		const std::string &	attr_name
	)

inline

Deletes an attribute attached to a specific node, if it exists.

Parameters

id	The active file handle
path	Internal path to the node
attr_name	Name of the attribute to delete

◆ hdf5_delete_dataset()

void theoretica::io::hdf5_delete_dataset	(	const hdf5_handle &	id,
		const std::string &	path
	)

inline

Deletes a dataset at the given path if it exists.

Parameters

id	The active file handle
path	Internal path to the dataset

◆ hdf5_delete_group()

void theoretica::io::hdf5_delete_group	(	const hdf5_handle &	id,
		const std::string &	path
	)

inline

Delete a group (link) at the given path under an already open HDF5 location.

Parameters

id	Open HDF5 file/group identifier.
path	Absolute or relative group path to delete.

◆ hdf5_is_valid()

bool theoretica::io::hdf5_is_valid ( const hdf5_handle & handle )

inline

Check whether a given HDF5 handle is valid.

Parameters

handle The HDF5 handle to check

Returns: True if the handle is valid, false otherwise

◆ hdf5_load()

hdf5_node theoretica::io::hdf5_load ( const hdf5_handle & id )

inline

Recursively loads the structure of an active HDF5 group or file.

Parameters

id	The open HDF5 handle representing the search root

Returns: An hdf5_node tree hierarchy representing the file

◆ hdf5_open()

hdf5_handle theoretica::io::hdf5_open	(	const std::string &	filename,
		bool	write = `false`
	)

inline

Open an HDF5 file with the given filename, returning a file handle.

Parameters

filename	The path to the HDF5 file
write	Whether to open the file with write permissions, creating it if it doesn't exist (defaults to false).

◆ hdf5_read_attribute()

template<typename Type >

Type theoretica::io::hdf5_read_attribute	(	const hdf5_handle &	id,
		const std::string &	path,
		const std::string &	attr_name
	)

inline

Reads an attribute attached to a specific node.

Template Parameters

Type	The expected scalar type or std::string

Parameters

id	The active file handle
path	Internal path to the node
attr_name	Name of the attribute to read

Returns: The value of the attribute

◆ hdf5_read_mat() [1/2]

template<typename Matrix = mat<real>>

Matrix theoretica::io::hdf5_read_mat	(	const hdf5_handle &	id,
		const std::string &	path
	)

inline

Loads a 2D dataset array into a matrix.

Template Parameters

Matrix The matrix container type (defaults to mat<real>).

Parameters

id	The active file handle
path	Internal path to the dataset

Returns: The populated matrix

◆ hdf5_read_mat() [2/2]

template<typename Matrix = mat<real>>

Matrix theoretica::io::hdf5_read_mat	(	const hdf5_handle &	id,
		const std::string &	path,
		Matrix &	m
	)

inline

Loads a 2D dataset array into a matrix.

Template Parameters

Matrix The matrix container type (defaults to mat<real>).

Parameters

id	The active file handle
path	Internal path to the dataset

Returns: The populated matrix

◆ hdf5_read_vec() [1/2]

template<typename Vector = vec<real>>

Vector theoretica::io::hdf5_read_vec	(	const hdf5_handle &	id,
		const std::string &	path
	)

inline

Loads a 1D dataset array into a vector.

Template Parameters

Vector The vector container type (defaults to vec<real>).

Parameters

id	The active file handle
path	Internal path to the dataset

Returns: The populated vector

◆ hdf5_read_vec() [2/2]

template<typename Vector = vec<real>>

Vector & theoretica::io::hdf5_read_vec	(	const hdf5_handle &	id,
		const std::string &	path,
		Vector &	v
	)

inline

Loads a 1D dataset array into a vector.

Template Parameters

Vector The vector container type (defaults to vec<real>).

Parameters

id	The active file handle
path	Internal path to the dataset

Returns: The populated vector

◆ hdf5_write_attribute()

template<typename Type >

void theoretica::io::hdf5_write_attribute	(	const hdf5_handle &	id,
		const std::string &	path,
		const std::string &	attr_name,
		const Type &	value
	)

inline

Writes or overwrites an attribute attached to a specific node.

Template Parameters

Type	The scalar type or std::string of the metadata

Parameters

id	The active file handle
path	Internal path to the node
attr_name	Name of the attribute
value	The value to write

◆ hdf5_write_mat()

template<typename Matrix >

void theoretica::io::hdf5_write_mat	(	const hdf5_handle &	id,
		const std::string &	path,
		const Matrix &	m
	)

inline

Writes a 2D matrix to an HDF5 dataset, overwriting if it exists.

Template Parameters

Matrix A generic matrix type. Must support .rows(), .cols(), and .data().

Parameters

id	The active file handle
path	Internal path to place the dataset
m	The matrix data

◆ hdf5_write_vec()

template<typename Vector >

void theoretica::io::hdf5_write_vec	(	const hdf5_handle &	id,
		const std::string &	path,
		const Vector &	v
	)

inline

Writes a 1D vector to an HDF5 dataset, overwriting if it exists.

Template Parameters

Vector The vector container type.

Parameters

id	The active file handle
path	Internal path to place the dataset
v	The vector data

◆ is_number()

bool theoretica::io::is_number ( const std::string & str )

inline

Check if a given string could be correctly interpreted as a number.

Parameters

str	The string to check

Returns: Whether the string could be interpreted as a number

◆ operator<<()

std::ostream & theoretica::io::operator<<	(	std::ostream &	os,
		const hdf5_node &	node
	)

inline

Prints the HDF5 file tree to a stream.

Parameters

os	The output stream
node	The target node

Returns: Reference to the output stream

◆ parse_csv()

std::vector< std::string > theoretica::io::parse_csv	(	const std::string &	line,
		char	delimiter = `','`
	)

inline

Parse a CSV line handling quoted fields.

Supports fields enclosed in double quotes, with delimiters (commas) inside quoted fields. Does not support escaped quotes or multiline fields.

Parameters

line	The CSV line to parse
delimiter	The field delimiter (default is comma)

Returns: A vector of parsed fields

◆ quote_csv()

std::string theoretica::io::quote_csv ( const std::string & str )

inline

Given a string entry, sanitize it for printing to a CSV file.

If it contains commas or whitespace, quotes are added before and after the string.

Parameters

str	The string to check for relevant characters.

Returns: The sanitized string, ready for printing to CSV.

◆ read_csv() [1/6]

template<typename Type >

Type theoretica::io::read_csv ( const std::string & filename )

inline

Read a generic data structure from a file in the CSV format, specifying the target type.

Supported types include vec<> and mat<>.

Parameters

filename The name of the file

Template Parameters

Type	The type of the data structure to read

Returns: The data structure read from the file The template parameter Type should specify a valid supported type, e.g. mat<real>, mat3, vec<real> and so on: auto A = read_csv<mat3>("myfile.csv");

◆ read_csv() [2/6]

template<typename Type , unsigned int N, enable_real< Type > = true>

void theoretica::io::read_csv	(	const std::string &	filename,
		const std::string &	col_name,
		vec< Type, N > &	v,
		bool	trim_nan = `true`
	)

inline

Read a specific column of a CSV file as a vector.

Enables reading a single column from a CSV file which may contain multiple. The file is expected to have a header row, and the column is identified by its header name. If the column is not found, the vector is filled with NaN.

Parameters

filename	The name of the file
v	A reference to the vector to overwrite
col_name	The header name of the column
trim_nan	If true, trailing NaN values are trimmed from the vector (default is true). In a larger dataset, it may happen that other columns are longer than the picked one, and so its missing values are filled with NaN.

◆ read_csv() [3/6]

void theoretica::io::read_csv	(	const std::string &	filename,
		data_table &	table
	)

inline

Read a data_table from a file in the CSV format.

Parameters

filename	The name of the file
table	A reference to the data_table to overwrite If present, the header is read as column names. If the file has fewer rows than the data_table, the remaining rows are filled with NaN.

◆ read_csv() [4/6]

void theoretica::io::read_csv	(	const std::string &	filename,
		histogram &	hist,
		bool	lower_extreme = `false`
	)

inline

Read a histogram from file, expecting a CSV format with columns "bins", "counts", "number", "average", "tss", "min" and "max", as written by write_csv(histogram).

Parameters

filename
hist

◆ read_csv() [5/6]

template<unsigned int N, unsigned int K>

void theoretica::io::read_csv	(	const std::string &	filename,
		mat< real, N, K > &	A
	)

inline

Read a matrix from a file in the CSV format.

Parameters

filename	The name of the file
A	A reference to the matrix to overwrite If present, the header is ignored. If the file has fewer rows or columns than the matrix, the remaining elements are filled with NaN.

◆ read_csv() [6/6]

template<typename Type , unsigned int N, enable_real< Type > = true>

void theoretica::io::read_csv	(	const std::string &	filename,
		vec< Type, N > &	v
	)

inline

Read a vector from a file in the CSV format.

Parameters

filename	The name of the file
v	A reference to the vector to overwrite

If present, the header is ignored. If the file has fewer elements than the vector, the remaining elements are filled with NaN.

◆ readln() [1/3]

std::string theoretica::io::readln ( )

inline

Read a line from standard input, up to a line return.

Returns: The line as a string.

◆ readln() [2/3]

template<typename Type , typename ... Args>

void theoretica::io::readln	(	Type &	curr,
		Args &...	args
	)

inline

Read objects from standard input, ended by a line return.

The object needs to support streaming from an std::istream.

For example, calling readln(x1, x2, x3) reads a line of the form: "1.0 2.0 3.0\n" into variables x1, x2 and x3.

◆ readln() [3/3]

template<typename Type >

void theoretica::io::readln ( Type & last )

inline

Read a single object from standard input, ended by a line return.

The object needs to support streaming from an std::istream.

◆ to_string()

std::string theoretica::io::to_string ( const hdf5_node & node )

inline

Generates a string representation of the HDF5 tree structure.

Parameters

node	The node to stringify (along its children)

Returns: Formatted tree string

◆ trim()

std::string theoretica::io::trim ( const std::string & str )

inline

Remove all leading and trailing whitespace from a string, returning the resulting string.

Parameters

str	The input string

Returns: The trimmed string

◆ unquote()

std::string theoretica::io::unquote ( const std::string & str )

inline

Remove leading and trailing double quotes from a string, if both are present.

Parameters

str	The input string

Returns: The string with quotes removed

◆ write_csv() [1/5]

void theoretica::io::write_csv	(	const std::string &	filename,
		const data_table &	table,
		const std::string &	delimiter = `", "`,
		unsigned int	precision = `8`
	)

inline

Write a data_table to file in the CSV format.

Parameters

filename	The name of the file
table	The data_table to write

◆ write_csv() [2/5]

void theoretica::io::write_csv	(	const std::string &	filename,
		const histogram &	hist,
		bool	normalized = `false`,
		bool	lower_extreme = `false`,
		const std::string &	delimiter = `", "`,
		unsigned int	precision = `8`
	)

inline

Write histogram data to file in the CSV format.

Parameters

filename	The name of the file
histogram	The histogram to save
normalized	Whether to write bin counts as frequency (defaults to false)
lower_extreme	Whether to write the lower extreme of each bin instead of the midpoint (defaults to false).

The CSV file will contain a column "bins" containing the midpoint coordinate of each bin (or the lower extreme, if lower_extreme is true), a column "counts" containing the corresponding bin counts (or frequency, if normalized is true) and additional columns with the histogram statistics: "number", "average", "tss", "min" and "max".

◆ write_csv() [3/5]

template<typename Type , unsigned int N, unsigned int M>

void theoretica::io::write_csv	(	const std::string &	filename,
		const mat< Type, N, M > &	A,
		const std::string &	delimiter = `", "`,
		unsigned int	precision = `8`
	)

inline

Write a matrix to file in the CSV format.

Parameters

filename	The name of the file
A	The matrix to write

◆ write_csv() [4/5]

template<typename Type , unsigned int N>

void theoretica::io::write_csv	(	const std::string &	filename,
		const std::string &	header,
		const vec< Type, N > &	v,
		unsigned int	precision = `8`
	)

inline

Write a vector to file in the CSV format, with a column header.

Parameters

filename	The name of the file
v	The vector to write
header	The header to add for the vector column

◆ write_csv() [5/5]

template<typename Type , unsigned int N>

void theoretica::io::write_csv	(	const std::string &	filename,
		const vec< Type, N > &	v,
		unsigned int	precision = `8`
	)

inline

Write a vector to file in the CSV format.

Parameters

filename	The name of the file
v	The vector to write
header	An optional header to add for the vector column

Classes

Enumerations

Functions

Detailed Description

Enumeration Type Documentation

◆ HDF5NodeType

◆ IoError

Function Documentation

◆ hdf5_create_group()

◆ hdf5_delete_attribute()

◆ hdf5_delete_dataset()

◆ hdf5_delete_group()

◆ hdf5_is_valid()

◆ hdf5_load()

◆ hdf5_open()

◆ hdf5_read_attribute()

◆ hdf5_read_mat() [1/2]

◆ hdf5_read_mat() [2/2]

◆ hdf5_read_vec() [1/2]

◆ hdf5_read_vec() [2/2]

◆ hdf5_write_attribute()

◆ hdf5_write_mat()

◆ hdf5_write_vec()

◆ is_number()

◆ operator<<()

◆ parse_csv()

◆ quote_csv()

◆ read_csv() [1/6]

◆ read_csv() [2/6]

◆ read_csv() [3/6]

◆ read_csv() [4/6]

◆ read_csv() [5/6]

◆ read_csv() [6/6]

◆ readln() [1/3]

◆ readln() [2/3]

◆ readln() [3/3]

◆ to_string()

◆ trim()

◆ unquote()

◆ write_csv() [1/5]

◆ write_csv() [2/5]

◆ write_csv() [3/5]

◆ write_csv() [4/5]

◆ write_csv() [5/5]