图标转换库（iconv-go）技术文档

1. 安装指南

安装方法

本项目主要通过 go get 命令进行安装（命令位于 $GOROOT/bin 目录下）。

go get github.com/djimenez/iconv-go

此命令会从 GitHub 下载并安装包至您的 $GOPATH 目录。如果您已经通过 go get 命令获取过包，但需要重新编译（例如，在新版本的 Go 中），请使用 go install 命令。

go install github.com/djimenez/iconv-go

请查阅 go get 和 go install 的文档以获取更多信息。

注意：由于此包是基于系统中的 libiconv 或 glibc 的 iconv 功能的封装，因此需要启用 cgo。如果禁用 cgo 尝试构建，将会失败。

2. 项目使用说明

导入包

使用此包前，需要添加适当的导入语句：

import (
	'iconv "github.com/djimenez/iconv-go"'
)

字符串转换

字符串转换可以通过两种方法进行。首先，使用 ConvertString 方法：

output, _ := iconv.ConvertString("Hello World!", "utf-8", "windows-1252")

另外，您可以创建一个转换器实例并使用其 ConvertString 方法。当在相同的编码之间进行多次字符串转换时，建议重用转换器实例。

converter := iconv.NewConverter("utf-8", "windows-1252")
output, _ := converter.ConvertString("Hello World!")

// 可以显式关闭转换器，或者在垃圾回收时自动关闭
converter.Close()

ConvertString 可能因以下原因返回错误：

• EINVAL - 当源编码或目标编码不被 iconv 支持
• EILSEQ - 当输入字符串包含给定源编码的无效字节序列

字节切片转换

与字符串转换类似，字节切片转换也有两种方法。首先，使用 Convert 方法：

in := []byte("Hello World!")
out := make([]byte, len(in))

bytesRead, bytesWritten, err := iconv.Convert(in, out, "utf-8", "latin1")

请注意，此方法需要提供输入和输出缓冲区。理想情况下，输出缓冲区的大小应该足以容纳输入转换为的所有字节。如果输出缓冲区大小不足，Convert 将尽可能多地将字节放入缓冲区，而不会创建无效序列。

Convert 可能因以下原因返回错误：

• EINVAL - 当源编码或目标编码不被 iconv 支持
• EILSEQ - 当输入字符串包含给定源编码的无效字节序列
• E2BIG - 当输出缓冲区不足以容纳输入的完整转换

注意：关于基于位移的编码

当使用 iconv.Convert 便捷方法时，它将自动尝试使用空输入来追加到输出缓冲区，以便正确写入任何结束位移序列。但是，使用 Converter.Convert 方法时不会自动执行此操作，因为它可以用于分块处理完整的流。因此，您需要在结束时自己传入一个空输入缓冲区，就像直接使用 iconv 一样。

io.Reader 转换

iconv.Reader 允许将任何其他 *io.Reader 封装，并在读取时将其字节转换。

// 为了简单起见，我们封装了 stdin，但也可以封装文件或网络读取器
reader, _ := iconv.NewReader(os.Stdin, "utf-8", "windows-1252")

io.Writer 转换

iconv.Writer 允许将任何其他 *io.Writer 封装，并在写入时将其字节转换。

// 为了简单起见，我们封装了 stdout，但也可以封装文件或网络写入器
writer, _ := iconv.NewWriter(os.Stdout, "utf-8", "windows-1252")

3. 项目API使用文档

本部分的详细 API 文档将涉及项目中的各个函数和方法，包括但不限于：

• ConvertString 方法
• NewConverter 方法
• Convert 方法
• Reader 封装
• Writer 封装

每个方法和函数的使用说明、参数、返回值以及可能的错误都将详细说明。

4. 项目安装方式

本项目支持以下安装方式：

• 使用 go get 命令
• 使用 go install 命令

请确保您的 Go 开发环境已经配置正确，并遵循上述安装指南。在安装过程中可能会需要系统依赖项，确保您的系统已经安装了必要的库，如 libiconv 或 glibc。