General data set. More...

#include <GeneralBranch.h>

Inheritance diagram for hdtree::Branch< DataType, Enable >:

Collaboration diagram for hdtree::Branch< DataType, Enable >:

Public Types
enum	SaveLoad { Both , LoadOnly , SaveOnly }
	Flag how a member variable should be accessed by serialization. More...

Public Member Functions
	Branch (const std::string &branch_name, DataType *handle=nullptr)
	Attach ourselves to the input type after construction. More...

void	load () final override
	Loading this dataset from the file involves simply loading all of the members of the data type. More...

void	attach (Reader &f) final override
	pure virtual method for loading data from the input file More...

void	save () final override
	pure virtual method for saving data More...

void	attach (Writer &f) final override
	pure virtual method for saving structure More...

template<typename MemberType >
void	attach (const std::string &name, MemberType &m, SaveLoad sl=SaveLoad::Both)
	Attach a member object from the our data handle. More...

template<typename MemberType >
void	rename (const std::string &old_name, const std::string &new_name, MemberType &m)
	Rename a member variable. More...

Public Member Functions inherited from hdtree::AbstractBranch< DataType >
	AbstractBranch (const std::string &branch_name, DataType *handle=nullptr)
	Define the dataset branch_name and provide an optional handle. More...

virtual	~AbstractBranch ()
	Delete our object if we own it, otherwise do nothing. More...

virtual void	clear ()
	Define the clear function here to handle the most common cases. More...

virtual const DataType &	get () const
	Get the current in-memory data. More...

int	version () const
	Get the version number for the type we are loading from. More...

virtual void	update (const DataType &val)
	Update the in-memory data object with the passed value. More...

DataType &	operator* ()
	Access the in-memory data object.

const DataType &	operator* () const
	Access the in-memory data opbject in a const manner.

DataType *	operator-> ()
	Pointer access to the in-memory data type.

const DataType *	operator-> () const
	Pointer access to the in-memory data type in a const manner.

Public Member Functions inherited from hdtree::BaseBranch
	BaseBranch (const std::string &full_name)
	define the full name of the branch

virtual	~BaseBranch ()=default
	virtual destructor so inherited classes can be properly destructed.

	BaseBranch (const BaseBranch &)=delete
	no copying

BaseBranch &	operator= (const BaseBranch &)=delete
	no copying

Private Attributes
std::vector< std::tuple< bool, bool, std::unique_ptr< BaseBranch > > >	members_
	list of members in this dataset More...

Reader *	input_file_
	pointer to the input file (if there is one)

Additional Inherited Members
Protected Attributes inherited from hdtree::AbstractBranch< DataType >
std::optional< std::pair< std::string, int > >	load_type_
	type this data is loading from

std::pair< std::string, int >	save_type_
	type this data that is being used to write

DataType *	handle_
	handle on current object in memory

bool	owner_
	we own the object in memory

Protected Attributes inherited from hdtree::BaseBranch
std::string	name_
	name of branch

Detailed Description

template<typename DataType, typename Enable = void>
class hdtree::Branch< DataType, Enable >

General data set.

This is the top-level data set that will be used most often. It is meant to be used by a class which registers its member variables to this set via the io::DataSet<DataType>::attach method.

More complete documentation is kept in the documentation of the hdtree namespace; nevertheless, a short example is kept here.

class MyData {
 public:
  hdtree_class_version(2);
  MyData() = default; // required by serialization technique
  // other public members
 private:
  friend class hdtree::access;
  template<typename Branch>
  void attach(Branch& b) {
    b.attach("my_double",my_double_);
    if (b.version() < 2) b.rename("old","new",new_);
    else b.attach("new",new_);
  }
  void clear() {
    my_double_ = -1; // reset to default value
    new_ = 0;
  }
 private:
  double my_double_;
  int new_;
  // this member doesn't appear in 'attach' so it won't end up on disk
  int i_wont_be_on_disk_;
};

Member Enumeration Documentation

◆ SaveLoad

template<typename DataType , typename Enable = void>

enum hdtree::Branch::SaveLoad

Flag how a member variable should be accessed by serialization.

In this context, load is only called when there is a file to load from.

Enumerator
Both	load and save the member
LoadOnly	only load the member (read in)
SaveOnly	only save the member (write out)

Constructor & Destructor Documentation

