HDF5 C++ API  1.8.20
 All Classes Namespaces Functions Variables Typedefs Friends Pages
Public Member Functions | Protected Member Functions | List of all members
H5::H5Location Class Referenceabstract

H5Location is an abstract base class, providing a collection of wrappers of the C functions that take a location identifier, which can be either file, group, dataset, attribute, or named datatype.

#include <H5Location.h>

Inheritance diagram for H5::H5Location:
H5::IdComponent H5::Attribute H5::H5Object H5::DataSet H5::DataType H5::Group H5::ArrayType H5::AtomType H5::CompType H5::EnumType H5::VarLenType H5::H5File H5::FloatType H5::IntType H5::PredType H5::StrType

Public Member Functions

bool nameExists (const char *name, const LinkAccPropList &lapl=LinkAccPropList::DEFAULT) const
 Checks if a link of a given name exists in a location. More...
 
bool nameExists (const H5std_string &name, const LinkAccPropList &lapl=LinkAccPropList::DEFAULT) const
 Checks if a link of a given name exists in a location. More...
 
void flush (H5F_scope_t scope) const
 Flushes all buffers associated with a location to disk. More...
 
H5std_string getFileName () const
 Gets the name of the file, in which this HDF5 object belongs. More...
 
void getObjectInfo (H5O_info_t *oinfo) const
 Retrieve information about an object, specified by location.

Exceptions
H5::LocationException.
More...
 
void getObjectInfo (const char *name, H5O_info_t *oinfo, const LinkAccPropList &lapl=LinkAccPropList::DEFAULT) const
 Retrieve information about an object, specified by name.

Exceptions
H5::LocationException.
More...
 
void getObjectInfo (const H5std_string &name, H5O_info_t *oinfo, const LinkAccPropList &lapl=LinkAccPropList::DEFAULT) const
 Retrieve information about an object, specified by name.

Exceptions
H5::LocationException.
More...
 
int getNumAttrs () const
 Deprecated - replaced by H5Object::getNumAttrs() More...
 
H5G_obj_t getObjType (void *ref, H5R_type_t ref_type=H5R_OBJECT) const
 Retrieves the type of object that an object reference points to. More...
 
H5O_type_t getRefObjType (void *ref, H5R_type_t ref_type=H5R_OBJECT) const
 Retrieves the type of object that an object reference points to. More...
 
unsigned objVersion () const
 Returns the header version of this HDF5 object. More...
 
void setComment (const char *name, const char *comment) const
 Sets or resets the comment for an object specified by its name. More...
 
void setComment (const H5std_string &name, const H5std_string &comment) const
 This is an overloaded member function, provided for convenience. It differs from the above function in that it takes an H5std_string for name and comment. More...
 
void setComment (const char *comment) const
 This is an overloaded member function, provided for convenience. It differs from the above function in that it doesn't take an object name. More...
 
void setComment (const H5std_string &comment) const
 This is an overloaded member function, provided for convenience. It differs from the above function in that it takes an H5std_string for comment. More...
 
ssize_t getComment (const char *name, size_t buf_size, char *comment) const
 Retrieves the comment for this location, returning its length. More...
 
H5std_string getComment (const char *name, size_t buf_size=0) const
 Returns the comment as string for this location, returning its length. More...
 
H5std_string getComment (const H5std_string &name, size_t buf_size=0) const
 This is an overloaded member function, provided for convenience. It differs from the above function in that it takes an H5std_string for name. More...
 
void removeComment (const char *name) const
 Removes the comment from an object specified by its name. More...
 
void removeComment (const H5std_string &name) const
 This is an overloaded member function, provided for convenience. It differs from the above function in that it takes an H5std_string for name. More...
 
void reference (void *ref, const char *name, H5R_type_t ref_type=H5R_OBJECT) const
 This is an overloaded function, provided for your convenience. It differs from the above function in that it does not take a DataSpace object and the reference type must be specified. More...
 
