diff options
| author | Frank Baker <fbaker@hdfgroup.org> | 2000-12-21 19:34:29 (GMT) |
|---|---|---|
| committer | Frank Baker <fbaker@hdfgroup.org> | 2000-12-21 19:34:29 (GMT) |
| commit | 7c606e5692bd4ff85545175c3c6ec8956dfb2418 (patch) | |
| tree | 6c7e1cb085ed411679c7cf1ecff6edac2b98a377 /doc | |
| parent | 28c80557badb55fa29d6255f58a56f41fa9047ed (diff) | |
| download | hdf5-7c606e5692bd4ff85545175c3c6ec8956dfb2418.zip hdf5-7c606e5692bd4ff85545175c3c6ec8956dfb2418.tar.gz hdf5-7c606e5692bd4ff85545175c3c6ec8956dfb2418.tar.bz2 | |
[svn-r3175]
Purpose:
CppUserNotes.pdf
CppUserNotes.doc (not for distribution)
CppInterfaces.html
New C++ API documents -- "HDF5 C++ User's Notes"
and "HDF5 C++ Interfaces"
Platforms tested:
IE 5
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/html/cpplus/CppInterfaces.html | 1413 | ||||
| -rw-r--r-- | doc/html/cpplus/CppUserNotes.doc | bin | 0 -> 136192 bytes | |||
| -rw-r--r-- | doc/html/cpplus/CppUserNotes.pdf | bin | 0 -> 55301 bytes |
3 files changed, 1413 insertions, 0 deletions
diff --git a/doc/html/cpplus/CppInterfaces.html b/doc/html/cpplus/CppInterfaces.html new file mode 100644 index 0000000..cf98a2a --- /dev/null +++ b/doc/html/cpplus/CppInterfaces.html @@ -0,0 +1,1413 @@ +<html> +<head> +<title>HDF5 C++ API Interfaces</title> +</head> + +<body bgcolor=#FFFFFF> +<pre> + + 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( int member_num ) const; + + // Returns the offset of a member of this compound datatype. + size_t getMemberOffset( int 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( int 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 hssize_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 hssize_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( int 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( int 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, int 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, int& 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( int& boot, int& freelist, int& stab, int& 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( int int_nodes_k, int 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( int& int_nodes_k, int& leaf_nodes_k ) const; + + // Sets the size of parameter used to control the B-trees for + // indexing chunked datasets. + void setIstorek( int ik ) const; + + // Returns the 1/2 rank of an indexed storage B-tree. + int 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 <class Type> +void resetIdComponent( + Type* obj ) // pointer to object to be reset + +</pre> + +<hr> + +<pre> +Last modified: 17 December 2000 +Describes HDF5 Release 1.4 Beta, December 2000 +</pre> + +</body> +</html> + diff --git a/doc/html/cpplus/CppUserNotes.doc b/doc/html/cpplus/CppUserNotes.doc Binary files differnew file mode 100644 index 0000000..c14d3d6 --- /dev/null +++ b/doc/html/cpplus/CppUserNotes.doc diff --git a/doc/html/cpplus/CppUserNotes.pdf b/doc/html/cpplus/CppUserNotes.pdf Binary files differnew file mode 100644 index 0000000..7d0064f --- /dev/null +++ b/doc/html/cpplus/CppUserNotes.pdf |