| 1 |
/*! |
| 2 |
@~chinese |
| 3 |
@ingroup dutil |
| 4 |
@file include/util/dtextencoding.h |
| 5 |
@details 本文件包含文本编码识别和文本编码转换的公共接口。 |
| 6 |
|
| 7 |
@class Dtk::Core::DTextEncoding |
| 8 |
@brief 文本编码信息类,提供文本编码识别和文本编码转换的公共接口。 |
| 9 |
@details 提供文本编码识别和文本编码转换的公共接口,默认使用 QTextCodec 进行检测, |
| 10 |
若系统环境中存在 libuchardet.so 及 libicuuc.so 库,可拓展支持的编码格式。 |
| 11 |
|
| 12 |
@fn QByteArray Dtk::Core::DTextEncoding::detectTextEncoding(const QByteArray &content) |
| 13 |
@brief 检测给定文本的编码格式。 |
| 14 |
@details 默认使用 QTextCodec 检测,若系统环境中存在 libuchardet.so 及 libicuuc.so 库,可拓展支持的编码格式。 |
| 15 |
检测会判断最接近的编码格式,未成功识别或为 ASCII 编码格式,将返回 UTF-8 编码格式。 |
| 16 |
@param[in] content 待检测的文本内容 |
| 17 |
@return 文本编码格式 |
| 18 |
|
| 19 |
@fn QByteArray Dtk::Core::DTextEncoding::detectFileEncoding(const QString &fileName, bool *isOk) |
| 20 |
@brief 检测给定文件的文本编码格式,将读取文件头部最多 64KB 的文本用于检测。若文件访问失败,返回空编码格式。 |
| 21 |
@param[in] fileName 文件路径 |
| 22 |
@param[out] isOk 检测是否成功,主要判断文件内容能否正确读取 |
| 23 |
@return 文本编码格式 |
| 24 |
@sa DTextEncoding::detectTextEncoding |
| 25 |
|
| 26 |
@fn bool Dtk::Core::DTextEncoding::convertTextEncoding(QByteArray &content, QByteArray &outContent, const QByteArray &toEncoding, const QByteArray &fromEncoding, QString *errString) |
| 27 |
@brief 将输入的文本 `content` 从 `fromEncoding` 编码格式转换到 `toEncoding` 编码格式,转换后的文本保存到 `outContent` 。 |
| 28 |
若转换过程中出现错误,将返回 false , 并设置 `errString` 错误信息,已转换的文本仍会写入 `outContent` 。 |
| 29 |
@note 当处理大量文本数据时,需考虑并行处理,防止阻塞线程。 |
| 30 |
@param[in] content 传入的文本 |
| 31 |
@param[out] outContent 编码转换后的文本 |
| 32 |
@param[in] toEncoding 转换的编码格式 |
| 33 |
@param[in] fromEncoding 原始的编码格式,默认为空,会通过 `DTextEncoding::detectTextEncoding` 检测编码格式 |
| 34 |
@param[out] errString 错误信息 |
| 35 |
@return 是否转换成功 |
| 36 |
@sa DTextEncoding::convertTextEncodingEx |
| 37 |
|
| 38 |
@fn bool Dtk::Core::DTextEncoding::convertTextEncodingEx(QByteArray &content, QByteArray &outContent, const QByteArray &toEncoding, const QByteArray &fromEncoding, QString *errString, int *convertedBytes) |
| 39 |
@brief 将输入的文本 `content` 从 `fromEncoding` 编码格式转换到 `toEncoding` 编码格式,转换后的文本保存到 `outContent` 。 |
| 40 |
若转换过程中出现错误,将返回 false , 并设置 `errString` 错误信息,已转换的文本仍会写入 `outContent` 。 |
| 41 |
@note 当处理大量文本数据时,需考虑并行处理,防止阻塞线程。 |
| 42 |
@note 返回 false 时,已转换的文本仍会写入 `outContent` ,同时 `convertedBytes` 会记录已转换数据长度,你可以决定保留或移除转换文本。 |
| 43 |
@param[in] content 传入的文本 |
| 44 |
@param[out] outContent 编码转换后的文本 |
| 45 |
@param[in] toEncoding 转换的编码格式 |
| 46 |
@param[in] fromEncoding 原始的编码格式,默认为空,会通过 `DTextEncoding::detectTextEncoding` 检测编码格式 |
| 47 |
@param[out] errString 错误信息 |
| 48 |
@param[out] convertedBytes 已转换的 `content` 数据长度,若转换过程出现错误,这个值会指向异常字符出现的位置 |
| 49 |
@return 是否转换成功 |
| 50 |
|
| 51 |
@fn bool DTextEncoding::convertFileEncoding(const QString &fileName, const QByteArray &toEncoding, const QByteArray &fromEncoding, QString *errString) |
| 52 |
@brief 读取输入的 `fileName` 文件内容,将文件内容从 `fromEncoding` 编码格式转换到 `toEncoding` 编码格式,转换后的文本保存到 `fileName` 。 |
| 53 |
若转换过程中出现错误,将返回 false , 并设置 `errString` 错误信息,已转换的文本会被抛弃。 |
| 54 |
@param[in] fileName 传入及保存的文件路径 |
| 55 |
@param[in] toEncoding 转换的编码格式 |
| 56 |
@param[in] fromEncoding 原始的编码格式,为空时会通过 `DTextEncoding::detectTextEncoding` 检测编码格式 |
| 57 |
@param[out] errString 错误信息 |
| 58 |
@return 是否转换成功 |
| 59 |
@sa DTextEncoding::convertTextEncoding |
| 60 |
|
| 61 |
@fn bool DTextEncoding::convertFileEncodingTo(const QString &fromFile, const QString &toFile, const QByteArray &toEncoding, const QByteArray &fromEncoding, QString *errString) |
| 62 |
@brief 读取输入的 `fromFile` 文件内容,将文件内容从 `fromEncoding` 编码格式转换到 `toEncoding` 编码格式,转换后的文本保存到 `toFile` 。 |
| 63 |
若转换过程中出现错误,将返回 false , 并设置 `errString` 错误信息,已转换的文本会被抛弃。 |
| 64 |
@param[in] fromFile 传入的文件路径 |
| 65 |
@param[in] toFile 保存的文件路径 |
| 66 |
@param[in] toEncoding 转换的编码格式 |
| 67 |
@param[in] fromEncoding 原始的编码格式,为空时会通过 `DTextEncoding::detectTextEncoding` 检测编码格式 |
| 68 |
@param[out] errString 错误信息 |
| 69 |
@return 是否转换成功 |
| 70 |
@sa DTextEncoding::convertTextEncoding |
| 71 |
|
| 72 |
*/ |