HDF5

The functions described in this chapter will read or write data to a file in the HDF5 format. These contain datasets together with a set of attributes for each dataset.

Datasets are arranged in a heirarchical name space similar to Unix file system. Each namespace is called a group. Datasets are stored in a group in an area of the file called a dataspace.

Supported Features

• Datasets consisting of a vector ([]i64, []f64, etc).
• Datasets consisting of a 2-d array ([][]u8, [][]i16, etc).
• Datasets consisting of a 3-d array ([][][]u32, [][][]f32, etc).
• Any number of attributes for each dataset (int, []f64, string, etc).Attributes can be scalars or vectors. These are often metadata of the dataset describing how it was acquired or created.

Unsupported Features - Planned

• Writing to groups other than / (which is the default)
• Datasets of arrays of strings.
• Compound data structures (akin to struct).
• Images or tables.
• Compression.
• Distributed datasets (pointers to other HDF5 files).
• Parallel reading or writing.

References and Further Reading

See the HDF5 website for documentation and examples in C or Fortran.

fn open_file(filename string) !Hdf5File

open_file opens an existing HDF5 file.

fn Hdf5File.new(filename string) !Hdf5File

Hdf5File.new creates a new HDF5 file, or truncates an existing file.

struct Hdf5File {
mut:
	filedesc Hdf5HidT
}

fn (f &Hdf5File) write_dataset1d[T](dset_name string, buffer []T) !Hdf5HerrT

write_dataset1d writes a 1-d numeric array (vector) to a named HDF5 dataset in an HDF5 file.

fn (f &Hdf5File) write_dataset2d[T](dset_name string, buffer [][]T) !Hdf5HerrT

write_dataset2d writes a 2-d numeric array to a named HDF5 dataset in an HDF5 file.

Note: creates and deletes a temporary copy of the array.

fn (f &Hdf5File) write_dataset3d[T](dset_name string, buffer [][][]T) !Hdf5HerrT

write_dataset3d writes a numeric 3-d array (layers of 2-d arrays) to a named HDF5 dataset in an HDF5 file.

Note: creates and deletes a temporary copy of the array.

fn (f &Hdf5File) write_attribute1d[T](dset_name string, attr_name string, buffer []T) !Hdf5HerrT

write_attribute1d adds a named 1-d numeric array (vector) attribute to a named HDF5 dataset.

fn (f &Hdf5File) write_attribute[T](dset_name string, attr_name string, buffer T) !Hdf5HerrT

write_attribute adds a named scalar attribute to a named HDF5 dataset. This is a helper function to avoid an array temporary; it writes a single element vector. It also supports writing a string attribute.

fn (f &Hdf5File) read_dataset1d[T](dset_name string, mut dataset []T)

read_dataset1d reads a 1-d numeric array (vector) from a named HDF5 dataset in an HDF5 file. Replaces the value of the array. Maximum dimension is max_i32 or less (this is checked).

fn (f &Hdf5File) read_dataset2d[T](dset_name string, mut dataset [][]T)

read_dataset2d reads a 2-d numeric array from a named HDF5 dataset in an HDF5 file. Replaces the value of the array. Maximum of any dimension is max_i32 or less (this is checked). Maximum total elements is also max_i32.

fn (f &Hdf5File) read_dataset3d[T](dset_name string, mut dataset [][][]T)

read_dataset3d reads a 3-d numeric array from a named HDF5 dataset in an HDF5 file. Replaces the value of the array with correctly dimensioned array. Maximum of any dimension is max_i32 or less (this is checked). Maximum total elements is also max_i32.

fn (f &Hdf5File) read_attribute[T](dset_name string, attr_name string, mut attr_value T) !bool

readattribute gets a named scalar attribute from a named HDF5 dataset. This is a helper function to avoid an array temporary; it gets a single element vector. It also supports reading a string attribute.

fn (f &Hdf5File) read_attribute1d[T](dset_name string, attr_name string, mut attr_value []T) !bool

read_attribute1d reads a 1-d numeric array (vector) from a named HDF5 dataset and named attribute in an HDF5 file. Replaces the value of the given array. Maximum dimension is max_i32 or less (this is checked).

fn (f &Hdf5File) close()

close releases memory resources for HDF5 files.