HDF5 C++ API Interfaces

                               HDF5 C++ Interfaces
                               ===================

    // HDF5 dataset and attribute have some common characteristics, so the
    // term abstract dataset is used to name the element that can represent
    // both objects, dataset and attribute.
    //
    // Class AbstractDs is an abstract base class, from which Attribute and
    // DataSet inherit.  It provides the services that are common to both
    // Attribute and DataSet.  It also inherits from H5Object and passes down
    // the services that H5Object provides.
    class AbstractDs : public H5Object

    	// Gets the dataspace of this abstract dataset - pure virtual
    	virtual DataSpace getSpace() const = 0;

            // Gets the class of the datatype that is used by this abstract
    	// dataset
    	H5T_class_t getTypeClass() const;

    	// Gets a copy of the datatype that this abstract dataset uses.
    	// Note that this datatype is a generic one and can only be accessed
    	// via generic member functions, i.e., member functions belong to
    	// DataType.  To get specific datatype, i.e. EnumType, FloatType,
    	// etc..., use the specific functions, that follow, instead.
    	DataType getDataType() const;

            // Gets a copy of the specific datatype of this abstract dataset
            EnumType getEnumType() const;
            CompType getCompType() const;
            IntType getIntType() const;
            FloatType getFloatType() const;
            StrType getStrType() const;

    	// Copy constructor
    	AbstractDs( const AbstractDs& original );

    	virtual ~AbstractDs();

    // end of class AbstractDs

    // Atomic datatype can be an integer, float, string, or predefined datatype.
    //
    // Class AtomType is a base class, from which IntType, FloatType, StrType,
    // and PredType inherit.  It provides the services that are common to these
    // subclasses.  It also inherits from DataType and passes down the
    // services that are common to all the datatypes.
    class AtomType : public DataType

    	// Sets the total size for an atomic datatype.
    	void setSize( size_t size ) const;

    	// Returns the byte order of an atomic datatype.
    	H5T_order_t getOrder( string& order_string ) const;

    	// Sets the byte ordering of an atomic datatype.
    	void setOrder( H5T_order_t order ) const;

    	// Returns the precision of an atomic datatype.
    	size_t getPrecision() const;

    	// Sets the precision of an atomic datatype.
    	void setPrecision( size_t precision ) const;

    	// Gets the bit offset of the first significant bit.
    	int getOffset() const;

    	// Sets the bit offset of the first significant bit.
    	void setOffset( size_t offset ) const;

    	// Copy constructor
    	AtomType( const AtomType& original );

    	virtual ~AtomType();

    // end of class AtomType

    // An attribute is an abstract dataset because it has some characteristics
    // that a dataset also has, but not all.
    //
    // Class Attribute inherits from AbstractDs and provides accesses to an
    // attribute.
    class Attribute : public AbstractDs

    	// Writes data to this attribute.
    	void write(const DataType& mem_type, void *buf ) const;

    	// Reads data from this attribute.
    	void read( const DataType& mem_type, void *buf ) const;

    	// Gets a copy of the dataspace for this attribute.
    	virtual DataSpace getSpace() const;

    	// Gets the name of this attribute.
    	string getName( size_t buf_size ) const;

    	// An attribute doesn't have the ability to iterate, simply because
    	// it doesn't have any attributes associated with it.  Thus, the
    	// implementation of this member which is inherited from H5Object
    	// is overwritten to do nothing here.
    	int iterateAttrs() const;

            // Creates a copy of an existing attribute using the attribute id
            Attribute( const hid_t attr_id );

    	// Copy constructor
    	Attribute( const Attribute& original );

    	virtual ~Attribute();

    // CommonFG is a protocol class.  Its existence is simply to provide the
    // common services that are provided by H5File and Group.  The file or
    // group in the context of this class is referred to as 'location'.
    class CommonFG
    	// Creates a new group at this location.
    	Group createGroup( const string& name, size_t size_hint = 0 ) const;
    	Group createGroup( const char* name, size_t size_hint = 0 ) const;

    	// Opens an existing group in a location.
    	Group openGroup( const string& name ) const;
    	Group openGroup( const char* name ) const;

    	// Creates a new dataset at this location.
    	DataSet createDataSet( const string& name, const DataType& data_type, const DataSpace& data_space, const DSetCreatPropList& create_plist = DSetCreatPropList::DEFAULT ) const;
    	DataSet createDataSet( const char* name, const DataType& data_type, const DataSpace& data_space, const DSetCreatPropList& create_plist = DSetCreatPropList::DEFAULT ) const;

    	// Opens an existing dataset at this location.
    	DataSet openDataSet( const string& name ) const;
    	DataSet openDataSet( const char* name ) const;

    	// Creates a link of the specified type from new_name to current_name;
    	// both names are interpreted relative to this location.
    	void link( H5G_link_t link_type, const string& curr_name, const string& new_name ) const;
    	void link( H5G_link_t link_type, const char* curr_name, const char* new_name ) const;

    	// Removes the specified name at this location.
    	void unlink( const string& name ) const;
    	void unlink( const char* name ) const;

    	// Renames an HDF5 object at this location.
    	void move( const string& src, const string& dst ) const;
    	void move( const char* src, const char* dst ) const;

    	// Returns information about an HDF5 object, given by its name, at this location.
    	void getObjinfo( const string& name, hbool_t follow_link, H5G_stat_t& statbuf ) const;
    	void getObjinfo( const char* name, hbool_t follow_link, H5G_stat_t& statbuf ) const;

    	// Returns the name of the HDF5 object that the symbolic link points to.
    	string getLinkval( const string& name, size_t size ) const;
    	string getLinkval( const char* name, size_t size ) const;

    	// Sets the comment for the HDF5 object specified by its name.
    	void setComment( const string& name, const string& comment ) const;
    	void setComment( const char* name, const char* comment ) const;

    	// Retrieves comment for the HDF5 object specified by its name.
    	string getComment( const string& name, size_t bufsize ) const;
    	string getComment( const char* name, size_t bufsize ) const;

    	// Mounts the file 'child' onto this location.
    	void mount( const string& name, H5File& child, PropList& plist ) const;
    	void mount( const char* name, H5File& child, PropList& plist) const;

    	// Unmounts the file named 'name' from this location.
    	void unmount( const string& name ) const;
    	void unmount( const char* name ) const;

    	// Iterates over the elements of this location - not implemented in
    	// C++ style yet
    	int iterateElems( const string& name, int *idx, H5G_iterate_t op, void *op_data );
    	int iterateElems( const char* name, int *idx, H5G_iterate_t op, void *op_data );

    	// Opens a generic named datatype at this location
    	DataType openDataType( const string& name ) const;
    	DataType openDataType( const char* name ) const;

    	// Opens a named enumeration datatype at this location
    	EnumType openEnumType( const string& name ) const;
    	EnumType openEnumType( const char* name ) const;

    	// Opens a named compound datatype at this location
    	CompType openCompType( const string& name ) const;
    	CompType openCompType( const char* name ) const;

    	// Opens a named integer datatype at this location
    	IntType openIntType( const string& name ) const;
    	IntType openIntType( const char* name ) const;

    	// Opens a named floating-point datatype at this location
    	FloatType openFloatType( const string& name ) const;
    	FloatType openFloatType( const char* name ) const;

    	// Opens a named string datatype at this location
    	StrType openStrType( const string& name ) const;
    	StrType openStrType( const char* name ) const;

    	// For H5File and Group to throw appropriate exception - pure virtual
    	virtual void throwException() const = 0;

    	// Get id of the location, either group or file - pure virtual
    	virtual hid_t getLocId() const = 0;

    	CommonFG();
    	virtual ~CommonFG();

    // end of CommonFG declaration

    // Class CompType inherits from DataType and provides accesses to a compound
    // datatype.
    class CompType : public DataType

    	// Creates a new compound datatype, given the type's size.
    	CompType( size_t size );

    	// Creates a compound datatype using an existing id.
    	CompType( const hid_t existing_id );

    	// Gets the compound datatype of the specified dataset.
    	CompType( const DataSet& dataset );

    	// Returns the number of members in this compound datatype.
    	int getNmembers() const;

    	// Returns the name of a member of this compound datatype.
    	string getMemberName( unsigned member_num ) const;

    	// Returns the offset of a member of this compound datatype.
    	size_t getMemberOffset( unsigned memb_no ) const;

    	// Returns the dimensionality of the specified member of this compound datatype.
    	int getMemberDims( int member_num, size_t* dims, int* perm ) const;

    	// Returns the type class of the specified member of this compound
    	// datatype.  It provides to the user a way of knowing what type
    	// to create another datatype of the same class.
    	H5T_class_t getMemberClass( unsigned member_num ) const;

    	// Returns the generic datatype of the specified member in
    	// this compound datatype.
    	DataType getMemberDataType( int member_num ) const;

    	// Returns the enumeration datatype of the specified member in
    	// this compound datatype.
    	EnumType getMemberEnumType( int member_num ) const;

    	// Returns the compound datatype of the specified member in
    	// this compound datatype.
    	CompType getMemberCompType( int member_num ) const;

    	// Returns the integer datatype of the specified member in
    	// this compound datatype.
    	IntType getMemberIntType( int member_num ) const;

    	// Returns the floating-point datatype of the specified member in
    	// this compound datatype.
    	FloatType getMemberFloatType( int member_num ) const;

    	// Returns the string datatype of the specified member in
    	// this compound datatype.
    	StrType getMemberStrType( int member_num ) const;

    	// Adds a new member to this compound datatype.
    	void insertMember( const string name, size_t offset, const DataType& new_member ) const;

    	// Recursively removes padding from within this compound datatype.
    	void pack() const;

    	// Default constructor
    	CompType();

    	// Copy constructor
    	CompType( const CompType& original );

    	virtual ~CompType();

    // end of class CompType

    // Class DataSet inherits from AbstractDs and provides accesses to a dataset.
    class DataSet : public AbstractDs

    	// Gets the dataspace of this dataset.
    	virtual DataSpace getSpace() const;

    	// Gets the creation property list of this dataset.
    	DSetCreatPropList getCreatePlist() const;

    	// Gets the storage size of this dataset.
    	hsize_t getStorageSize() const;

    	// Reads the data of this dataset and stores it in the provided buffer.
    	// The memory and file dataspaces and the transferring property list
    	// can be defaults.
    	void read( void* buf, const DataType& mem_type, const DataSpace& mem_space = DataSpace::ALL, const DataSpace& file_space = DataSpace::ALL, const DSetMemXferPropList& xfer_plist = DSetMemXferPropList::DEFAULT ) const;

    	// Writes the buffered data to this dataset.
    	// The memory and file dataspaces and the transferring property list
    	// can be defaults.
    	void write( const void* buf, const DataType& mem_type, const DataSpace& mem_space = DataSpace::ALL, const DataSpace& file_space = DataSpace::ALL, const DSetMemXferPropList& xfer_plist = DSetMemXferPropList::DEFAULT ) const;

    	// Extends the dataset with unlimited dimension.
    	void extend( const hsize_t* size ) const;

    	// Default constructor
    	DataSet();

    	// Copy constructor
    	DataSet( const DataSet& original );

    	virtual ~DataSet();

    // end of class DataSet

    // Class DataSpace provides accesses to the dataspace.
    class DataSpace : public IdComponent

    	// Default DataSpace objects
    	static const DataSpace ALL;

    	// Creates a dataspace object given the space type.
    	DataSpace( H5S_class_t type );

    	// Creates a simple dataspace.
    	DataSpace( int rank, const hsize_t * dims, const hsize_t * maxdims = NULL);

    	// Makes copy of an existing dataspace.
    	void copy( const DataSpace& like_space );

    	// Determines if this dataspace is a simple one.
    	bool isSimple () const;

    	// Sets the offset of this simple dataspace.
    	void offsetSimple ( const hssize_t* offset ) const;

    	// Retrieves dataspace dimension size and maximum size.
    	int getSimpleExtentDims ( hsize_t *dims, hsize_t *maxdims = NULL ) const;

    	// Gets the dimensionality of this dataspace.
    	int getSimpleExtentNdims () const;

    	// Gets the number of elements in this dataspace.
    	hssize_t getSimpleExtentNpoints () const;

    	// Gets the current class of this dataspace.
    	H5S_class_t getSimpleExtentType () const;

    	// Copies the extent of this dataspace.
    	void extentCopy ( DataSpace& dest_space ) const;

    	// Sets or resets the size of this dataspace.
    	void setExtentSimple( int rank, const hsize_t *current_size, const hsize_t *maximum_size = NULL ) const;

    	// Removes the extent from this dataspace.
    	void setExtentNone () const;

    	// Gets the number of elements in this dataspace selection.
    	hssize_t getSelectNpoints () const;

    	// Get number of hyperslab blocks.
    	hssize_t getSelectHyperNblocks () const;

    	// Gets the list of hyperslab blocks currently selected.
    	void getSelectHyperBlocklist( hsize_t startblock, hsize_t numblocks, hsize_t *buf ) const;

    	// Gets the number of element points in the current selection.
    	hssize_t getSelectElemNpoints () const;

    	// Retrieves the list of element points currently selected.
    	void getSelectElemPointlist ( hsize_t startpoint, hsize_t numpoints, hsize_t *buf ) const;

    	// Gets the bounding box containing the current selection.
    	void getSelectBounds ( hsize_t* start, hsize_t* end ) const;

    	// Selects array elements to be included in the selection for
    	// this dataspace.
    	void selectElements ( H5S_seloper_t op, const size_t num_elements, const hsize_t* coord[ ] ) const;

    	// Selects the entire dataspace.
    	void selectAll () const;

    	// Resets the selection region to include no elements.
    	void selectNone () const;

    	// Verifies that the selection is within the extent of the dataspace.
    	bool selectValid () const;

    	// Selects a hyperslab region to add to the current selected region.
    	void selectHyperslab( H5S_seloper_t op, const hsize_t *count, const hsize_t *start, const hsize_t *stride = NULL, const hsize_t *block = NULL ) const;

    	// Default constructor
    	DataSpace();

    	// Create a dataspace object from a dataspace identifier
    	DataSpace( const hid_t space_id );

    	// Copy constructor
    	DataSpace( const DataSpace& original );

    	virtual ~DataSpace();
    // end of class DataSpace

    // HDF5 datatype can be an atom datatype, a compound datatype, or an
    // enumeration datatype.  A datatype is itself a kind of HDF5 object.
    //
    // Class DataType provides accesses to a generic HDF5 datatype.  It has
    // characteristics which AtomType, CompType, and EnumType inherit.  It also
    // inherits from H5Object and passes down the services to its subclasses.
    class DataType : public H5Object

    	// Creates a datatype given its class and size.
    	DataType( const H5T_class_t type_class, size_t size );

    	// Copies an existing datatype to this datatype instance.
    	void copy( const DataType& like_type );

    	// Returns the datatype class identifier of this datatype.
    	H5T_class_t getClass() const;

    	// Commits a transient datatype to a file; this datatype becomes
    	// a named datatype which can be accessed from the location.
    	void commit( H5Object& loc, const string& name ) const;
    	void commit( H5Object& loc, const char* name ) const;

    	// Determines whether this datatype is a named datatype or
    	// a transient datatype.
    	bool committed() const;

            // Finds a conversion function that can handle the conversion
            // of this datatype to the given datatype, dest.
    	H5T_conv_t find( const DataType& dest, H5T_cdata_t **pcdata ) const;

    	// Converts data from this datatype into the specified datatype, dest.
    	void convert( const DataType& dest, size_t nelmts, void *buf, void *background, PropList& plist ) const;

    	// Sets the overflow handler to a specified function.
    	void setOverflow(H5T_overflow_t func) const;

    	// Returns a pointer to the current global overflow function.
    	H5T_overflow_t getOverflow(void) const;

    	// Locks a datatype.
    	void lock() const;

    	// Returns the size of this datatype.
    	size_t getSize() const;

    	// Returns the base datatype from which a datatype is derived.
    	// Not implemented yet
    	DataType getSuper() const;

    	// Registers a conversion function.
    	void registerFunc(H5T_pers_t pers, const string& name, const DataType& dest, H5T_conv_t func ) const;
    	void registerFunc(H5T_pers_t pers, const char* name, const DataType& dest, H5T_conv_t func ) const;

    	// Removes a conversion function from all conversion paths.
    	void unregister( H5T_pers_t pers, const string& name, const DataType& dest, H5T_conv_t func ) const;
    	void unregister( H5T_pers_t pers, const char* name, const DataType& dest, H5T_conv_t func ) const;

    	// Tags an opaque datatype.
    	void setTag( const string& tag ) const;
    	void setTag( const char* tag ) const;

    	// Gets the tag associated with an opaque datatype.
    	string getTag() const;

    	// Creates a DataType using an existing id - this datatype is
    	// not a predefined type
    	DataType( const hid_t type_id, bool predtype = false );

    	// Default constructor
    	DataType();

    	// Copy constructor
    	DataType( const DataType& original );

    	virtual ~DataType();

    // end of class DataType

    // Class DSetCreatPropList provides accesses to a dataset creation
    // property list.
    class DSetCreatPropList : public PropList

    	// Default DSetCreatPropList object
    	static const DSetCreatPropList DEFAULT;

    	// Copies a dataset creation property list using assignment statement.
    	DSetCreatPropList& operator=( const DSetCreatPropList& rhs );

    	// Sets the type of storage used to store the raw data for the
    	// dataset that uses this property list.
    	void setLayout( hid_t plist, H5D_layout_t layout ) const;

    	// Gets the layout of the raw data storage of the data that uses this
    	// property list.
    	H5D_layout_t getLayout() const;

    	// Sets the size of the chunks used to store a chunked layout dataset.
    	void setChunk( int ndims, const hsize_t* dim ) const;

    	// Retrieves the size of the chunks used to store a chunked layout dataset.
    	int getChunk( int max_ndims, hsize_t* dim ) const;

    	// Sets compression method and compression level
    	void setDeflate( int level ) const;

    	// Sets a dataset fill value.
    	void setFillValue( DataType& fvalue_type, const void* value ) const;

    	// Retrieves a dataset fill value.
    	void getFillValue( DataType& fvalue_type, void* value ) const;

    	// Adds a filter to the filter pipeline
    	void setFilter( H5Z_filter_t filter, unsigned int flags, size_t cd_nelmts, const unsigned int cd_values[] ) const;

    	// Returns the number of filters in the pipeline.
    	int getNfilters() const;

    	// Returns information about a filter in a pipeline.
    	H5Z_filter_t getFilter( int filter_number, unsigned int& flags, size_t& cd_nelmts, unsigned int* cd_values, size_t namelen, char name[] ) const;

    	// Adds an external file to the list of external files.
    	void setExternal( const char* name, off_t offset, hsize_t size ) const;

    	// Returns the number of external files for a dataset.
    	int getExternalCount() const;

    	// Returns information about an external file
    	void getExternal( unsigned idx, size_t name_size, char* name, off_t& offset, hsize_t& size ) const;

    	// Creates a copy of an existing dataset creation property list
    	// using the property list id
    	DSetCreatPropList( const hid_t plist_id );

    	// Default constructor
    	DSetCreatPropList();

    	// Copy constructor
    	DSetCreatPropList( const DSetCreatPropList& original );

    	virtual ~DSetCreatPropList();

    // end of class DSetCreatPropList

    // Class DSetMemXferPropList provides accesses to a dataset memory and
    // transfer property list.
    class DSetMemXferPropList : public PropList

    	// Default object for dataset memory and transfer property list
    	static const DSetMemXferPropList DEFAULT;

    	// Copies a dataset memory and transfer property list using
    	// assignment statement
    	DSetMemXferPropList& operator=( const DSetMemXferPropList& rhs );

    	// Sets type conversion and background buffers
    	void setBuffer( size_t size, void* tconv, void* bkg ) const;

    	// Reads buffer settings
    	size_t getBuffer( void** tconv, void** bkg ) const;

    	// Sets the dataset transfer property list status to TRUE or FALSE
    	void setPreserve( bool status ) const;

    	// Checks status of the dataset transfer property list
    	bool getPreserve() const;

    	// Indicates whether to cache hyperslab blocks during I/O
    	void setHyperCache( bool cache, unsigned limit = 0 ) const;

    	// Returns information regarding the caching of hyperslab blocks during I/O
    	void getHyperCache( bool& cache, unsigned& limit ) const;

    	// Sets B-tree split ratios for a dataset transfer property list
    	void setBtreeRatios( double left, double middle, double right ) const;

    	// Gets B-tree split ratios for a dataset transfer property list
    	void getBtreeRatios( double& left, double& middle, double& right ) const;

    	// Sets the memory manager for variable-length datatype
    	// allocation in H5Dread and H5Dvlen_reclaim
    	void setVlenMemManager( H5MM_allocate_t alloc, void* alloc_info,
    				H5MM_free_t free, void* free_info ) const;

    	// alloc and free are set to NULL, indicating that system
    	// malloc and free are to be used
    	void setVlenMemManager() const;

    	// Gets the memory manager for variable-length datatype
    	// allocation in H5Dread and H5Tvlen_reclaim
    	void getVlenMemManager( H5MM_allocate_t& alloc, void** alloc_info,
    				H5MM_free_t& free, void** free_info ) const;

    	// Sets the transfer mode - parallel mode, not currently supported
    	//void setXfer( H5D_transfer_t data_xfer_mode = H5D_XFER_INDEPENDENT ) const;

    	// Gets the transfer mode - parallel mode, not currently supported
    	//H5D_transfer_t getXfer() const;

    	// Creates a copy of an existing dataset memory and transfer
    	// property list using the property list id
    	DSetMemXferPropList (const hid_t plist_id)

    	// Default constructor
    	DSetMemXferPropList();

    	// Copy constructor
    	DSetMemXferPropList( const DSetMemXferPropList& original );

    	// Default destructor
    	virtual ~DSetMemXferPropList();

    // end of class DSetMemXferPropList

    class EnumType : public DataType

    	// Creates an empty enumeration datatype based on a native signed
    	// integer type, whose size is given by size.
    	EnumType( size_t size );

    	// Gets the enum datatype of the specified dataset
    	EnumType( const DataSet& dataset );  // H5Dget_type

    	// Creates a new enum datatype based on an integer datatype
    	EnumType( const IntType& data_type );  // H5Tenum_create

    	// Inserts a new member to this enumeration type.
    	void insert( const string& name, void *value ) const;
    	void insert( const char* name, void *value ) const;

    	// Returns the symbol name corresponding to a specified member
    	// of this enumeration datatype.
    	string nameOf( void *value, size_t size ) const;

    	// Returns the value corresponding to a specified member of this
    	// enumeration datatype.
    	void valueOf( const string& name, void *value ) const;
    	void valueOf( const char* name, void *value ) const;

    	// Returns the value of an enumeration datatype member
    	void getMemberValue( unsigned memb_no, void *value ) const;

    	// Default constructor
    	EnumType();

    	// Creates an enumeration datatype using an existing id
    	EnumType( const hid_t existing_id );

    	// Copy constructor
    	EnumType( const EnumType& original );

    	virtual ~EnumType();
    // end of class EnumType

    class Exception

    	// Creates an exception with a detailed message
    	Exception( const string& message );

    	Exception( const char* message);

    	// Returns the character string that describes an error specified by
    	// a major error number.
    	string getMajorString( H5E_major_t major_num ) const;

    	// Returns the character string that describes an error specified by
    	// a minor error number.
    	string getMinorString( H5E_minor_t minor_num ) const;

    	// Returns the detailed message set at the time the exception is thrown
    	string getDetailMesg() const;

    	// Turns on the automatic error printing.
    	void setAutoPrint( H5E_auto_t func,
    				void* client_data ) const;

    	// Turns off the automatic error printing.
    	static void dontPrint();

    	// Retrieves the current settings for the automatic error stack
    	// traversal function and its data.
    	void getAutoPrint( H5E_auto_t& func,
    				void** client_data ) const;

    	// Clears the error stack for the current thread.
    	void clearErrorStack() const;

    	// Walks the error stack for the current thread, calling the
    	// specified function.
    	void walkErrorStack( H5E_direction_t direction,
    				H5E_walk_t func, void* client_data ) const;

    	// Default error stack traversal callback function that prints
    	// error messages to the specified output stream.
    	void walkDefErrorStack( int n, H5E_error_t& err_desc,
    				void* client_data ) const;

    	// Prints the error stack in a default manner.
    	//void printError() const;
    	void printError( FILE* stream = NULL ) const;

    	// Creates an exception with no message
    	Exception();

    	// copy constructor
    	Exception( const Exception& original );

    // end of class Exception

    // Class FileIException inherits from Exception to provide exception
    // handling for H5File.
    class FileIException : public Exception
    	FileIException();
    	FileIException( string message );
    // end of class FileIException

    // Class GroupIException inherits from Exception to provide exception
    // handling for Group.
    class GroupIException : public Exception
    	GroupIException();
    	GroupIException( string message );
    // end of class GroupIException

    // Class DataSpaceIException inherits from Exception to provide exception
    // handling for DataSpace.
    class DataSpaceIException : public Exception
    	DataSpaceIException();
    	DataSpaceIException( string message );
    // end of class DataSpaceIException

    // Class DataTypeIException inherits from Exception to provide exception
    // handling for DataType.
    class DataTypeIException : public Exception
    	DataTypeIException();
    	DataTypeIException( string message );
    // end of class DataTypeIException

    // Class PropListIException inherits from Exception to provide exception
    // handling for PropList.
    class PropListIException : public Exception
    	PropListIException();
    	PropListIException( string message );
    // end of class PropListIException

    // Class DataSetIException inherits from Exception to provide exception
    // handling for DataSet.
    class DataSetIException : public Exception
    	DataSetIException();
    	DataSetIException( string message );
    // end of class DataSetIException

    // Class AttributeIException inherits from Exception to provide exception
    // handling for Attribute.
    class AttributeIException : public Exception
    	AttributeIException();
    	AttributeIException( string message );
    // end of class AttributeIException

    // Class LibraryIException inherits from Exception to provide exception
    // handling for H5Library.
    class LibraryIException : public Exception
    	LibraryIException();
    	LibraryIException( string message );
    // end of class LibraryIException

    // Class IdComponentException inherits from Exception to provide exception
    // handling for IdComponent.
    class IdComponentException : public Exception
    	IdComponentException();
    	IdComponentException( string message );
    // end of class IdComponentException

    // Class FileAccPropList provides accesses to a file access property list.
    class FileAccPropList : public PropList

    	// Default file access property list object
    	static const FileAccPropList DEFAULT;

    	// Copies a file access property list using assignment statement.
    	FileAccPropList& operator=( const FileAccPropList& rhs );

    	// Sets alignment properties of this file access property list.
    	void setAlignment( hsize_t threshold = 1, hsize_t alignment = 1 ) const;

    	// Retrieves the current settings for alignment properties from
    	// this file access property list.
    	void getAlignment( hsize_t& threshold, hsize_t& alignment ) const;

    	// Sets the meta data cache and raw data chunk cache parameters.
    	void setCache( int mdc_nelmts, size_t rdcc_nelmts, size_t rdcc_nbytes, double rdcc_w0 ) const;

    	// Retrieves maximum sizes of data caches and the preemption
    	// policy value.
    	void getCache( int& mdc_nelmts, size_t& rdcc_nelmts, size_t& rdcc_nbytes, double& rdcc_w0 ) const;

    	// Sets garbage collecting references flag.
    	void setGcReferences( unsigned gc_ref = 0 ) const;

    	// Returns garbage collecting references setting.
    	unsigned getGcReferences() const;

    	// Creates a copy of an existing file access property list
    	// using the property list id.
    	FileAccPropList (const hid_t plist_id);

    	// Default constructor
    	FileAccPropList();

    	// Copy constructor
    	FileAccPropList( const FileAccPropList& original );

    	// Default destructor
    	virtual ~FileAccPropList();

    // end of class FileAccPropList

    // Class FileCreatPropList provides accesses to a file creation property list.
    class FileCreatPropList : public PropList

    	// Default file creation property list object
    	static const FileCreatPropList DEFAULT;

    	// Copies a file creation property list using assignment statement.
    	FileCreatPropList& operator=( const FileCreatPropList& rhs );

    	// Retrieves version information for various parts of a file.
    	void getVersion( unsigned& boot, unsigned& freelist, unsigned& stab, unsigned& shhdr ) const;

    	// Sets the userblock size field of a file creation property list.
    	void setUserblock( hsize_t size ) const;

    	// Gets the size of a user block in this file creation property list.
    	hsize_t getUserblock() const;

    	// Sets file size-of addresses and sizes.
    	void setSizes( size_t sizeof_addr = 4, size_t sizeof_size = 4 ) const;

    	// Retrieves the size-of address and size quantities stored in a
    	// file according to this file creation property list.
    	void getSizes( size_t& sizeof_addr, size_t& sizeof_size ) const;

    	// Sets the size of parameters used to control the symbol table nodes.
    	void setSymk( unsigned int_nodes_k, unsigned leaf_nodes_k ) const;

    	// Retrieves the size of the symbol table B-tree 1/2 rank and the
    	// symbol table leaf node 1/2 size.
    	void getSymk( unsigned& int_nodes_k, unsigned& leaf_nodes_k ) const;

    	// Sets the size of parameter used to control the B-trees for
    	// indexing chunked datasets.
    	void setIstorek( unsigned ik ) const;

    	// Returns the 1/2 rank of an indexed storage B-tree.
    	unsigned getIstorek() const;

    	// Creates a copy of an existing file create property list
    	// using the property list id.
    	FileCreatPropList (const hid_t plist_id);

    	// Default constructor
    	FileCreatPropList();

    	// Copy constructor
    	FileCreatPropList( const FileCreatPropList& original );

    	// Default destructor
    	virtual ~FileCreatPropList();

    // end of class FileCreatPropList

    // Class H5File provides accesses to an HDF5 file.  It uses the services
    // provided by CommonFG beside inheriting the HDF5 id management from the
    // IdComponent class.
    class H5File : public IdComponent, public CommonFG

    	// Creates or opens an HDF5 file.  The file creation and access
    	// property lists can be default.
    	H5File( const string& name, unsigned int flags, const FileCreatPropList& create_plist = FileCreatPropList::DEFAULT, const FileAccPropList& access_plist = FileAccPropList::DEFAULT );
    	H5File( const char* name, unsigned int flags, const FileCreatPropList& create_plist = FileCreatPropList::DEFAULT, const FileAccPropList& access_plist = FileAccPropList::DEFAULT );

    	// Throw file exception - used by CommonFG to specifically throw
    	// FileIException.
    	virtual void throwException() const;

    	// Determines if a file, specified by its name, is in HDF5 format.
    	static bool isHdf5(const string& name );
    	static bool isHdf5(const char* name );

    	// Reopens this file.
    	void reopen();

    	// Gets the creation property list of this file.
    	FileCreatPropList getCreatePlist() const;

    	// Gets the access property list of this file.
    	FileAccPropList getAccessPlist() const;

    	// Copy constructor
    	H5File(const H5File& original );

    	virtual ~H5File();

    // end of class H5File

    // Class FloatType inherits from AtomType and provides accesses to a
    // floating-point datatype.
    class FloatType : public AtomType

            // Creates a floating-point type using a predefined type.
            FloatType( const PredType& pred_type );

    	// Gets the floating-point datatype of the specified dataset.
    	FloatType( const DataSet& dataset );

    	// Retrieves floating point datatype bit field information.
    	void getFields( size_t& spos, size_t& epos, size_t& esize, size_t& mpos, size_t& msize ) const;

    	// Sets locations and sizes of floating point bit fields.
    	void setFields( size_t spos, size_t epos, size_t esize, size_t mpos, size_t msize ) const;

    	// Retrieves the exponent bias of a floating-point type.
    	size_t getEbias() const;

    	// Sets the exponent bias of a floating-point type.
    	void setEbias( size_t ebias ) const;

    	// Retrieves mantissa normalization of a floating-point datatype.
    	H5T_norm_t getNorm( string& norm_string ) const;

    	// Sets the mantissa normalization of a floating-point datatype.
    	void setNorm( H5T_norm_t norm ) const;

    	// Retrieves the internal padding type for unused bits in
    	// floating-point datatypes.
    	H5T_pad_t getInpad( string& pad_string ) const;

    	// Fills unused internal floating point bits.
    	void setInpad( H5T_pad_t inpad ) const;

    	// Default constructor
    	FloatType();

    	// Creates a floating-point datatype using an existing id.
    	FloatType( const hid_t existing_id );

    	// Copy constructor
    	FloatType( const FloatType& original );

    	virtual ~FloatType();

    // end of class FloatType

    // Class Group provides accesses to an HDF5 group.  As H5File, it uses the
    // services provided by CommonFG.  This class also inherits from H5Object.
    class Group : public H5Object, public CommonFG
       public:

            // Throw group exception - used by CommonFG to specifically throw
    	// GroupIException.
            virtual void throwException() const;

    	// Default constructor
    	Group();

    	// Copy constructor
    	Group( const Group& original );

    	virtual ~Group();

    // end of class Group

    // Class IdComponent provides a mechanism to handle reference counting
    // for an identifier of any HDF5 object.
    class IdComponent
    	// Sets the identifier of this object to a new value.
    	void setId( hid_t new_id );

    	// Creates an object to hold an HDF5 identifier.
    	IdComponent( const hid_t h5_id );

    	// Gets the value of the current HDF5 object id which is held
    	// by this IdComponent object.
    	hid_t getId () const;

    	// Increment reference counter.
    	void incRefCount();

    	// Decrement reference counter.
    	void decRefCount();

    	// Get the reference counter to this identifier.
    	int getCounter();

    	// Decrements the reference counter then determines if there are
    	// no more reference to this object.
    	bool noReference();

    	// Reset this object by deleting its reference counter of the old id.
    	void reset();

    	// Copy constructor
    	IdComponent( const IdComponent& original );

    	// Destructor
    	virtual ~IdComponent();

    }; // end class IdComponent

    // Class IntType inherits from AtomType and provides accesses to
    // integer datatypes.
    class IntType : public AtomType

    	// Creates a integer type using a predefined type.
    	IntType( const PredType& pred_type );

    	// Gets the integer datatype of the specified dataset.
    	IntType( const DataSet& dataset );

    	// Retrieves the sign type for an integer type.
    	H5T_sign_t getSign() const;

    	// Sets the sign proprety for an integer type.
    	void setSign( H5T_sign_t sign ) const;

    	// Default constructor
    	IntType();

    	// Creates a integer datatype using an existing id.
    	IntType( const hid_t existing_id );

    	// Copy constructor
    	IntType( const IntType& original );

    	virtual ~IntType();

    // end of class IntType

    // Class H5Library provides accesses to the HDF5 library.  All of its
    // member functions are static.
    class H5Library

    	// Initializes the HDF5 library.
    	static void open();

    	// Flushes all data to disk, closes files, and cleans up memory.
    	static void close();

    	// Instructs library not to install atexit cleanup routine
    	static void dontAtExit();

    	// Returns the HDF library release number.
    	static void getLibVersion( unsigned& majnum, unsigned& minnum, unsigned& relnum );

    	// Verifies that the arguments match the version numbers compiled
    	// into the library
    	static void checkVersion( unsigned majnum, unsigned minnum, unsigned relnum );

    // end of class H5Library

    // An HDF5 object can be a group, dataset, attribute, or named datatype.
    //
    // Class H5Object provides the services that are typical to an HDF5 object
    // so Group, DataSet, Attribute, and DataType can use them.  It also
    // inherits the HDF5 id management from the class IdComponent.
    class H5Object : public IdComponent

    	// Flushes all buffers associated with this HDF5 object to disk.
    	void flush( H5F_scope_t scope ) const;

    	// Creates an attribute for a group, dataset, or named datatype.
    	// PropList is currently not used, it should always be default.
    	Attribute createAttribute( const char* name, const DataType& type, const DataSpace& space, const PropList& create_plist = PropList::DEFAULT ) const;
    	Attribute createAttribute( const string& name, const DataType& type, const DataSpace& space, const PropList& create_plist = PropList::DEFAULT ) const;

    	// Opens an attribute that belongs to this object, given the
    	// attribute name.
    	Attribute openAttribute( const string& name ) const;
    	Attribute openAttribute( const char* name ) const;

    	// Opens an attribute that belongs to this object, given the
    	// attribute index.
    	Attribute openAttribute( const unsigned int idx ) const;

    	// Iterate user's function over the attributes of this HDF5 object
    	int iterateAttrs( attr_operator_t user_op, unsigned* idx = NULL, void* op_data = NULL );

    	// Determines the number of attributes attached to this HDF5 object.
    	int getNumAttrs() const;

    	// Removes an attribute from this HDF5 object, given the attribute
    	// name.
    	void removeAttr( const string& name ) const;
    	void removeAttr( const char* name ) const;

    	// Copy constructor
    	H5Object( const H5Object& original );

    	virtual ~H5Object();

    // end of class H5Object

    // Class PredType contains all the predefined datatype objects that are
    // currently available.
    class PredType : public AtomType

    	static const PredType STD_I8BE;
    	static const PredType STD_I8LE;
    	static const PredType STD_I16BE;
    	static const PredType STD_I16LE;
    	static const PredType STD_I32BE;
    	static const PredType STD_I32LE;
    	static const PredType STD_I64BE;
    	static const PredType STD_I64LE;
    	static const PredType STD_U8BE;
    	static const PredType STD_U8LE;
    	static const PredType STD_U16BE;
    	static const PredType STD_U16LE;
    	static const PredType STD_U32BE;
    	static const PredType STD_U32LE;
    	static const PredType STD_U64BE;
    	static const PredType STD_U64LE;
    	static const PredType STD_B8BE;
    	static const PredType STD_B8LE;
    	static const PredType STD_B16BE;
    	static const PredType STD_B16LE;
    	static const PredType STD_B32BE;
    	static const PredType STD_B32LE;
    	static const PredType STD_B64BE;
    	static const PredType STD_B64LE;
    	static const PredType STD_REF_OBJ;
    	static const PredType STD_REF_DSETREG;

    	static const PredType C_S1;
    	static const PredType FORTRAN_S1;

    	static const PredType IEEE_F32BE;
    	static const PredType IEEE_F32LE;
    	static const PredType IEEE_F64BE;
    	static const PredType IEEE_F64LE;

    	static const PredType UNIX_D32BE;
    	static const PredType UNIX_D32LE;
    	static const PredType UNIX_D64BE;
    	static const PredType UNIX_D64LE;

    	static const PredType INTEL_I8;
    	static const PredType INTEL_I16;
    	static const PredType INTEL_I32;
    	static const PredType INTEL_I64;
    	static const PredType INTEL_U8;
    	static const PredType INTEL_U16;
    	static const PredType INTEL_U32;
    	static const PredType INTEL_U64;
    	static const PredType INTEL_B8;
    	static const PredType INTEL_B16;
    	static const PredType INTEL_B32;
    	static const PredType INTEL_B64;
    	static const PredType INTEL_F32;
    	static const PredType INTEL_F64;

    	static const PredType ALPHA_I8;
    	static const PredType ALPHA_I16;
    	static const PredType ALPHA_I32;
    	static const PredType ALPHA_I64;
    	static const PredType ALPHA_U8;
    	static const PredType ALPHA_U16;
    	static const PredType ALPHA_U32;
    	static const PredType ALPHA_U64;
    	static const PredType ALPHA_B8;
    	static const PredType ALPHA_B16;
    	static const PredType ALPHA_B32;
    	static const PredType ALPHA_B64;
    	static const PredType ALPHA_F32;
    	static const PredType ALPHA_F64;

    	static const PredType MIPS_I8;
    	static const PredType MIPS_I16;
    	static const PredType MIPS_I32;
    	static const PredType MIPS_I64;
    	static const PredType MIPS_U8;
    	static const PredType MIPS_U16;
    	static const PredType MIPS_U32;
    	static const PredType MIPS_U64;
    	static const PredType MIPS_B8;
    	static const PredType MIPS_B16;
    	static const PredType MIPS_B32;
    	static const PredType MIPS_B64;
    	static const PredType MIPS_F32;
    	static const PredType MIPS_F64;

    	static const PredType NATIVE_CHAR;
    	static const PredType NATIVE_SCHAR;
    	static const PredType NATIVE_UCHAR;
    	static const PredType NATIVE_SHORT;
    	static const PredType NATIVE_USHORT;
    	static const PredType NATIVE_INT;
    	static const PredType NATIVE_UINT;
    	static const PredType NATIVE_LONG;
    	static const PredType NATIVE_ULONG;
    	static const PredType NATIVE_LLONG;
    	static const PredType NATIVE_ULLONG;
    	static const PredType NATIVE_FLOAT;
    	static const PredType NATIVE_DOUBLE;
    	static const PredType NATIVE_LDOUBLE;
    	static const PredType NATIVE_B8;
    	static const PredType NATIVE_B16;
    	static const PredType NATIVE_B32;
    	static const PredType NATIVE_B64;
    	static const PredType NATIVE_OPAQUE;
    	static const PredType NATIVE_HSIZE;
    	static const PredType NATIVE_HSSIZE;
    	static const PredType NATIVE_HERR;
    	static const PredType NATIVE_HBOOL;

    	static const PredType NATIVE_INT8;
    	static const PredType NATIVE_UINT8;
    	static const PredType NATIVE_INT_LEAST8;
    	static const PredType NATIVE_UINT_LEAST8;
    	static const PredType NATIVE_INT_FAST8;
    	static const PredType NATIVE_UINT_FAST8;

    	static const PredType NATIVE_INT16;
    	static const PredType NATIVE_UINT16;
    	static const PredType NATIVE_INT_LEAST16;
    	static const PredType NATIVE_UINT_LEAST16;
    	static const PredType NATIVE_INT_FAST16;
    	static const PredType NATIVE_UINT_FAST16;

    	static const PredType NATIVE_INT32;
    	static const PredType NATIVE_UINT32;
    	static const PredType NATIVE_INT_LEAST32;
    	static const PredType NATIVE_UINT_LEAST32;
    	static const PredType NATIVE_INT_FAST32;
    	static const PredType NATIVE_UINT_FAST32;

    	static const PredType NATIVE_INT64;
    	static const PredType NATIVE_UINT64;
    	static const PredType NATIVE_INT_LEAST64;
    	static const PredType NATIVE_UINT_LEAST64;
    	static const PredType NATIVE_INT_FAST64;
    	static const PredType NATIVE_UINT_FAST64;

    	// Copy constructor
    	PredType( const PredType& original );

    	// Default destructor
    	virtual ~PredType();

       protected:
    	// Default constructor
    	PredType();

    	// Creates a pre-defined type using an HDF5 pre-defined constant
    	PredType( const hid_t predtype_id );  // used by the library only

    // end of class PredType

    // An HDF5 property list can be a file creation property list, a file
    // access property list, a dataset creation property list, or a dataset
    // memory and transfer property list.
    //
    // Class PropList provides accesses to an HDF5 property list.  Its
    // services are inherited by classes FileCreatPropList, FileAccPropList,
    // DSetCreatPropList, and DSetMemXferPropList.  It also inherits the HDF5
    // id management from the class IdComponent.
    class PropList : public IdComponent

    	// Default property list object
            static const PropList DEFAULT;

    	// Creates a property list given the property list type.
    	PropList( H5P_class_t type );

    	// Makes a copy of the given property list.
    	void copy( const PropList& like_plist );

    	// Gets the class of this property list, i.e. H5P_FILE_CREATE,
    	// H5P_FILE_ACCESS, ...
    	H5P_class_t getClass() const;

    	// Default constructor
    	PropList();

    	// Copy constructor
    	PropList( const PropList& original );

    	// Creates a default property list or creates a copy of an
    	// existing property list giving the property list id
    	PropList( const hid_t plist_id );

    	virtual ~PropList();

    // end of class PropList

    // Class RefCounter provides a reference counting mechanism.  It is used
    // mainly by IdComponent to keep track of the references to an HDF5 object
    // identifier.
    class RefCounter

    	// Returns the value of the counter.
            int getCounter () const;

    	// Increments and decrements the counter.
            void increment();
            void decrement();

    	// This bool function is used to determine whether to close an
    	// HDF5 object when there are no more reference to that object.
    	// It decrements the counter, then returns true if there are no
    	// other object references the associated identifier.  When the
    	// function returns true, the associated identifier can be closed
    	// safely.
    	bool noReference();

    	// Default constructor
    	RefCounter();

    	~RefCounter();

    // end of class RefCounter

    // Class StrType inherits from AtomType and provides accesses to a
    // string datatype.
    class StrType : public AtomType
       public:
    	// Creates a string type using a predefined type.
    	StrType( const PredType& pred_type );

            // Gets the string datatype of the specified dataset.
    	StrType( const DataSet& dataset );

    	// Returns the character set type of this string datatype.
    	H5T_cset_t getCset() const;

    	// Sets character set to be used.
    	void setCset( H5T_cset_t cset ) const;

    	// Returns the string padding method for this string datatype.
    	H5T_str_t getStrpad() const;

    	// Defines the storage mechanism for character strings.
    	void setStrpad( H5T_str_t strpad ) const;

    	// Default constructor
    	StrType();

    	// Copy constructor
    	StrType( const StrType& original );

    	// Creates a string datatype using an existing id.
    	StrType( const hid_t existing_id );

    	virtual ~StrType();
    // end of class StrType

    // This template function, resetIdComponent, is used to reset an
    // IdComponent object, which includes closing the associated HDF5
    // identifier if it has no other references.
    // 'Type' can be of the following classes: Attribute, DataSet, DataSpace,
    // DataType, H5File, Group, and PropList.
    template
    void resetIdComponent(
    	Type* obj )	// pointer to object to be reset

Last modified: 17 December 2000