H5::H5Location Class Reference

H5Location is an abstract base class, added in version 1.8.12. More...

#include <H5Location.h>

Inheritance diagram for H5::H5Location:

Public Member Functions
Attribute	createAttribute (const char *name, const DataType &type, const DataSpace &space, const PropList &create_plist=PropList::DEFAULT) const
	Creates an attribute for a group, dataset, or named datatype. More...
Attribute	createAttribute (const H5std_string &name, const DataType &type, const DataSpace &space, const PropList &create_plist=PropList::DEFAULT) const
	This is an overloaded member function, provided for convenience. It differs from the above function in that it takes a reference to an H5std_string for name. More...
Attribute	openAttribute (const char *name) const
	Opens an attribute given its name. More...
Attribute	openAttribute (const H5std_string &name) const
	This is an overloaded member function, provided for convenience. It differs from the above function in that it takes a reference to an H5std_string for name. More...
Attribute	openAttribute (const unsigned int idx) const
	Opens an attribute given its index. 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...
int	getNumAttrs () const
	Returns the number of attributes attached to this HDF5 object. 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...
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...
bool	attrExists (const char *name) const
	Checks whether the named attribute exists at this location. More...
bool	attrExists (const H5std_string &name) const
	This is an overloaded member function, provided for convenience. It differs from the above function in that it takes a reference to an H5std_string for name. More...
void	renameAttr (const char *oldname, const char *newname) const
	Renames the named attribute from this object. More...
void	renameAttr (const H5std_string &oldname, const H5std_string &newname) const
	This is an overloaded member function, provided for convenience. It differs from the above function in that it takes a reference to an H5std_string for the names. More...
void	removeAttr (const char *name) const
	Removes the named attribute from this object. More...
void	removeAttr (const H5std_string &name) const
	This is an overloaded member function, provided for convenience. It differs from the above function in that it takes a reference to an H5std_string for name. 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...
virtual hid_t	getId () const =0
	Returns an identifier. (pure virtual) 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...
IdComponent &	operator= (const IdComponent &rhs)
	Assignment operator. More...
void	setId (const hid_t new_id)
	Sets the identifier of this object to a new value. More...
	IdComponent (const hid_t h5_id)
	Creates an IdComponent object using the id of an existing object. - Obsolete, will be removed in 1.8.17. 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...

Detailed Description

It provides a collection of wrappers for the C functions that take a location identifier to specify the HDF5 object. The location identifier can be either file, group, dataset, or named datatype.

Constructor & Destructor Documentation

H5::H5Location::~H5Location ( )

protectedvirtual

Member Function Documentation

bool H5::H5Location::attrExists

(

const char *

name

)

const

Parameters

name	- IN: Name of the attribute to be queried

Exceptions

H5::AttributeIException

References getId().

Referenced by attrExists().

bool H5::H5Location::attrExists

(

const H5std_string &

name

)

const

References attrExists().

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

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.

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

Referenced by createAttribute().

Attribute H5::H5Location::createAttribute	(	const H5std_string &	name,
		const DataType &	type,
		const DataSpace &	space,
		const PropList &	create_plist = PropList::DEFAULT
	)		const

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::Exception

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

Implemented in H5::DataType, H5::DataSet, H5::H5File, and H5::Group.

Referenced by attrExists(), H5::DataType::commit(), createAttribute(), H5::DataSet::DataSet(), H5::DataType::DataType(), dereference(), flush(), getComment(), getNumAttrs(), getRegion(), H5::Group::Group(), iterateAttrs(), openAttribute(), removeAttr(), removeComment(), renameAttr(), and setComment().

int H5::H5Location::getNumAttrs

(

)

const

Returns

Number of attributes

Exceptions

H5::AttributeIException

References 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
	)

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: http://www.hdfgroup.org/HDF5/doc/RM/RM_H5A.html#Annot-Iterate

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

Attribute H5::H5Location::openAttribute

(

const char *

name

)

const

Parameters

name	- IN: Name of the attribute

Returns

Attribute instance

Exceptions

H5::AttributeIException

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

Referenced by openAttribute().

Attribute H5::H5Location::openAttribute

(

const H5std_string &

name

)

const

References openAttribute().

Attribute H5::H5Location::openAttribute

(

const unsigned int

idx

)

const

Parameters

idx	- IN: Index of the attribute, a 0-based, non-negative integer

Returns

Attribute instance

Exceptions

H5::AttributeIException

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

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

Parameters

name	- IN: Name of the attribute to be removed

Exceptions

H5::AttributeIException

References getId().

Referenced by removeAttr().

void H5::H5Location::removeAttr

(

const H5std_string &

name

)

const

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

Parameters

oldname	- IN: Name of the attribute to be renamed
newname	- IN: New name ame of the attribute

Exceptions

H5::AttributeIException

References getId().

Referenced by renameAttr().

void H5::H5Location::renameAttr	(	const H5std_string &	oldname,
		const H5std_string &	newname
	)		const

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:

• H5Location.h
• H5Location.cpp