Just-DataInspector/Utilities/Inc/Utf8Util.hpp

#ifndef __UTF8_UTIL_HPP__
#define __UTF8_UTIL_HPP__

#include <windows.h>

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

namespace jdi
{

	/**
	 * @brief 将 UTF-8 编码的字节序列转换为宽字符串（UTF-16LE）。
	 * @param [IN] text UTF-8 文本起始地址。
	 * @param [IN] length 文本字节数，传入负值表示按 '\0' 结尾自动计算长度。
	 * @return 转换后的宽字符串，输入非法时返回空字符串。
	 */
	std::wstring Utf8ToWide(const char* text, int length = -1);

	/**
	 * @brief 去除字符串首尾的空白字符（含制表、换行与不间断空格）。
	 * @param [IN] text 待处理文本。
	 * @return 去除首尾空白后的新字符串。
	 */
	std::wstring Trim(const std::wstring& text);

	/**
	 * @brief 去除字符串首尾的成对引号（单引号或双引号）。
	 * @param [IN] text 待处理文本。
	 * @return 去除引号后的新字符串。
	 */
	std::wstring StripQuotes(const std::wstring& text);

	/**
	 * @brief 仅针对 ASCII 字母执行小写转换（其余字符原样保留）。
	 * @param [IN] text 待处理文本。
	 * @return 转换后的新字符串。
	 */
	std::wstring ToLowerAscii(const std::wstring& text);

	/**
	 * @brief 判断字符串是否包含指定子串（ASCII 大小写不敏感）。
	 * @param [IN] text 被检索文本。
	 * @param [IN] needle 子串文本。
	 * @return 包含返回 true，否则返回 false。
	 */
	bool ContainsInsensitive(const std::wstring& text, const std::wstring& needle);

	/**
	 * @brief 从字符区间中解析一个双精度浮点数（允许尾部存在非数字残留字符）。
	 * @param [IN] begin 区间起始指针。
	 * @param [IN] end 区间结束指针（不包含）。
	 * @param [OUT] value 解析结果输出。
	 * @return 解析成功返回 true，区间为空或完全无法识别时返回 false。
	 */
	bool TryParseDouble(const char* begin, const char* end, double& value);

	/**
	 * @brief 以固定小数位格式化数值。
	 * @param [IN] value 待格式化数值。
	 * @param [IN] decimals 小数位数。
	 * @return 格式化后的文本。
	 */
	std::wstring FormatNumber(double value, int decimals);

	/**
	 * @brief 把字节数格式化为自适应单位的文本（GB / MB / KB），保留两位小数。
	 *
	 * 单位阀值：1 GB = 1024 MB、1 MB = 1024 KB；小于 1 KB 时也按 KB 显示。
	 * 只输出"数字 + 单位"（如 "1.69 GB"），便于拼接为"已读取 / 总量"。
	 *
	 * @param [IN] bytes 字节数。
	 * @return 形如 "812.34 MB" 的文本。
	 */
	std::wstring FormatByteSize(unsigned long long bytes);

	/**
	 * @brief 以自适应有效位格式化数值（NaN/Inf 会被转换为可读文本）。
	 * @param [IN] value 待格式化数值。
	 * @return 格式化后的文本。
	 */
	std::wstring FormatValue(double value);

	/**
	 * @brief 以**十进制小数**形式格式化数值（**绝不出现科学计数法**）。
	 *
	 * 与 `FormatValue`（`%.6g`）的区别：
	 *  * `FormatValue(1.0e-5)` → `"1e-05"`（科学计数法，不适合显示时间间隔 / 频率）；
	 *  * `FormatDecimal(1.0e-5)` → `"0.00001"`。
	 *
	 * 小数位数按“保留 `significantDigits` 位有效数字”自适应（整数部分超过有效位时取 0 位），
	 * 末尾多余的 0 会被去掉；`-0` 归一成 `0`。
	 *
	 * @param [IN] value 待格式化数值。
	 * @param [IN] significantDigits 期望保留的有效数字位数（1–15，默认 6）。
	 * @return 形如 `0.00001` / `25.641` / `1000000` 的文本。
	 */
	std::wstring FormatDecimal(double value, int significantDigits = 6);

