dal::File Class Reference

#include <File.h>

Inheritance diagram for dal::File:

List of all members.

Public Member Functions
	File ()
	File (const std::string &filename, FileMode mode=READ, const std::string &versionAttrName="")
virtual	~File ()
File &	operator= (File rhs)
virtual void	open (const std::string &filename, FileMode mode=READ, const std::string &versionAttrName="")
virtual void	close ()
void	flush ()
virtual bool	exists () const
Attribute< VersionType >	version ()
Friends
void	swap (File &first, File &second)

---

Detailed Description

A File object encapsulates the data and provides the functions to operate on a HDF5 file.

Note on reopening files and destructing File objects: Best practise is to destruct all references to a file's contents (groups, datasets, attributes, etc) before destructing or close()ing the File object itself. And not to reopen a file while HDF5 still has it open.

HDF5 can only close a file once all references to its contents have been closed. As long as HDF5 references remain open, HDF5 leaves the file open (usually possible). You could reopen the file with the same mode; HDF5 will try to keep both accesses to the file consistent (may fail on distributed file systems). If you want to reopen a read-write file as read-only, drop all references, close() it, then open() it.

For more detail, see the HDF5 Reference/API Manual on H5Fopen() and H5Fclose().

---

Constructor & Destructor Documentation

dal::File::File

(

)

Create default File object. This is intended to be able to have a container that contains a File object before the filename is known. Once the filename is known, use open() to initialize further.

dal::File::File	(	const std::string &	filename,
		FileMode	mode = READ,
		const std::string &	versionAttrName = ""
	)

Try to open or create `filename` with open mode `mode` and treat `versionAttrName` as the version attribute name. For an existing file, the specified version attribute must exist. For a new file, it will be created. The default value skips Node tracking (except Group's GROUPTYPE) and versioning.

See the class description for more info on reopening and closing files.

Python example:

    # Create and close a new HDF5 file called "example.h5"
    >>> f = File("example.h5", File.CREATE)
    >>> del f

    # Open (and close) the same file for reading
    >>> f = File("example.h5", File.READ)
    >>> del f

    # Clean up
    >>> import os
    >>> os.remove("example.h5")

dal::File::~File

(

)

[virtual]

Destruct File object.

---

Member Function Documentation

void dal::File::close

(

)

[virtual]

Indicate that this File object will not be used anymore to access the underlying HDF5 file (if any), possibly until a subsequent call to open().

See the class description for more info on reopening and closing files.

Reimplemented in dal::BF_File, dal::TBB_File, and dal::CLA_File.

bool dal::File::exists

(

)

const [virtual]

Returns whether this file exists (i.e. true).

Reimplemented from dal::Group.

void dal::File::flush

(

)

Commit any changes to disk.

void dal::File::open	(	const std::string &	filename,
		FileMode	mode = READ,
		const std::string &	versionAttrName = ""
	)		[virtual]

Open or create `filename` with open mode `mode` and treat `versionAttrName` as the version attribute name. Upon return, the previously opened file reference (if any) has been closed. If an exception is thrown, the previously opened file reference (if any) is unaltered.

See the File(filename, mode, versionAttrName) constructor for more info. See the class description for more info on reopening and closing files.

File & dal::File::operator=

(

File

rhs

)

Assign the rhs object to this object and return a reference to this object. If the operation succeeds, the previous state of this object (if any) is destructed. If the operation fails, an exception is thrown.

Attribute< VersionType > dal::File::version

(

)

Returns the version attribute using the `versionAttrName` passed when the file was opened or created.

Python example:

    # Create and close a new HDF5 file called "example.h5"
    >>> f = File("example.h5", File.CREATE)

    # Set and get the file version
    >>> f.version(VersionType(1,2,3))

    # version() reports the version
    >>> str(f.version().get())
    '1.2.3'

    # Groups and attributes inherit the Version
    >>> g = Group(f, "GROUP")
    >>> str(g.version())
    '1.2.3'

    # Note: changing the version affects
    # already existing group objects.
    >>> f.version.set(VersionType(4,5,6))
    >>> str(f.version().get())
    '4.5.6'
    >>> str(g.version.get())
    '4.5.6'

    # Reload other objects to refresh the file info,
    # including the newly set version.
    >>> g = Group(f, "GROUP")
    >>> str(g.version())
    '4.5.6'

    # Clean up
    >>> import os
    >>> os.remove("example.h5")

---

Friends And Related Function Documentation

void swap	(	File &	first,
		File &	second
	)		[friend]

Store the pair of File objects (first, second) into (second, first). Specialization of std::swap(). Always succeeds.

---

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

• /home/amesfoort/DAL/dal/hdf5/File.h
• /home/amesfoort/DAL/dal/hdf5/File.cc