#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 依据坐标轴刻度步长格式化刻度标签。
	 * @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 计算“美观”的坐标轴刻度步长（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__