#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 将宽字符串（UTF-16LE）转换为 UTF-8 编码的字节序列。
	 * @param [IN] text 宽字符文本起始地址。
	 * @return 转换后的 UTF-8 字符串，输入非法时返回空字符串。
	 */
	std::string WideToUtf8(const wchar_t* text);

	/**
	 * @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 判断字符串是否以指定前缀开头。
	 * @param [IN] text 被检索文本。
	 * @param [IN] prefix 前缀文本。
	 * @return 以该前缀开头返回 true，否则返回 false。
	 */
	bool StartsWith(const std::wstring& text, const std::wstring& prefix);

	/**
	 * @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 以自适应有效位格式化数值（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 计算“美观”的坐标轴刻度步长（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__