void reference (void *ref, const H5std_string &name, H5R_type_t ref_type=H5R_OBJECT) const
 This is an overloaded function, provided for your convenience. It differs from the above function in that it takes an H5std_string for the object's name. More...
 
void reference (void *ref, const char *name, const DataSpace &dataspace, H5R_type_t ref_type=H5R_DATASET_REGION) const
 Creates a reference to an HDF5 object or a dataset region. More...
 
void reference (void *ref, const H5std_string &name, const DataSpace &dataspace, H5R_type_t ref_type=H5R_DATASET_REGION) const
 This is an overloaded member function, provided for convenience. It differs from the above function in that it takes an H5std_string for name. More...
 
void dereference (const H5Location &loc, const void *ref, H5R_type_t ref_type=H5R_OBJECT)
 Dereferences a reference into an HDF5 object, given an HDF5 object. More...
 
void dereference (const Attribute &attr, const void *ref, H5R_type_t ref_type=H5R_OBJECT)
 Dereferences a reference into an HDF5 object, given an attribute. More...
 
DataSpace getRegion (void *ref, H5R_type_t ref_type=H5R_DATASET_REGION) const
 Retrieves a dataspace with the region pointed to selected. More...
 
hid_t openObjId (const char *name, const LinkAccPropList &lapl=LinkAccPropList::DEFAULT) const
 Opens an object without knowing the object type. More...
 
hid_t openObjId (const H5std_string &name, const LinkAccPropList &lapl=LinkAccPropList::DEFAULT) const
 This is an overloaded member function, provided for convenience. It takes a reference to a H5std_string for the object's path. More...
 
void closeObjId (hid_t obj_id) const
 Closes an object, which was opened with H5Location::openObjId. More...
 
virtual hid_t getId () const =0
 Returns an identifier. (pure virtual) More...
 
virtual Attribute createAttribute (const char *name, const DataType &type, const DataSpace &space, const PropList &create_plist=PropList::DEFAULT) const
 Deprecated - replaced by H5Object::createAttribute. More...
 
virtual Attribute createAttribute (const H5std_string &name, const DataType &type, const DataSpace &space, const PropList &create_plist=PropList::DEFAULT) const
 Deprecated - replaced by H5Object::createAttribute. More...
 
virtual Attribute openAttribute (const char *name) const
 Deprecated - replaced by H5Object::openAttribute. More...
 
virtual Attribute openAttribute (const H5std_string &name) const
 Deprecated - replaced by H5Object::openAttribute. More...
 
virtual Attribute openAttribute (const unsigned int idx) const
 Deprecated - replaced by H5Object::openAttribute. More...
 
virtual int iterateAttrs (attr_operator_t user_op, unsigned *idx=NULL, void *op_data=NULL)
 Iterates a user's function over all the attributes of an H5 object, which may be a group, dataset or named datatype. More...
 
virtual bool attrExists (const char *name) const
 Deprecated - replaced by H5Object::attrExists() More...
 
virtual bool attrExists (const H5std_string &name) const
 Deprecated - replaced by H5Object::attrExists() More...
 
virtual void renameAttr (const char *oldname, const char *newname) const
 Deprecated - replaced by H5Object::renameAttr() More...
 
virtual void renameAttr (const H5std_string &oldname, const H5std_string &newname) const
 Deprecated - replaced by H5Object::renameAttr() More...
 
virtual void removeAttr (const char *name) const
 Deprecated - replaced by H5Object::removeAttr() More...
 
virtual void removeAttr (const H5std_string &name) const
 Deprecated - replaced by H5Object::removeAttr() More...
 
- Public Member Functions inherited from H5::IdComponent
void incRefCount (const hid_t obj_id) const
 Increment reference counter for a given id. More...
 
void incRefCount () const
 Increment reference counter for the id of this object. More...
 
void decRefCount (const hid_t obj_id) const
 Decrement reference counter for a given id. More...
 
void decRefCount () const
 Decrement reference counter for the id of this object. More...
 
