Frequently Asked Questions

1. How can I use HDF5DotNet to read an HDF5 dataset or attribute of a fixed- or variable-length string type?
2. How can I use HDF5DotNet to read and de-reference HDF5 region references?

The first two questions are related in that it is easy to overestimate what H5D.read can do. It's really just a thinly veiled version of the unmanaged H5Dread function and does not do any type marshalling.

The code snippets are written in IronPython and you shouldn't have much difficulty translating them into your preferred .NET language.

How can I use HDF5DotNet to read an HDF5 dataset or attribute of a fixed- or variable-length string type?

The fixed- and variable-length HDF5 string datatypes have no direct counterpart in the .NET framework. The .NET System.String type is based on sequences of 2-byte System.Char Unicode characters. (The C++/CLI counterpart is wchar_t, not char!) We have to use slightly different methods for reading HDF5 fixed-length and variable-length strings into .NET strings.

Fixed-length HDF5 strings

This case is pretty straightforward. Since we know the length of the HDF5 strings in advance, we can read them into properly sized System.Byte arrays and then use the GetString() method of System.Text.ASCIIEncoding or System.Text.UTF8Encoding (Determine the character set with H5T.get_cset!) to convert System.Byte arrays into .NET strings. Here's an example of how to read a fixed-length ASCII-encoded string attribute:

Variable-length HDF5 strings

With variable-length HDF5 strings matters are a little more subtle. If your gut instinct tells you 'pointer', your are not too far from the solution. As a VB.NET or IronPython user you may ask, 'What's a pointer, Walter?' Although some .NET languages support pointers they are not part of the Common Language Specification (CLS), and, whenever possible, we are trying to provide a solution that plays nice with all .NET languages. A CLS-compliant construct which mimics pointers in .NET languages that otherwise don't support them is System.IntPtr. Instead of allocating an array of System.Byte we allocate an array of System.IntPtr "pointers" and then use PtrToStringAnsi(IntPtr) or PtrToStringUni(IntPtr) in System.Runtime.InteropServices.Marshal to convert them into .NET strings.

How can I use HDF5DotNet to read and de-reference HDF5 region references?

The H5R.dereference method has 3 arguments: an object handle of an HDF5 object from the file containing the referenced object, an indicator whether we are dealing with an object or region reference, and an object that implements the H5R.IReference interface. For region references, we use RegionReference objects. As for strings, H5D.read cannot read references directly into RegionReference objects and we have to read them into an intermediate System.Byte array first. Below is an example of reading and dereferencing an HDF5 region reference.