|
HDF5 documents and links Introduction to HDF5 HDF5 User Guide |
And in this document, the
HDF5 Reference Manual
H5 H5A H5D H5E H5F H5G H5I H5P H5R H5S H5T H5Z Tools Datatypes |
The C Interfaces:
The FORTRAN90 Interfaces:
In general, each FORTRAN90 subroutine performs exactly the same task
as the corresponding C function. The links below go to the C function
descriptions, which serve as general descriptions for both. A button,
under Non-C API(s) at the end of the C function description,
opens an external browser window displaying the FORTRAN90-specific
information. You will probably want to adjust the size and location of
this external window so that both browser windows are visible and to
facilitate moving easily between them.
H5Screate(H5S_class_t type)
H5Screate creates a new dataspace of a particular
type.
The types currently supported are H5S_SCALAR and
H5S_SIMPLE;
others are planned to be added later.
type
H5Screate_simple(int rank,
const hsize_t * dims,
const hsize_t * maxdims
)
H5Screate_simple creates a new simple dataspace
and opens it for access.
rank is the number of dimensions used in the dataspace.
dims is an array specifying the size of each dimension
of the dataset while
maxdims is an array specifying the upper limit on
the size of each dimension.
maxdims may be the null pointer, in which case the
upper limit is the same as dims.
If an element of maxdims is
H5S_UNLIMITED, (-1),
the maximum size of the corresponding dimension is unlimited.
Otherwise, no element of maxdims should be
smaller than the corresponding element of dims.
The dataspace identifier returned from this function must be
released with H5Sclose or resource leaks will occur.
rank
dims
maxdims
H5Scopy(hid_t space_id
)
H5Scopy creates a new dataspace which is an exact
copy of the dataspace identified by space_id.
The dataspace identifier returned from this function should be
released with H5Sclose or resource leaks will occur.
space_id
H5Sselect_elements(hid_t space_id,
H5S_seloper_t op,
const size_t num_elements,
const hssize_t *coord[ ]
)
H5Sselect_elements selects array elements to be
included in the selection for the space_id
dataspace. The number of elements selected must be set with
the num_elements. The coord array
is a two-dimensional array of size dataspace rank
by num_elements (ie. a list of coordinates in
the array). The order of the element coordinates in the
coord array also specifies the order in which
the array elements are iterated through when I/O is performed.
Duplicate coordinate locations are not checked for.
The selection operator op determines how the
new selection is to be combined with the previously existing
selection for the dataspace.
The following operators are supported:
H5S_SELECT_SET
| Replaces the existing selection with the parameters from this call. Overlapping blocks are not supported with this operator. Adds the new selection to the existing selection. |
H5S_SELECT_APPEND
| Adds the new selection following the last element of the existing selection. |
H5S_SELECT_PREPEND
| Adds the new selection preceding the first element of the existing selection. |
space_id
op
num_elements
coord[ ]
H5Sselect_all(hid_t space_id)
H5Sselect_all selects the entire extent
of the dataspace space_id.
More specifically, H5Sselect_all selects
the special 5S_SELECT_ALL region for the dataspace
space_id. H5S_SELECT_ALL selects the
entire dataspace for any dataspace it is applied to.
space_id
H5Sselect_none(hid_t space_id)
H5Sselect_none resets the selection region
for the dataspace space_id to include no elements.
space_id
H5Sselect_valid(hid_t space_id)
H5Sselect_valid verifies that the selection
for the dataspace space_id is within the extent
of the dataspace if the current offset for the dataspace is used.
space_id
TRUE,
if the selection is contained within the extent
or 0 (zero), for FALSE, if it is not.
Returns a negative value on error conditions
such as the selection or extent not being defined.
H5Sget_simple_extent_npoints(hid_t space_id)
H5Sget_simple_extent_npoints determines the number of elements
in a dataspace. For example, a simple 3-dimensional dataspace
with dimensions 2, 3, and 4 would have 24 elements.
space_id
H5Sget_select_npoints(hid_t space_id)
H5Sget_select_npoints determines the number of elements
in the current selection of a dataspace.
space_id
H5Sget_simple_extent_ndims(hid_t space_id)
H5Sget_simple_extent_ndims determines the dimensionality (or rank)
of a dataspace.
space_id
H5Sget_simple_extent_dims(hid_t space_id,
hsize_t *dims,
hsize_t *maxdims
)
H5Sget_simple_extent_dims returns the size and maximum sizes
of each dimension of a dataspace through the dims
and maxdims parameters.
Either or both of dims and maxdims
may be NULL.
If a value in the returned array maxdims is
H5S_UNLIMITED (-1),
the maximum size of that dimension is unlimited.
space_id
dims
maxdims
H5Sget_simple_extent_type(hid_t space_id)
H5Sget_simple_extent_type queries a dataspace to determine the
current class of a dataspace.
The function returns a class name, one of the following:
H5S_SCALAR,
H5S_SIMPLE, or
H5S_NONE.
space_id
H5Sset_extent_simple(hid_t space_id,
int rank,
const hsize_t *current_size,
const hsize_t *maximum_size
)
H5Sset_extent_simple sets or resets the size of
an existing dataspace.
rank is the dimensionality, or number of
dimensions, of the dataspace.
current_size is an array of size rank
which contains the new size of each dimension in the dataspace.
maximum_size is an array of size rank
which contains the maximum size of each dimension in the
dataspace.
Any previous extent is removed from the dataspace, the dataspace
type is set to H5S_SIMPLE, and the extent is set as
specified.
space_id
rank
current_size
maximum_size
H5Sis_simple(hid_t space_id)
H5Sis_simple determines whether a dataspace is
a simple dataspace. [Currently, all dataspace objects are simple
dataspaces, complex dataspace support will be added in the future]
space_id
TRUE,
or 0 (zero), for FALSE.
Otherwise returns a negative value.
H5Soffset_simple(hid_t space_id,
const hssize_t *offset
)
H5Soffset_simple sets the offset of a
simple dataspace space_id. The offset
array must be the same number of elements as the number of
dimensions for the dataspace. If the offset
array is set to NULL, the offset for the dataspace
is reset to 0.
This function allows the same shaped selection to be moved to different locations within a dataspace without requiring it to be redefined.
space_id
offset
H5Sextent_copy(hid_t dest_space_id,
hid_t source_space_id
)
H5Sextent_copy copies the extent from
source_space_id to dest_space_id.
This action may change the type of the dataspace.
dest_space_id
source_space_id
H5Sset_extent_none(hid_t space_id)
H5Sset_extent_none removes the extent from
a dataspace and sets the type to H5S_NO_CLASS.
space_id
H5Sselect_hyperslab(hid_t space_id,
H5S_seloper_t op,
const hssize_t *start,
const hsize_t *stride,
const hsize_t *count,
const hsize_t *block
)
H5Sselect_hyperslab selects a hyperslab region
to add to the current selected region for the dataspace
specified by space_id.
The start, stride, count,
and block arrays must be the same size as the rank
of the dataspace.
The selection operator op determines how the new
selection is to be combined with the already existing selection
for the dataspace.
The following operators are supported:
H5S_SELECT_SET
| Replaces the existing selection with the parameters from this call. Overlapping blocks are not supported with this operator. |
H5S_SELECT_OR
| Adds the new selection to the existing selection. (Binary OR) |
H5S_SELECT_AND
| Retains only the overlapping portions of the new selection and the existing selection. (Binary AND) |
H5S_SELECT_XOR
| Retains only the elements that are members of the new selection or the existing selection, excluding elements that are members of both selections. (Binary exclusive-OR, XOR) |
H5S_SELECT_NOTB
| Retains only elements of the existing selection that are not in the new selection. |
H5S_SELECT_NOTA
| Retains only elements of the new selection that are not in the existing selection. |
The start array determines the starting coordinates
of the hyperslab to select.
The stride array chooses array locations
from the dataspace with each value in the stride
array determining how many elements to move in each dimension.
Setting a value in the stride array to 1 moves to
each element in that dimension of the dataspace; setting a value
of 2 in alocation in the stride array
moves to every other element in that dimension of the dataspace.
In other words, the stride determines the
number of elements to move from the start location
in each dimension.
Stride values of 0 are not allowed.
If the stride parameter is NULL,
a contiguous hyperslab is selected (as if each value in the
stride array were set to all 1's).
The count array determines how many blocks to
select from the dataspace, in each dimension.
The block array determines
the size of the element block selected from the dataspace.
If the block parameter is set to NULL,
the block size defaults to a single element in each dimension
(as if the block array were set to all
1's).
For example, in a 2-dimensional dataspace, setting
start to [1,1],
stride to [4,4],
count to [3,7], and
block to [2,2]
selects 21 2x2 blocks of array elements starting with
location (1,1) and selecting blocks at locations
(1,1), (5,1), (9,1), (1,5), (5,5), etc.
Regions selected with this function call default to C order iteration when I/O is performed.
space_id
op
start
count
stride
block
H5Sget_select_hyper_nblocks(hid_t space_id
)
H5Sget_select_hyper_nblocks returns the
number of hyperslab blocks in the current dataspace selection.
space_id
H5Sget_select_hyper_blocklist(hid_t space_id,
hsize_t startblock,
hsize_t numblocks,
hsize_t *buf
)
H5Sget_select_hyper_blocklist returns a list of
the hyperslab blocks currently selected. Starting with the
startblock-th block in the list of blocks,
numblocks blocks are put into the user's buffer.
If the user's buffer fills up before numblocks
blocks are inserted, the buffer will contain only as many
blocks as fit.
The block coordinates have the same dimensionality (rank)
as the dataspace they are located within. The list of blocks
is formatted as follows:
<"start" coordinate>, immediately followed by
<"opposite" corner coordinate>, followed by
the next "start" and "opposite" coordinates,
etc.
until all of the selected blocks have been listed.
No guarantee is implied as the order in which blocks are listed.
space_id
startblock
numblocks
buf
H5Sget_select_elem_npoints(hid_t space_id
)
H5Sget_select_elem_npoints returns
the number of element points in the current dataspace selection.
space_id
H5Sget_select_elem_pointlist(hid_t space_id,
hsize_t startpoint,
hsize_t numpoints,
hsize_t *buf
)
H5Sget_select_elem_pointlist returns the list of
element points in the current dataspace selection. Starting with
the startpoint-th point in the list of points,
numpoints points are put into the user's buffer.
If the user's buffer fills up before numpoints
points are inserted, the buffer will contain only as many
points as fit.
The element point coordinates have the same dimensionality (rank)
as the dataspace they are located within. The list of element points
is formatted as follows:
<coordinate>, followed by
the next coordinate,
etc.
until all of the selected element points have been listed.
The points are returned in the order they will be iterated through when the selection is read/written from/to disk.
space_id
startpoint
numpoints
buf
H5Sget_select_bounds(hid_t space_id,
hssize_t *start,
hssize_t *end
)
H5Sget_select_bounds retrieves the coordinates of
the bounding box containing the current selection and places
them into user-supplied buffers.
The start and end buffers must be large
enough to hold the dataspace rank number of coordinates.
The bounding box exactly contains the selection. I.e., if a 2-dimensional element selection is currently defined as containing the points (4,5), (6,8), and (10,7), then the bounding box will be (4, 5), (10, 8).
The bounding box calculation includes the current offset of the selection within the dataspace extent.
Calling this function on a none selection will
return FAIL.
space_id
start
end
H5Sget_select_type(hid_t space_id)
H5Sget_select_type retrieves the
type of selection currently defined for the dataspace
space_id.
space_id
H5S_sel_type,
if successful.
Valid return values are as follows:
H5S_SEL_NONE
| No selection is defined. |
H5S_SEL_POINTS
| A sequence of points is selected. |
H5S_SEL_HYPERSLABS
| A hyperslab or compound hyperslab is selected. |
H5S_SEL_ALL
| The entire dataset is selected. |
H5Sclose(hid_t space_id
)
H5Sclose releases a dataspace.
Further access through the dataspace identifier is illegal.
Failure to release a dataspace with this call will
result in resource leaks.
space_id
|
HDF5 documents and links Introduction to HDF5 HDF5 User Guide |
And in this document, the
HDF5 Reference Manual
H5 H5A H5D H5E H5F H5G H5I H5P H5R H5S H5T H5Z Tools Datatypes |