int getCounter (const hid_t obj_id) const
 Returns the reference counter for a given id. More...
 
int getCounter () const
 Returns the reference counter for the id of this object. More...
 
H5I_type_t getHDFObjType () const
 Returns the type of the object. It is an overloaded function of the above function. More...
 
IdComponentoperator= (const IdComponent &rhs)
 Assignment operator. More...
 
void setId (const hid_t new_id)
 Sets the identifier of this object to a new value. More...
 
virtual ~IdComponent ()
 Noop destructor. More...
 

Protected Member Functions

virtual ~H5Location ()
 Noop destructor. More...
 

Additional Inherited Members

- Static Public Member Functions inherited from H5::IdComponent
static H5I_type_t getHDFObjType (const hid_t obj_id)
 Given an id, returns the type of the object. More...
 
static bool isValid (hid_t an_id)
 Checks if the given ID is valid. More...
 

Constructor & Destructor Documentation

H5::H5Location::~H5Location ( )
protectedvirtual

Member Function Documentation

bool H5::H5Location::attrExists ( const char *  name) const
virtual
Parameters
name- IN: Name of the attribute to be queried
Exceptions
H5::AttributeIException

Reimplemented in H5::H5Object.

References getId().

Referenced by attrExists().

bool H5::H5Location::attrExists ( const H5std_string &  name) const
virtual
Parameters
name- IN: Name of the attribute to be queried

Reimplemented in H5::H5Object.

References attrExists().

void H5::H5Location::closeObjId ( hid_t  obj_id) const
Attribute H5::H5Location::createAttribute ( const char *  name,
const DataType data_type,
const DataSpace data_space,
const PropList create_plist = PropList::DEFAULT 
) const
virtual
Parameters
name- IN: Name of the attribute
data_type- IN: Datatype for the attribute
data_space- IN: Dataspace for the attribute - only simple dataspaces are allowed at this time
create_plist- IN: Creation property list - default to PropList::DEFAULT
Returns
Attribute instance
Exceptions
H5::AttributeIException
Description
The attribute name specified in name must be unique. Attempting to create an attribute with the same name as an existing attribute will raise an exception, leaving the pre-existing attribute intact. To overwrite an existing attribute with a new attribute of the same name, first delete the existing one with H5Location::removeAttr, then recreate it with this function.

Reimplemented in H5::H5Object.

References H5::f_Attribute_setId(), H5::PropList::getId(), H5::DataSpace::getId(), getId(), and H5::DataType::getId().

Referenced by createAttribute().

Attribute H5::H5Location::createAttribute ( const H5std_string &  name,
const DataType data_type,
const DataSpace data_space,
const PropList create_plist = PropList::DEFAULT 
) const
virtual

It differs from the above function in that it takes a reference to an H5std_string for name.

Reimplemented in H5::H5Object.

References createAttribute().

void H5::H5Location::dereference ( const H5Location loc,
const void *  ref,
H5R_type_t  ref_type = H5R_OBJECT 
)
Parameters
loc- IN: Location of the referenced object
ref- IN: Reference pointer
ref_type- IN: Reference type
Exceptions
H5::ReferenceException

References getId().

void H5::H5Location::dereference ( const Attribute attr,
const void *  ref,
H5R_type_t  ref_type = H5R_OBJECT 
)
Parameters
attr- IN: Attribute specifying the location of the referenced object
ref- IN: Reference pointer
ref_type- IN: Reference type
Exceptions
H5::ReferenceException

References H5::Attribute::getId().

void H5::H5Location::flush ( H5F_scope_t  scope) const
Parameters
scope- IN: Specifies the scope of the flushing action, which can be either of these values:
  • H5F_SCOPE_GLOBAL - Flushes the entire virtual file
  • H5F_SCOPE_LOCAL - Flushes only the specified file
Exceptions
H5::LocationException
Description
This location is used to identify the file to be flushed.

References getId().

