iconv - 字符编码转换

孟伟

一、概述

1.1 功能说明

iconv 模块提供字符编码转换功能，支持在不同字符编码格式之间进行转换，如 gb2312/ucs2/ucs2be/utf8。

1.2 主要功能

支持打开不同编码格式的转换句柄
提供编码之间的字符转换能力
支持关闭转换句柄以释放资源

1.3 应用场景

处理不同编码格式的文本数据
与外部系统进行编码兼容的数据交换
多语言环境下的文本处理

二、核心示例

1、核心示例是指：使用本库文件提供的核心 API，开发的基础业务逻辑的演示代码；

2、核心示例的作用是：帮助开发者快速理解如何使用本库，所以核心示例的逻辑都比较简单；

3、更加完整和详细的 demo，请参考此链接中的 demo/iconv

-- Unicode大端编码转换为UTF-8编码_
_function ucs2beToUtf8(ucs2s)_
_    local ic = iconv.open("utf8", "ucs2be")_
_    if not ic then_
_        log.info("iconv", "打开转换句柄失败")_
_        return nil_
_    end_

_    local result = ic:iconv(ucs2s)_
_    iconv.close(ic)_

_    return result_
_end_

_-- 实际使用示例_
_local unicodeStr = "\x00\x41\x00\x42" -- "AB"的UCS2BE编码_
_local utf8Str = ucs2beToUtf8(unicodeStr)_
_if utf8Str then_
_    log.info("iconv", "转换结果:", utf8Str)_
_end

三、常量详解

核心库常量，顾名思义是由合宙 LuatOS 内核固件中定义的、不可重新赋值或修改的固定值，在脚本代码中不需要声明，可直接调用；

每个常量对应的常量取值仅做日志打印时查询使用，不要将这个常量取值用做具体的业务逻辑判断，因为LuatOS内核固件可能会变更每个常量对应的常量取值；

如果用做具体的业务逻辑判断，一旦常量取值发生改变，业务逻辑就会出错；

iconv 核心库没有常量。

四、函数详解

4.1 iconv.open(tocode, fromcode)

功能

打开相应字符编码转换函数

参数

tocode

参数含义：目标编码格式；
数据类型：string；
取值范围："gb2312"/"ucs2"/"ucs2be"/"utf8"；
是否必选：必选；
注意事项：暂无；
参数示例："utf8"

fromcode

参数含义：源编码格式；
数据类型：string；
取值范围："gb2312"/"ucs2"/"ucs2be"/"utf8"；
是否必选：必选；
注意事项：暂无；
参数示例："ucs2be"

返回值

local ic = iconv.open(tocode, fromcode)

有一个返回值 ic

ic

含义说明：成功时返回一个userdata类型的iconv客户端实例对象，该实例对象可用于后续的iconv编码转换操作；
         失败时返回nil；
         实例对象名称并不是固定的ic，可自定义；
数据类型：userdata；
取值范围：成功返回有效的句柄，失败返回nil；
注意事项：暂无；

示例

_-- Unicode大端编码 转化为 utf8编码_
local ic = iconv.open("utf8", "ucs2be")

4.2 ic:iconv(inbuf)

功能

字符编码转换，

注意事项

ic 是由 iconv.open(tocode, fromcode)所返回的实例对象。

参数

inbuf

参数含义：待转换字符串；
数据类型：string；
取值范围：任意字符串；
是否必选：必选；
注意事项：暂无；
参数示例："\x00\x41\x00\x42"

返回值

local result = ic:iconv(inbuf)

有一个返回值 result

result

含义说明：返回编码转换后的结果；
数据类型：string；
取值范围：成功返回转换后的字符串，失败返回nil；
注意事项：暂无；

示例

_-- Unicode大端编码 转化为 utf8编码_
function ucs2beToUtf8(ucs2s)
    local ic = iconv.open("utf8", "ucs2be")
    return ic:iconv(ucs2s)
end

4.3 iconv.close(ic)

功能

关闭字符编码转换

参数

ic

参数含义：iconv.open返回的句柄；
数据类型：userdata；
取值范围：有效的iconv句柄；
是否必选：必选；
注意事项：暂无；
参数示例：local ic = iconv.open("utf8", "ucs2be")

返回值

local success = iconv.close(ic)

有一个返回值 success

success

含义说明：操作是否成功；
数据类型：boolean；
取值范围：成功返回true，失败返回false；
注意事项：暂无；

示例

_-- 关闭字符编码转换_
local ic= iconv.open("utf8", "ucs2be")
iconv.close(ic)

五、产品支持说明

支持 LuatOS 开发的所有产品都支持 iconv 核心库。