![]() |
HDF5
1.15.0.1fd82ab
API Reference
|
Creating and manipulating HDF5 datasets that are associated with the dimension of another HDF5 dataset (H5DS)
Functions | |
H5_HLDLL herr_t | H5DSwith_new_ref (hid_t obj_id, hbool_t *with_new_ref) |
Determines if new references are used with dimension scales. More... | |
H5_HLDLL herr_t | H5DSattach_scale (hid_t did, hid_t dsid, unsigned int idx) |
Attach dimension scale dsid to dimension idx of dataset did. More... | |
H5_HLDLL herr_t | H5DSdetach_scale (hid_t did, hid_t dsid, unsigned int idx) |
Detach dimension scale dsid from the dimension idx of dataset did . More... | |
H5_HLDLL herr_t | H5DSset_scale (hid_t dsid, const char *dimname) |
Convert dataset dsid to a dimension scale, with optional name, dimname . More... | |
H5_HLDLL int | H5DSget_num_scales (hid_t did, unsigned int idx) |
Determines how many Dimension Scales are attached to dimension idx of did . More... | |
H5_HLDLL herr_t | H5DSset_label (hid_t did, unsigned int idx, const char *label) |
Set label for the dimension idx of did to the value label . More... | |
H5_HLDLL ssize_t | H5DSget_label (hid_t did, unsigned int idx, char *label, size_t size) |
Read the label for dimension idx of did into buffer label . More... | |
H5_HLDLL ssize_t | H5DSget_scale_name (hid_t did, char *name, size_t size) |
Retrieves name of scale did into buffer name . More... | |
H5_HLDLL htri_t | H5DSis_scale (hid_t did) |
Determines whether did is a Dimension Scale. More... | |
H5_HLDLL herr_t | H5DSiterate_scales (hid_t did, unsigned int dim, int *idx, H5DS_iterate_t visitor, void *visitor_data) |
Iterates the operation visitor through the scales attached to dimension dim . More... | |
H5_HLDLL htri_t | H5DSis_attached (hid_t did, hid_t dsid, unsigned int idx) |
Report if dimension scale dsid is currently attached to dimension idx of dataset did . More... | |
Attach dimension scale dsid
to dimension idx
of dataset did.
[in] | did | The dataset |
[in] | dsid | The scale to be attached |
[in] | idx | The dimension of did that dsid is associated with |
Define Dimension Scale dsid
to be associated with dimension idx
of dataset did
.
Entries are created in the DIMENSION_LIST and REFERENCE_LIST attributes, as defined in section 4.2 of HDF5 Dimension Scale Specification.
Fails if:
dsid
is not a Dimension Scaledid
is a Dimension Scale (A Dimension Scale cannot have scales.)dsid
can be attached to the same dimension more than once, which has no effect. Detach dimension scale dsid
from the dimension idx
of dataset did
.
[in] | did | The dataset |
[in] | dsid | The scale to be detached |
[in] | idx | The dimension of did to detach |
If possible, deletes association of Dimension Scale dsid
with dimension idx
of dataset did
. This deletes the entries in the DIMENSION_LIST and REFERENCE_LIST attributes, as defined in section 4.2 of HDF5 Dimension Scale Specification.
Fails if:
did
or dsid
do not existdsid
is not a Dimension Scaledsid
is not attached to did
did
. Read the label for dimension idx
of did
into buffer label
.
[in] | did | The dataset |
[in] | idx | The dimension |
[out] | label | The label |
[in] | size | The length of the label buffer |
Returns the value of the DIMENSION_LABELS for dimension idx
of dataset did
, if set. Up to size
characters of the name are copied into the buffer label
. If the label is longer than size
, it will be truncated to fit. The parameter size
is set to the size of the returned label
.
If did
has no label, the return value of label
is NULL.
Fails if:
H5_HLDLL int H5DSget_num_scales | ( | hid_t | did, |
unsigned int | idx | ||
) |
Determines how many Dimension Scales are attached to dimension idx
of did
.
[in] | did | The dataset to query |
[in] | idx | The dimension of did to query |
did
, if successful, otherwise returns a negative value.H5DSget_num_scales() determines how many Dimension Scales are attached to dimension idx
of dataset did
.
Retrieves name of scale did
into buffer name
.
[in] | did | Dimension scale identifier |
[out] | name | Buffer to contain the returned name |
[in] | size | Size in bytes, of the name buffer |
H5DSget_scale_name() retrieves the name attribute for scale did
.
Up to size
characters of the scale name are returned in name
; additional characters, if any, are not returned to the user application.
If the length of the name, which determines the required value of size
, is unknown, a preliminary H5DSget_scale_name() call can be made by setting name
to NULL. The return value of this call will be the size of the scale name; that value plus one (1) can then be assigned to size
for a second H5DSget_scale_name() call, which will retrieve the actual name. (The value passed in with the parameter size
must be one greater than size in bytes of the actual name in order to accommodate the null terminator; if size
is set to the exact size of the name, the last byte passed back will contain the null terminator and the last character will be missing from the name passed back to the calling application.)
Report if dimension scale dsid
is currently attached to dimension idx
of dataset did
.
[in] | did | The dataset |
[in] | dsid | The scale to be attached |
[in] | idx | The dimension of did that dsid is associated with |
Report if dimension scale dsid
is currently attached to dimension idx
of dataset did
.
Fails if:
dsid
is not a Dimension Scaledsid
is not a Dimension Scaledid
is a Dimension Scale (A Dimension Scale cannot have scales.) Determines whether did
is a Dimension Scale.
[in] | did | The dataset to query |
H5DSis_scale() determines if did
is a Dimension Scale, i.e., has class="DIMENSION_SCALE").
H5_HLDLL herr_t H5DSiterate_scales | ( | hid_t | did, |
unsigned int | dim, | ||
int * | idx, | ||
H5DS_iterate_t | visitor, | ||
void * | visitor_data | ||
) |
Iterates the operation visitor through the scales attached to dimension dim
.
[in] | did | The dataset |
[in] | dim | The dimension of dataset did |
[in,out] | idx | Input the index to start iterating, output the next index to visit. If NULL, start at the first position. |
[in] | visitor | The visitor function |
[in] | visitor_data | Arbitrary data to pass to the visitor function |
H5DSiterate_scales() iterates over the scales attached to dimension dim
of dataset did
. For each scale in the list, the visitor_data
and some additional information, specified below, are passed to the visitor
function. The iteration begins with the idx
object in the group and the next element to be processed by the operator is returned in idx
. If idx
is NULL, then the iterator starts at the first group member; since no stopping point is returned in this case, the iterator cannot be restarted if one of the calls to its operator returns non-zero.
The prototype for H5DS_iterate_t is:
The operation receives the Dimension Scale dataset identifier, scale
, and the pointer to the operator data passed in to H5DSiterate_scales(), visitor_data
.
The return values from an operator are:
H5DSiterate_scales() assumes that the scales of the dimension identified by dim
remain unchanged through the iteration. If the membership changes during the iteration, the function's behavior is undefined.
Set label for the dimension idx
of did
to the value label
.
[in] | did | The dataset |
[in] | idx | The dimension |
[in] | label | The label |
Sets the DIMENSION_LABELS for dimension idx
of dataset did
. If the dimension had a label, the new value replaces the old.
Fails if:
Convert dataset dsid
to a dimension scale, with optional name, dimname
.
[in] | dsid | The dataset to be made a Dimemsion Scale |
[in] | dimname | The dimension name (optional), NULL if the dimension has no name. |
The dataset dsid
is converted to a Dimension Scale dataset, as defined above. Creates the CLASS attribute, set to the value "DIMENSION_SCALE" and an empty REFERENCE_LIST attribute, as described in HDF5 Dimension Scale Specification. (PDF, see section 4.2).
If dimname
is specified, then an attribute called NAME is created, with the value dimname
.
Fails if:
dsid
is already a scaledsid
is a dataset which already has dimension scalesIf the dataset was created with the Table, Image, or Palette interface [9], it is not recommended to convert to a Dimension Scale. (These Datasets will have a CLASS Table, Image, or Palette.)
Determines if new references are used with dimension scales.
[in] | obj_id | Object identifier |
[out] | with_new_ref | New references are used or not |
H5DSwith_new_ref() takes any object identifier and checks if new references are used for dimension scales. Currently, new references are used when non-native VOL connector is used or when H5_DIMENSION_SCALES_WITH_NEW_REF is set up via configure option.