ssize_t H5::H5Location::getComment ( const char *  name,
size_t  buf_size,
char *  comment 
) const
Parameters
name- IN: Name of the object
buf_size- IN: Length of the comment to retrieve
comment- OUT: Retrieved comment
Returns
Actual length of the comment
Exceptions
H5::LocationException
Description
This function retrieves buf_size characters of the comment including the null terminator. Thus, if the actual length of the comment is more than buf_size-1, the retrieved comment will be truncated to accommodate the null terminator.

References getId().

Referenced by getComment().

H5std_string H5::H5Location::getComment ( const char *  name,
size_t  buf_size = 0 
) const
Parameters
name- IN: Name of the object
buf_size- IN: Length of the comment to retrieve, default to 0
Returns
Comment string
Exceptions
H5::LocationException

References getComment(), and getId().

H5std_string H5::H5Location::getComment ( const H5std_string &  name,
size_t  buf_size = 0 
) const

References getComment().

H5std_string H5::H5Location::getFileName ( ) const
Returns
File name
Exceptions
H5::LocationException

References H5::Exception::getDetailMsg().

virtual hid_t H5::H5Location::getId ( ) const
pure virtual
int H5::H5Location::getNumAttrs ( ) const
Returns
Number of attributes
Exceptions
H5::AttributeIException

References getId().

void H5::H5Location::getObjectInfo ( H5O_info_t *  oinfo) const

References getId().

void H5::H5Location::getObjectInfo ( const char *  name,
H5O_info_t *  oinfo,
const LinkAccPropList lapl = LinkAccPropList::DEFAULT 
) const

References H5::PropList::getId(), and getId().

void H5::H5Location::getObjectInfo ( const H5std_string &  name,
H5O_info_t *  oinfo,
const LinkAccPropList lapl = LinkAccPropList::DEFAULT 
) const

References H5::PropList::getId(), and getId().

H5G_obj_t H5::H5Location::getObjType ( void *  ref,
H5R_type_t  ref_type = H5R_OBJECT 
) const
Parameters
ref_type- IN: Type of reference to query, valid values are:
  • H5R_OBJECT - Reference is an object reference.
  • H5R_DATASET_REGION - Reference is a dataset region reference.
ref- IN: Reference to query
Returns
An object type, which can be one of the following:
  • H5G_UNKNOWN - A failure occurs. (-1)
  • H5G_GROUP - Object is a group.
  • H5G_DATASET - Object is a dataset.
  • H5G_TYPE Object - is a named datatype
  • H5G_LINK - Object is a symbolic link.
  • H5G_UDLINK - Object is a user-defined link.
Exceptions
H5::ReferenceException

References H5::Exception::getDetailMsg().

H5O_type_t H5::H5Location::getRefObjType ( void *  ref,
H5R_type_t  ref_type = H5R_OBJECT 
) const
Parameters
ref- IN: Reference to query
ref_type- IN: Type of reference to query, valid values are:
  • H5R_OBJECT - Reference is an object reference.
  • H5R_DATASET_REGION - Reference is a dataset region reference.
Returns
An object type, which can be one of the following:
  • H5O_TYPE_UNKNOWN - Unknown object type (-1)
  • H5O_TYPE_GROUP - Object is a group
  • H5O_TYPE_DATASET - Object is a dataset
  • H5O_TYPE_NAMED_DATATYPE - Object is a named datatype
  • H5O_TYPE_NTYPES - Number of different object types
Exceptions
H5::ReferenceException

References H5::Exception::getDetailMsg().

DataSpace H5::H5Location::getRegion ( void *  ref,
H5R_type_t  ref_type = H5R_DATASET_REGION 
) const
Parameters
ref- IN: Reference to get region of
ref_type- IN: Type of reference to get region of - default
Returns
DataSpace object
Exceptions
H5::ReferenceException

References H5::f_DataSpace_setId(), H5::Exception::getDetailMsg(), and getId().

