Hdf5Util.hpp

Go to the documentation of this file.

// SPDX-License-Identifier: Apache-2.0
//
// Copyright 2026 Caleb Buahin
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//     http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.


 
#ifndef OPENSWMM_HDF5_UTIL_HPP
#define OPENSWMM_HDF5_UTIL_HPP
 
#include <hdf5.h>
 
#include <cstdint>
#include <string>
#include <vector>
 
namespace openswmm::h5io {

class Handle {
public:
    enum class Kind { File, Group, Dataset, Space, Type, Attr, Plist };

    Handle() = default;
    Handle(hid_t id, Kind kind) : id_(id), kind_(kind) {}
    Handle(const Handle&) = delete;
    Handle& operator=(const Handle&) = delete;
    Handle(Handle&& o) noexcept : id_(o.id_), kind_(o.kind_) { o.id_ = -1; }
    Handle& operator=(Handle&& o) noexcept {
        if (this != &o) {
            close();
            id_ = o.id_;
            kind_ = o.kind_;
            o.id_ = -1;
        }
        return *this;
    }

    ~Handle() { close(); }

    hid_t get() const noexcept { return id_; }
    bool ok() const noexcept { return id_ >= 0; }
    explicit operator bool() const noexcept { return ok(); }


    void close() noexcept;
 
private:
    hid_t id_ = -1;
    Kind kind_ = Kind::File;
};


Handle make_string_type();


Handle open_file_readonly(const std::string& path);


std::string column_units(hid_t group, const std::string& column);


Handle make_group(hid_t loc, const std::string& name);
Handle open_group(hid_t loc, const std::string& name);


bool has_link(hid_t loc, const std::string& name);
 
// ---------------------------------------------------------------------------
// Attributes — scalars on a group or on the file root.
// ---------------------------------------------------------------------------
bool write_attr(hid_t loc, const std::string& name, const std::string& value);
bool write_attr(hid_t loc, const std::string& name, double value);
bool write_attr(hid_t loc, const std::string& name, int value);

bool read_attr(hid_t loc, const std::string& name, std::string& out);
bool read_attr(hid_t loc, const std::string& name, double& out);
bool read_attr(hid_t loc, const std::string& name, int& out);
 
// ---------------------------------------------------------------------------
// Columns — equal-length 1-D datasets inside a group.
//
// `units` and `description` ride along as dataset attributes so the file
// explains itself without this repository (STRATEGY.md §2). Pass an empty
// string to omit either.
//
// An EMPTY column is still written, as a zero-length dataset: a group whose
// columns disagree on length is the one corruption a columnar reader cannot
// recover from, so shape is always explicit.
// ---------------------------------------------------------------------------
bool write_column(hid_t group, const std::string& name, const std::vector<double>& values,
                  const std::string& units = "", const std::string& description = "",
                  int compression = 4);

bool write_column(hid_t group, const std::string& name, const std::vector<int>& values,
                  const std::string& units = "", const std::string& description = "",
                  int compression = 4);

bool write_column(hid_t group, const std::string& name, const std::vector<std::string>& values,
                  const std::string& description = "", int compression = 4);

bool read_column(hid_t group, const std::string& name, std::vector<double>& out);
bool read_column(hid_t group, const std::string& name, std::vector<int>& out);
bool read_column(hid_t group, const std::string& name, std::vector<std::string>& out);


std::size_t column_length(hid_t group, const std::string& probe);
 
} // namespace openswmm::h5io
 
#endif // OPENSWMM_HDF5_UTIL_HPP