6.4.11RENAME

#Syntax

#Description

Rename (or move) an existing HDF5 group, dataset, attribute, (soft) link, or external link named object_name as new_object_name. Multiple groups, datasets, attributes, (soft) links, or external links can be renamed (or moved) at once by separating their names with a comma (,). If new_object_name already exists, it is not overwritten, no subsequent objects are renamed (or moved), and an error is raised. To overwrite an existing object, specify the keyword TRUNCATE (all data stored in the object will be permanently lost). In case (1) a group and an attribute or (2) a dataset and an attribute with identical names (object_name) are stored in the same location (i.e. group) and none of the keywords GROUP, DATASET, or ATTRIBUTE is specified, the object to be renamed is the group or dataset, respectively. To explicitly rename an object according to its type, the keyword GROUP, DATASET, ATTRIBUTE, [SOFT] LINK, or EXTERNAL LINK must be specified. While the renaming (or moving) of groups and datasets to a different location is natively supported by the HDF5 library, this is not the case for attributes; HDFql overcomes this limitation by (1) creating a new attribute with the same characteristics as the existing one (e.g. data type, number of dimensions) using the new specified location and name, (2) writing the data from the existing attribute to the newly created attribute, and (3) deleting the existing attribute.

#Parameter(s)

file_name – optional string that specifies the name of the HDF5 file storing the object to be renamed (or moved). If file_name is specified, the file is opened on the fly, the object is renamed (or moved), and the file is subsequently closed. If not specified, the file currently in use is used instead.

object_name – mandatory string that specifies the name of the object to rename (or move).

new_object_name – mandatory string that specifies the new name and/or location (within the HDF5 file) to use for renaming and/or moving object_name.

#Return

Nothing

#Example(s)

# create two HDF5 groups named "my_group0" and "my_group1" 
CREATE GROUP my_group0, my_group1

# create two HDF5 datasets named "my_dataset" and "my_common" of data type short 
CREATE DATASET my_dataset, my_common AS SMALLINT 

# create two HDF5 attributes named "my_attribute" and "my_common" of data type float 
CREATE ATTRIBUTE my_attribute, my_common AS FLOAT 

# rename an object named "my_group0" as "my_group" (the object "my_group" will not be overwritten if it already exists)
RENAME my_group0 AS my_group

# move an object named "my_group1" into object "my_group" and rename it as "my_subgroup" (the object "my_subgroup" will be overwritten if it already exists in object "my_group")
RENAME TRUNCATE my_group1 AS my_group/my_subgroup

# move two objects named "my_dataset" and "my_attribute" into objects "my_group" and "my_group/my_subgroup", respectively (both objects "my_dataset" and "my_attribute" will not be overwritten if they already exist in objects "my_group" and "my_group/my_subgroup")
RENAME my_dataset, my_attribute AS my_group/, my_group/my_subgroup/

# rename attribute "my_common" as "my_attribute" (the attribute "my_attribute" will not be overwritten if it already exists)
RENAME ATTRIBUTE my_common AS my_attribute

# rename dataset "my_common" as "my_dataset" (the dataset "my_dataset" will not be overwritten if it already exists)
RENAME DATASET my_common AS my_dataset