Skip to content

Latest commit

 

History

History

examples

README.md

HDF5 Go Library Examples

This directory contains standalone examples demonstrating the HDF5 Go library features.

Running Examples

Each example is in its own directory with a main.go file. Run them using go run:

# Basic usage example
go run examples/01-basic/main.go

# List objects in HDF5 file
go run examples/02-list-objects/main.go

# Read dataset values
go run examples/03-read-dataset/main.go

# Read variable-length strings
go run examples/04-vlen-strings/main.go

# Comprehensive feature demonstration
go run examples/05-comprehensive/main.go

Or build and run:

cd examples/01-basic
go build
./01-basic   # or 01-basic.exe on Windows

Examples Overview

Each example has its own README.md with detailed explanations, code walkthroughs, and use cases.

01-basic - Basic Usage

Best starting point for new users!

Demonstrates:

  • Opening HDF5 files
  • Reading superblock information
  • Walking file structure
  • Automatic test file generation with Python

📖 Full Documentation →

02-list-objects - File Navigation

Demonstrates:

  • Traversing groups and datasets
  • Reading object hierarchy
  • Walking nested structures
  • Building object indexes

📖 Full Documentation →

03-read-dataset - Dataset Reading

Demonstrates:

  • Reading numeric datasets (floats, integers)
  • Reading matrices (2D data)
  • Reading multiple datasets
  • Getting dataset metadata
  • Data verification

📖 Full Documentation →

04-vlen-strings - Variable-Length Strings

Demonstrates:

  • Reading variable-length strings via Global Heap
  • Global Heap architecture
  • String storage mechanisms
  • Compound types with vlen string members

📖 Full Documentation →

05-comprehensive - Full Feature Demo

Complete demonstration of all library features!

Demonstrates:

  • All superblock versions (0, 2, 3)
  • Object headers (v1 + v2)
  • All group formats
  • All dataset layouts
  • GZIP compression
  • All datatypes
  • Production readiness showcase (~98%)

📖 Full Documentation →

Test Files

Examples expect test HDF5 files in ../../testdata/:

  • v0.h5 - HDF5 version 0 (earliest format)
  • v2.h5 - HDF5 version 2 (1.8.x format)
  • v3.h5 - HDF5 version 3 (latest format)
  • with_groups.h5 - File with nested groups
  • vlen_strings.h5 - File with variable-length strings

Most examples auto-generate test files if Python with h5py is available.

Requirements

  • Go 1.25 or later
  • For test file generation (optional): Python 3 with h5py and numpy

Install Python dependencies:

pip install h5py numpy

Note: Python is optional. You can use your own HDF5 files or download test files.

API Usage Patterns

Opening Files

file, err := hdf5.Open("data.h5")
if err != nil {
    log.Fatal(err)
}
defer file.Close()

Walking File Structure

file.Walk(func(path string, obj hdf5.Object) {
    switch v := obj.(type) {
    case *hdf5.Group:
        fmt.Printf("Group: %s\n", path)
    case *hdf5.Dataset:
        fmt.Printf("Dataset: %s\n", path)
    }
})

Reading Datasets

// Numeric data
values, err := dataset.Read()

// String data
strings, err := dataset.ReadStrings()

// Compound data (structs)
records, err := dataset.ReadCompound()

Building All Examples

From repository root:

make examples

This builds all examples to verify they compile correctly.

Documentation

User Guides

Reference

Last Updated: 2025-10-29 Version: 0.10.0-beta