	/**
	 * @brief 以**固定小数位数**格式化数值（绝不出现科学计数法，保留尾随 0）。
	 *
	 * 与 `FormatDecimal` 的区别：后者按「有效数字位数」自适应小数位并去掉尾随 0；
	 * 本函数按**小数位数**精确输出，**保留尾随 0**（用户 2026-11-03 要求：
	 * 「次级单位保留三位小数」，例如 `696.631us`、`700.000us`）。
	 *
	 * 例：`FormatDecimalFixed(0.003696631 * 1e6, 3)` → `"3696.631"`；
	 *     `FormatDecimalFixed(700.0, 3)` → `"700.000"`。
	 *
	 * @param [IN] value 待格式化数值。
	 * @param [IN] decimals 小数位数（0–12，默认 3）。
	 * @return 定点小数文本；NaN/Inf 返回 "NaN"/"+Inf"/"-Inf"。
	 */
	std::wstring FormatDecimalFixed(double value, int decimals = 3);

	/**
	 * @brief 依据坐标轴刻度步长格式化刻度标签。
	 * @param [IN] value 刻度值。
	 * @param [IN] step 刻度步长，用于推断所需小数位。
	 * @return 刻度标签文本。
	 */
	std::wstring FormatTick(double value, double step);

	/**
	 * @brief 将整数格式化为带千位分隔符的文本。
	 * @param [IN] value 待格式化整数。
	 * @return 格式化后的文本。
	 */
	std::wstring FormatCount(unsigned long long value);

	/**
	 * @brief 把时间间隔格式化为「Δt 语义」的复合单位文本（不含 "Δt：" 前缀）。
	 *
	 * 规则（用户明确要求，与双光标差值的显示完全一致）：
	 * - 顶级单位高于 s（即 h / min）时**一路整合到 s**，例如 3662s → "1h 1min 2s"；
	 * - 顶级单位为 s 及以下时，若不是该单位的整数，则**向下一级递进**，
	 *   例如 5.06s → "5s 60ms"；整秒数不加下级单位，例如 5s → "5s"；
	 * - 顶级单位为 ps 时不再递进次级单位，例如 5.123ps → "5.123 ps"。
	 *
	 * @param [IN] seconds 时间间隔（秒）。
	 * @return 形如 "1h 1min 2s" / "5s 60ms" 的间隔文本。
	 */
	std::wstring FormatDurationCompound(double seconds);

	/**
	 * @brief 把时间间隔格式化为「秒」数值文本（不含单位），用于内联编辑。
	 *
	 * 编辑时的量级**始终是秒**：即使显示为 "1h 1min 2s"，进入编辑后也是 3602。
	 *
	 * @param [IN] seconds 时间间隔（秒）。
	 * @return 形如 "3602" 的文本。
	 */
	std::wstring FormatDurationSeconds(double seconds);

	/**
	 * @brief 把频率格式化为带自适应单位的文本（Hz / kHz / MHz / GHz，保留小数）。
	 *
	 * 用于「重采样」面板与派生信号名称（`<原信号> (重采样 1.2 kHz)`）。
	 *
	 * @param [IN] hertz 频率（Hz）。
	 * @return 形如 "1.2 kHz" 的文本；非法值返回 "—"。
	 */
	std::wstring FormatFrequency(double hertz);

	/**
	 * @brief 计算“美观”的坐标轴刻度步长（1/2/5 乘以 10 的整数次幂）。
	 * @param [IN] range 坐标轴数值跨度，必须为正数。
	 * @param [IN] targetTicks 期望的刻度数量。
	 * @return 刻度步长，输入非法时返回 1.0。
	 */
	double NiceStep(double range, int targetTicks);

	/**
	 * @brief 依据范围与步长生成刻度值序列。
	 * @param [IN] minValue 范围下限。
	 * @param [IN] maxValue 范围上限。
	 * @param [IN] step 刻度步长。
	 * @param [OUT] ticks 输出刻度序列（按升序排列）。
	 */
	void BuildTicks(double minValue, double maxValue, double step, std::vector<double>& ticks);

	/**
	 * @brief 将文本复制到系统剪贴板。
	 * @param [IN] owner 剪贴板所有者窗口句柄，允许为空。
	 * @param [IN] text 待复制文本。
	 * @return 复制成功返回 true。
	 */
	bool CopyTextToClipboard(HWND owner, const std::wstring& text);

	/**
	 * @brief 从系统剪贴板读取文本。
	 * @param [IN] owner 剪贴板所有者窗口句柄，允许为空。
	 * @param [OUT] text 读出的文本，剪贴板无文本时清空。
	 * @return 读到非空文本返回 true。
	 */
	bool PasteTextFromClipboard(HWND owner, std::wstring& text);

} // namespace jdi

#endif // __UTF8_UTIL_HPP__