Just-DataInspector/Utilities/Inc/MatH5.hpp

#ifndef __MAT_H5_HPP__
#define __MAT_H5_HPP__

#include <cstdint>
#include <functional>
#include <string>
#include <utility>
#include <vector>

namespace jdi
{

	/**
	 * @brief 只读的 HDF5 子集解析器（用于 MATLAB 7.3 的 `.mat` 文件）。
	 *
	 * MATLAB 7.3（`-v7.3`）的 `.mat` 其实是 **HDF5** 文件：数值矩阵是数据集，
	 * 结构体是分组（字段 = 成员），元信息放在属性里（如 `MATLAB_class`）。
	 * 本项目不引入 HDF5 库，因此这里实现一个**刚好够用**的只读子集：
	 *
	 * * 超级块 v0/v1/v2/v3；
	 * * 对象头 v1（含续块消息），v2 仅识别并跳过；
	 * * 分组成员：符号表（B-tree v1 + 本地堆）与 link 消息两种方式；
	 * * 数据空间 v1/v2、数据类型 v1（整数 / 浮点 / 定长字符串 / 引用 / 复合 / vlen）；
	 * * 数据布局 v3（紧凑 / 连续 / 分块），分块数据集支持 deflate 压缩（zlib）。
	 *
	 * ⚠️ 不支持：外部数据文件、共享消息表、非 deflate 过滤器、极老的 v1 布局。
	 * 这些在 MATLAB 保存的文件里都不出现。
	 */
	class MatHdf5
	{
	public:
		/** @brief 数据类型类别（对应 HDF5 的 class 编号）。 */
		enum class TypeClass : int
		{
			Integer = 0,
			Float = 1,
			Time = 2,
			String = 3,
			Bitfield = 4,
			Opaque = 5,
			Compound = 6,
			Reference = 7,
			Enum = 8,
			VariableLength = 9,
			Array = 10
		};

		/** @brief 数据类型（只保留读取 MATLAB 数据所需的字段）。 */
		struct Type
		{
			TypeClass cls = TypeClass::Opaque;
			int version = 1;
			std::size_t size = 0;		/**< 单个元素占用的字节数。 */
			bool isSigned = false;		/**< 整数是否有符号。 */
			bool bigEndian = false;		/**< 字节序（MATLAB 一律小端）。 */
			bool isVariableString = false;	/**< vlen 字符串。 */
			std::vector<std::pair<std::string, Type>> members;	/**< 复合类型成员。 */
		};

		/** @brief 数据布局。 */
		enum class LayoutClass
		{
			Compact = 0,
			Contiguous = 1,
			Chunked = 2
		};

		/** @brief 一个数据集的定义与数据。 */
		struct Dataset
		{
			std::vector<std::size_t> dims;	/**< 各维长度。 */
			Type type;						/**< 元素类型。 */
			LayoutClass layout = LayoutClass::Compact;
			std::vector<std::uint8_t> data;	/**< 解码后的原始字节（行优先，按 `dims`）。 */
			std::uint64_t chunkAddress = 0;	/**< 分块数据集的 B-tree 地址。 */
			std::vector<std::size_t> chunkDims;
			bool deflate = false;			/**< 是否使用了 deflate（zlib）过滤器。 */
			bool ok = false;
		};

		/** @brief 读文件进度回调：`已读字节 / 总字节`。返回 false 表示请求取消。 */
		using OpenProgress = std::function<bool(std::uint64_t bytesRead, std::uint64_t totalBytes)>;

		/**
		 * @brief 打开文件（一次性读入内存；`.mat` 通常几十 MB，可接受）。
		 *
		 * ⚠️ 按块读取并回调 `progress`：加载遮罩层的"已加载大小 / 总大小 / 百分比"
		 * 全靠它驱动。省略回调时行为不变。
		 * @param [IN] path 文件路径。
		 * @param [OUT] error 失败原因。
		 * @param [IN] progress 读取进度回调（可为空）。
		 * @return 成功返回 true；用户取消时也返回 false。
		 */
		bool Open(const std::wstring& path, std::wstring& error,
		          const OpenProgress& progress = OpenProgress());
		void Close();

		/** @brief 根分组地址。 */
		std::uint64_t Root() const { return m_root; }

		/** @brief 该对象是否为数据集（有数据空间消息）。 */
		bool IsDataset(std::uint64_t address) const;

		/** @brief 分组（或结构体）的成员：`名字 → 对象头地址`。 */
		std::vector<std::pair<std::string, std::uint64_t>> Members(std::uint64_t address) const;

		/** @brief 按名字取成员（不存在返回 0）。 */
		std::uint64_t Member(std::uint64_t address, const std::string& name) const;

		/** @brief 读取数据集定义（含解码后的原始数据）。 */
		bool ReadDataset(std::uint64_t address, Dataset& out) const;

		/** @brief 读取字符串属性（如 `MATLAB_class`、`MATLAB_fields`）。 */
		std::string AttributeString(std::uint64_t address, const char* name) const;

		/** @brief 读取 `char` 数据集为宽字符串（MATLAB 的 char 是 uint16）。 */
		bool ReadText(std::uint64_t address, std::wstring& out) const;

		/** @brief 读取数值数据集为 double 序列。 */
		bool ReadNumbers(std::uint64_t address, std::vector<double>& out) const;

		/** @brief 读取引用数据集（HDF5 对象引用 = 对象头地址，相对基地址）。 */
		bool ReadReferences(std::uint64_t address, std::vector<std::uint64_t>& out) const;

	private:
		struct Message
		{
			std::uint16_t type = 0;
			std::vector<std::uint8_t> data;
		};

		std::uint8_t U8(std::uint64_t offset) const;
		std::uint16_t U16(std::uint64_t offset) const;
		std::uint32_t U32(std::uint64_t offset) const;
		std::uint64_t U64(std::uint64_t offset) const;
		std::uint64_t Addr(std::uint64_t offset) const;
		std::uint64_t Resolve(std::uint64_t address) const;

		void ReadMessages(std::uint64_t address, std::vector<Message>& messages) const;
		bool ParseType(const std::uint8_t* data, std::size_t size, std::size_t offset, Type& out,
		               std::size_t& consumed) const;
		bool DecodeChunked(const Dataset& dataset, std::size_t elementSize,
		                   std::vector<std::uint8_t>& out) const;
		void WalkBtree(std::uint64_t node, std::uint64_t heapData,
		               std::vector<std::pair<std::string, std::uint64_t>>& out) const;
		void WalkSymbolNode(std::uint64_t node, std::uint64_t heapData,
		                    std::vector<std::pair<std::string, std::uint64_t>>& out) const;

		std::vector<std::uint8_t> m_data;
		std::uint64_t m_base = 0;
		std::uint64_t m_root = 0;
		int m_offsetSize = 8;
		int m_lengthSize = 8;
		mutable std::vector<std::pair<std::uint64_t, std::uint64_t>> m_heaps;	/**< 堆地址 → 数据地址。 */
	};

} // namespace jdi

#endif // __MAT_H5_HPP__