int H5::H5Location::iterateAttrs ( attr_operator_t  user_op,
unsigned *  _idx = NULL,
void *  op_data = NULL 
)
virtual
Parameters
user_op- IN: User's function to operate on each attribute
_idx- IN/OUT: Starting (IN) and ending (OUT) attribute indices
op_data- IN: User's data to pass to user's operator function
Returns
Returned value of the last operator if it was non-zero, or zero if all attributes were processed
Exceptions
H5::AttributeIException
Description
The signature of user_op is void (*)(H5::H5Location&, H5std_string, void*). For information, please refer to the C layer Reference Manual at: https://support.hdfgroup.org/HDF5/doc/RM/RM_H5A.html#Annot-Iterate

References getId(), H5::UserData4Aiterate::location, H5::UserData4Aiterate::op, and H5::UserData4Aiterate::opData.

bool H5::H5Location::nameExists ( const char *  name,
const LinkAccPropList lapl = LinkAccPropList::DEFAULT 
) const
Parameters
name- IN: Searched name - char*
lapl- IN: Link access property list
Exceptions
H5::LocationException

References H5::PropList::getId(), and getId().

Referenced by nameExists().

bool H5::H5Location::nameExists ( const H5std_string &  name,
const LinkAccPropList lapl = LinkAccPropList::DEFAULT 
) const
Parameters
name- IN: Searched name - H5std_string
lapl- IN: Link access property list
Exceptions
H5::LocationException

References nameExists().

unsigned H5::H5Location::objVersion ( ) const
Returns
Object version, which can have the following values:
  • H5O_VERSION_1
  • H5O_VERSION_2
Exceptions
H5::LocationExceptionException will be thrown when:
  • an error returned by the C API
  • version number is not one of the valid values above

References getId().

Attribute H5::H5Location::openAttribute ( const char *  name) const
virtual
Parameters
name- IN: Name of the attribute
Returns
Attribute instance
Exceptions
H5::AttributeIException

Reimplemented in H5::H5Object.

References H5::f_Attribute_setId(), and getId().

Referenced by openAttribute().

Attribute H5::H5Location::openAttribute ( const H5std_string &  name) const
virtual
Parameters
name- IN: Name of the attribute

Reimplemented in H5::H5Object.

References openAttribute().

Attribute H5::H5Location::openAttribute ( const unsigned int  idx) const
virtual
Parameters
idx- IN: Index of the attribute, a 0-based, non-negative integer
Returns
Attribute instance
Exceptions
H5::AttributeIException

Reimplemented in H5::H5Object.

References H5::f_Attribute_setId(), and getId().

hid_t H5::H5Location::openObjId ( const char *  obj_name,
const LinkAccPropList lapl = LinkAccPropList::DEFAULT 
) const
Parameters
obj_name- IN: Path to the object
lapl- IN: Access property list for the link pointing to the object
Exceptions
H5::LocationException
Description
This function opens an object at this location, using H5Oopen. Thus, an object can be opened without knowing the object's type.

References H5::PropList::getId(), and getId().

Referenced by openObjId().

hid_t H5::H5Location::openObjId ( const H5std_string &  obj_name,
const LinkAccPropList lapl = LinkAccPropList::DEFAULT 
) const
Parameters
obj_name- IN: Path to the object
lapl- IN: Access property list for the link pointing to the object
Exceptions
H5::LocationException

References openObjId().

void H5::H5Location::reference ( void *  ref,
const char *  name,
H5R_type_t  ref_type = H5R_OBJECT 
) const
Parameters
ref- IN: Reference pointer
name- IN: Name of the object to be referenced
ref_type- IN: Type of reference to query, valid values are:
  • H5R_OBJECT - Reference is an object reference (default)
  • H5R_DATASET_REGION - Reference is a dataset region
Exceptions
H5::ReferenceException
Note
This method is more suitable for an object reference.

References H5::Exception::getDetailMsg().

Referenced by reference().