◆ Branch()

template<typename DataType , typename Enable = void>

hdtree::Branch< DataType, Enable >::Branch	(	const std::string &	branch_name,
		DataType *	handle = `nullptr`
	)

inlineexplicit

Attach ourselves to the input type after construction.

After the intermediate class AbstractBranch does the initialization, we call the void attach(Branch<DataType>& d) method of the data pointed to by our handle. This allows us to register its member variables with our own Branch<DataType>::attach method.

Parameters

[in]	branch_name	full in-file branch_name to the data set for this data
[in]	handle	address of object already created (optional)

Member Function Documentation

◆ attach() [1/3]

template<typename DataType , typename Enable = void>

template<typename MemberType >

void hdtree::Branch< DataType, Enable >::attach	(	const std::string &	name,
		MemberType &	m,
		SaveLoad	sl = `SaveLoad::Both`
	)

inline

Attach a member object from the our data handle.

We create a new child Branch so that we can recursively handle complex member variable types.

Template Parameters

MemberType type of member variable we are attaching

Parameters

[in]	name	name of member variable
[in]	m	reference of member variable
[in]	save	write this member into output files (if the class is being written)
[in]	load	load this member from an input file (if being read)

◆ attach() [2/3]

template<typename DataType , typename Enable = void>

void hdtree::Branch< DataType, Enable >::attach ( Reader & f )

inlinefinaloverridevirtual

pure virtual method for loading data from the input file

Parameters

[in] f Reader to load from

Implements hdtree::AbstractBranch< DataType >.

◆ attach() [3/3]

template<typename DataType , typename Enable = void>

void hdtree::Branch< DataType, Enable >::attach ( Writer & f )

inlinefinaloverridevirtual

pure virtual method for saving structure

Parameters

[in] f Writer to write to

Implements hdtree::AbstractBranch< DataType >.

◆ load()

template<typename DataType , typename Enable = void>

void hdtree::Branch< DataType, Enable >::load ( )

inlinefinaloverridevirtual

Loading this dataset from the file involves simply loading all of the members of the data type.

We catch a HighFive exception early here so that we can detail to the user which class is causing the read issue. This is especially helpful in the case of containers of user types since the issue is (probably) not coming from serialization of the container.

Exceptions

HDTreeException if HighFive is unable to load any of the members.

Parameters

[in] f file to load from

Implements hdtree::AbstractBranch< DataType >.

◆ rename()

template<typename DataType , typename Enable = void>

template<typename MemberType >

void hdtree::Branch< DataType, Enable >::rename	(	const std::string &	old_name,
		const std::string &	new_name,
		MemberType &	m
	)

inline

Rename a member variable.

This is a simple helper-function wrapping attach which does the two calls for the user sharing the same member variable, creating one member for loading from the old_name and one member for writing to the new_name.

Template Parameters

MemberType type of member variable we are attaching

Parameters

[in]	old_name	name of member variable in version being read from file
[in]	new_name	name of member variable in version being written to output file
[in]	m	reference of member variable

◆ save()

template<typename DataType , typename Enable = void>

void hdtree::Branch< DataType, Enable >::save ( )

inlinefinaloverridevirtual

pure virtual method for saving data

Parameters

[in] f Writer to save to

Implements hdtree::AbstractBranch< DataType >.

Member Data Documentation

◆ members_

template<typename DataType , typename Enable = void>

std::vector<std::tuple<bool, bool, std::unique_ptr<BaseBranch> > > hdtree::Branch< DataType, Enable >::members_

private

list of members in this dataset

the extra boolean flags are to tell us if that member should be loaded from the input file and/or saved to the output file

This is the core of schema evolution.

The documentation for this class was generated from the following file:

cpp/include/hdtree/branch/GeneralBranch.h

Public Types

Public Member Functions

Private Attributes

Additional Inherited Members

Detailed Description

template<typename DataType, typename Enable = void> class hdtree::Branch< DataType, Enable >

Member Enumeration Documentation

◆ SaveLoad

Constructor & Destructor Documentation

◆ Branch()

Member Function Documentation

◆ attach() [1/3]

◆ attach() [2/3]

◆ attach() [3/3]

◆ load()

◆ rename()

◆ save()

Member Data Documentation

◆ members_

template<typename DataType, typename Enable = void>
class hdtree::Branch< DataType, Enable >