6.4.16DROP

#Syntax

#Description

Drop (i.e. delete) an existing HDF5 group, dataset, attribute, (soft) link, or external link named object_name. Multiple groups, datasets, attributes, (soft) links, or external links can be dropped at once by separating their names with a comma (,). If object_name was not found or could not be dropped (due to unknown/unexpected reasons), no subsequent objects are dropped, and an error is raised. 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 dropped is the group or dataset, respectively. To explicitly drop an object according to its type, the keyword GROUP, DATASET, ATTRIBUTE, [SOFT] LINK, or EXTERNAL LINK must be specified. In case the keyword LIKE is specified, only objects with names complying with a regular expression named regular_expression will be dropped (in HDFql, regular expressions are the ones specified by PCRE, which closely follows Perl 5 syntax – please refer to https://www.pcre.org and https://perldoc.perl.org/perlre for additional information). As a general rule, in case regular_expression contains spaces or special characters, it should be enclosed in double quotes (“). Otherwise, if it is not enclosed in double quotes, objects are not dropped, and an error is raised. If regular_expression includes “**”, a recursive search is performed (i.e. HDFql will search in all existing groups and subgroups for objects to drop). If object_name is specified, the recursive search starts from within object_name, which is assumed to be a group or a dataset. To limit the recursiveness, the keyword DEEP may be specified along with a value deep_value that represents the maximum recursiveness limit.

#Parameter(s)

file_name – optional string that specifies the name of the HDF5 file storing the object to be dropped (i.e. deleted). If file_name is specified, the file is opened on the fly, the object is dropped, 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 drop (i.e. delete).

regular_expression – optional string that specifies the regular expression with which the names of objects must comply for those objects to be dropped. If regular_expression includes “**”, a recursive search is performed.

deep_value – optional integer that specifies the maximum recursiveness limit (i.e. how deep the recursive search is performed). If deep_value is specified, it must be equal to or greater than 0 (otherwise an error is raised).

#Return

Nothing

#Example(s)

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

# create two HDF5 datasets named "my_dataset0" and "my_dataset1" of data type short in group "my_group2"
CREATE DATASET my_group2/my_dataset0, my_group2/my_dataset1 AS SMALLINT 

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

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

# drop (i.e. delete) an object named "my_group0" (and all objects that may eventually be stored in it)
DROP my_group0

# drop (i.e. delete) attribute "my_common" 
DROP ATTRIBUTE my_common

# drop (i.e. delete) all existing datasets in group "my_group2" (should drop "my_dataset2" and "my_dataset3")
DROP DATASET my_group2/

# drop (i.e. delete) all existing groups (should drop "my_group1" and "my_group2") 
DROP GROUP

# drop (i.e. delete) all existing objects (should drop "my_dataset2", "my_common", and "my_attribute0")
DROP /