Just-DataInspector/Utilities/Inc/DataTable.hpp

#ifndef __DATA_TABLE_HPP__
#define __DATA_TABLE_HPP__

#include <cstddef>
#include <functional>
#include <string>
#include <vector>

namespace jdi
{

	/**
	 * @brief 内存中的**列优先**数据表（与具体文件格式无关）。
	 *
	 * 这是「从任意格式读出来的原始格子」：一行是表头，其余是各列的数值。
	 * 它**不是**应用的数据模型（不含时间轴语义、不含信号名规范化），
	 * 只是各格式加载器（CSV / MF4 / 以后更多格式）与数据模型之间的中转结构。
	 *
	 * 采用列优先（每列一整块连续内存）而不是行优先的二维数组，原因有二：
	 * 1. 大型文件（百万行级）若按行存储会产生上百万次独立堆分配，
	 *    每行还要额外承担 vector 的控制块与容量对齐开销，实测内存放大接近 1.5 倍；
	 * 2. 构建信号时可以直接把整列**移动**进 `SignalData`，不再逐元素拷贝。
	 */
	struct DataTable
	{
		std::vector<std::wstring> headers;				/**< 列名（已去除引号与首尾空白）。 */
		std::vector<std::vector<double>> columns;		/**< 列优先数值矩阵：columns[列][行]，缺失处为 NaN。 */
		std::size_t rowCount = 0;						/**< 有效数据行数。 */
		wchar_t delimiter = L',';						/**< 实际使用的分隔符（仅文本格式有意义）。 */
		unsigned long long sourceBytes = 0;				/**< 源文件字节数（用于按比例预留容量）。 */

		/**
		 * @brief 判断解析结果是否包含可用的表格数据。
		 * @return 存在列名且存在数据行时返回 true。
		 */
		bool HasData() const { return !headers.empty() && (rowCount > 0) && (columns.size() >= headers.size()); }
	};

	/**
	 * @brief 加载进度信息。
	 *
	 * 解析阶段会携带真实的"已读 / 总字节数"；列重组与统计阶段没有字节可计，
	 * 此时 `hasBytes` 为 false，界面应只展示百分比。
	 */
	struct LoadProgressInfo
	{
		double ratio = 0.0;					/**< 0-1 总体完成比例。 */
		unsigned long long bytesRead = 0;	/**< 已读取字节数。 */
		unsigned long long totalBytes = 0;	/**< 文件总字节数。 */
		bool hasBytes = false;				/**< 上述字节数字段是否有效。 */
	};

	/**
	 * @brief 加载进度回调。
	 *
	 * 在解析过程中按块回调；返回 false 表示请求取消，解析会尽快停止并返回失败。
	 */
	using LoadProgress = std::function<bool(const LoadProgressInfo& info)>;

	/**
	 * @brief 一组**共享同一时间轴**的数据列（一个「时间轴块」）。
	 *
	 * 一个源文件可以包含多个这样的块：CSV 里每个 `time` 列都会开启一个新块，
	 * MF4 里每个测量通道组（CG）是一个块。块内的各列长度一致（都等于本块的行数）。
	 */
	struct TableBlock
	{
		std::wstring timeHeader;	/**< 本块时间列的列名（原样保留，如 `time`）。 */
		DataTable table;			/**< 本块的列集合（**含**时间列本身）。 */
	};

	/**
	 * @brief 一个源文件加载后的全部内容（可能包含多个时间轴块）。
	 *
	 * ⚠️ 这是「加载器 → 数据模型」的唯一接口：加载器只负责把文件读成
	 * `LoadedSource`（纯格子，无应用语义），`BuildSignalGroup` 再把它规范化为
	 * `SignalGroup`（含时间轴去重、信号命名、调色板等应用语义）。
	 * 新增文件格式时**只需新增一个加载器**，数据模型与界面代码完全不用改。
	 */
	struct LoadedSource
	{
		std::wstring sourceName;				/**< 源文件名（不含目录，含扩展名）。 */
		std::vector<TableBlock> blocks;			/**< 时间轴块集合（至少一个）。 */

		/** @brief 是否包含可用的数据。 */
		bool HasData() const
		{
			for (const TableBlock& block : blocks)
			{
				if (block.table.HasData())
				{
					return true;
				}
			}
			return false;
		}
	};

} // namespace jdi

#endif // __DATA_TABLE_HPP__