void H5::H5Location::reference ( void *  ref,
const H5std_string &  name,
H5R_type_t  ref_type = H5R_OBJECT 
) const
Parameters
ref- IN: Reference pointer
name- IN: Name of the object to be referenced - H5std_string
ref_type- IN: Type of reference to query, valid values are:
  • H5R_OBJECT - Reference is an object reference (default)
  • H5R_DATASET_REGION - Reference is a dataset region
Note
This method is more suitable for an object reference.

References reference().

void H5::H5Location::reference ( void *  ref,
const char *  name,
const DataSpace dataspace,
H5R_type_t  ref_type = H5R_DATASET_REGION 
) const
Parameters
ref- IN: Reference pointer
name- IN: Name of the object to be referenced
dataspace- IN: Dataspace with selection
ref_type- IN: Type of reference to query, valid values are:
  • H5R_OBJECT - Reference is an object reference.
  • H5R_DATASET_REGION - Reference is a dataset region reference. (default)
Exceptions
H5::ReferenceException
Note
This method is more suitable for a dataset region reference.

References H5::Exception::getDetailMsg(), and H5::DataSpace::getId().

void H5::H5Location::reference ( void *  ref,
const H5std_string &  name,
const DataSpace dataspace,
H5R_type_t  ref_type = H5R_DATASET_REGION 
) const
Parameters
ref- IN: Reference pointer
name- IN: Name of the object to be referenced
dataspace- IN: Dataspace with selection
ref_type- IN: Type of reference to query, valid values are:
  • H5R_OBJECT - Reference is an object reference.
  • H5R_DATASET_REGION - Reference is a dataset region reference. (default)
Exceptions
H5::ReferenceException
Note
This method is more suitable for a dataset region reference.

References H5::Exception::getDetailMsg(), and H5::DataSpace::getId().

void H5::H5Location::removeAttr ( const char *  name) const
virtual
Parameters
name- IN: Name of the attribute to be removed
Exceptions
H5::AttributeIException

Reimplemented in H5::H5Object.

References getId().

Referenced by removeAttr().

void H5::H5Location::removeAttr ( const H5std_string &  name) const
virtual
Parameters
name- IN: Name of the attribute to be removed

Reimplemented in H5::H5Object.

References removeAttr().

void H5::H5Location::removeComment ( const char *  name) const
Parameters
name- IN: Name of the object
Exceptions
H5::LocationException

References getId().

Referenced by removeComment().

void H5::H5Location::removeComment ( const H5std_string &  name) const

References removeComment().

void H5::H5Location::renameAttr ( const char *  oldname,
const char *  newname 
) const
virtual
Parameters
oldname- IN: Name of the attribute to be renamed
newname- IN: New name ame of the attribute
Exceptions
H5::AttributeIException

Reimplemented in H5::H5Object.

References getId().

Referenced by renameAttr().

void H5::H5Location::renameAttr ( const H5std_string &  oldname,
const H5std_string &  newname 
) const
virtual
Parameters
oldname- IN: Name of the attribute to be renamed
newname- IN: New name ame of the attribute
Exceptions
H5::AttributeIException

Reimplemented in H5::H5Object.

References renameAttr().

void H5::H5Location::setComment ( const char *  name,
const char *  comment 
) const
Parameters
name- IN: Name of the object
comment- IN: New comment
Exceptions
H5::LocationException
Description
If comment is an empty string or a null pointer, the comment message is removed from the object. Comments should be relatively short, null-terminated, ASCII strings. They can be attached to any object that has an object header, e.g., data sets, groups, named data types, and data spaces, but not symbolic links.

References getId().

Referenced by setComment().

void H5::H5Location::setComment ( const H5std_string &  name,
const H5std_string &  comment 
) const

References setComment().

void H5::H5Location::setComment ( const char *  comment) const

References getId().

void H5::H5Location::setComment ( const H5std_string &  comment) const

References setComment().


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


The HDF Group Help Desk:
  Copyright by The HDF Group
and the Board of Trustees of the University of Illinois