Dataspace

A dataspace defines the size and the shape of a Dataset or an Attribute, and is also used for selecting a subset of a dataset.

Usage

The following functions have methods defined for Dataspace objects

• ==
• ndims
• size
• length
• isempty
• isnull

dataspace(obj::Union{Attribute, Dataset, Dataspace})

The Dataspace of obj.

dataspace(data)

Constructs an appropriate Dataspace for representing a Julia object data.

• strings or numbers: a scalar Dataspace
• arrays: a simple Dataspace
• struct types: a scalar Dataspace
• nothing or an EmptyArray: a null dataspace

HDF5.UNLIMITED

A sentinel value which indicates an unlimited dimension in a Dataspace.

Can be used as an entry in the max_dims argument in the Dataspace constructor or create_dataset, or as a count argument in BlockRange when selecting virtual dataset mappings.

isnull(dspace::Union{HDF5.Dataspace, HDF5.Dataset, HDF5.Attribute})

Determines whether the given object has no size (consistent with the API.H5S_NULL dataspace).

Examples

julia> HDF5.isnull(Dataspace(nothing))
true

julia> HDF5.isnull(Dataspace(()))
false

julia> HDF5.isnull(Dataspace((0,)))
false

HDF5.get_extent_dims(obj::Union{HDF5.Dataspace, HDF5.Dataset, HDF5.Attribute}) -> dims, maxdims

Get the array dimensions from a dataspace, dataset, or attribute and return a tuple of dims and maxdims.

HDF5.set_extent_dims(dspace::HDF5.Dataspace, new_dims::Dims, max_dims::Union{Dims,Nothing} = nothing)

Change the dimensions of a dataspace dspace to new_dims, optionally with the maximum possible dimensions max_dims different from the active size new_dims. If not given, max_dims is set equal to new_dims.

HDF5.set_extent_dims(dset::HDF5.Dataset, new_dims::Dims)

Change the current dimensions of a dataset to new_dims, limited by max_dims = get_extent_dims(dset)[2]. Reduction is possible and leads to loss of truncated data.

HDF5.BlockRange(;start::Integer, stride::Integer=1, count::Integer=1, block::Integer=1)

A BlockRange represents a selection along a single dimension of a HDF5 hyperslab. It is similar to a Julia range object, with some extra features for selecting multiple contiguous blocks.

• start: the index of the first element in the first block (1-based).

• stride: the step between the first element of each block (must be >0)

• count: the number of blocks. Can be HDF5.UNLIMITED for an unlimited number of blocks (e.g. for a virtual dataset mapping).

• block: the number of elements in each block.

External links

• HDF5 User Guide, section 7.4.2.1 "Selecting Hyperslabs"

HDF5.BlockRange(obj::Union{Integer, OrdinalRange})

Convert obj to a BlockRange object.

HDF5.select_hyperslab!(dspace::Dataspace, [op, ], idxs::Tuple)

Selects a hyperslab region of the dspace. idxs should be a tuple of integers, ranges or BlockRange objects.

• op determines how the new selection is to be combined with the already selected dataspace:
  • :select (default): replace the existing selection with the new selection.
  • :or: adds the new selection to the existing selection. Aliases: |, ∪, union.
  • :and: retains only the overlapping portions of the new and existing selection. Aliases: &, ∩, intersect.
  • :xor: retains only the elements that are members of the new selection or the existing selection, excluding elements that are members of both selections. Aliases: ⊻, xor
  • :notb: retains only elements of the existing selection that are not in the new selection. Alias: setdiff.
  • :nota: retains only elements of the new selection that are not in the existing selection.

HDF5.get_regular_hyperslab(dspace)::Tuple

Get the hyperslab selection from dspace. Returns a tuple of BlockRange objects.

HDF5.is_selection_valid(dspace::HDF5.Dataspace)

Determines whether the selection is valid for the extent of the dataspace.