erlang characters_to_list(Data, InEncoding)用法及代码示例

将可能很深的整数和二进制列表转换为表示 Unicode 字符的整数列表。输入中的二进制文件可以将字符编码为以下之一：

• ISO Latin-1(0-255，每个字节一个字符)。这里，case参数InEncoding被指定为latin1。

• UTF-encodings 之一，指定为参数 InEncoding 。

请注意，列表中的整数始终表示代码点，无论是否传递 InEncoding。如果通过InEncoding latin1，则仅允许代码点<256；否则，允许所有有效的 unicode 代码点。

如果 InEncoding 为 latin1 ，则参数 Data 对应于 iodata() 类型，但对于 unicode ，参数 Data 可以包含大于 255 的整数(超出 ISO Latin-1 范围的 Unicode 字符)，这使得它无效为 iodata() 。

该函数的目的主要是将 Unicode 字符的组合转换为列表表示形式的纯 Unicode 字符串，以便进一步处理。要将数据写入外部实体，请使用反向函数 characters_to_binary/3派上用场了。

选项 unicode 是 utf8 的别名，因为这是二进制文件中 Unicode 字符的首选编码。 utf16 是 {utf16,big} 的别名，utf32 是 {utf32,big} 的别名。原子 big 和 little 表示大端或小端编码。

如果由于列表中的非法 Unicode/ISO Latin-1 字符或由于任何二进制文件中的 UTF 编码无效而无法转换数据，则会返回错误元组。错误元组包含标签 error ，一个表示错误发生之前可以转换的字符的列表，以及包含和之后有问题的整数/字节的字符的表示。最后一部分主要用于调试，因为它仍然构成可能很深或混合的列表，或两者兼而有之，不一定与原始数据具有相同的深度。遍历列表时会发生错误，并且返回需要解码的任何内容"as is"。

但是，如果输入 Data 是纯二进制文件，则错误元组的第三部分也保证是二进制文件。

发生错误的原因如下：

• 整数超出范围。

  如果 InEncoding 是 latin1 ，则只要在列表中找到大于 255 的整数，就会发生错误。

  如果InEncoding是Unicode类型，则只要发现以下任一情况就会发生错误：

  • 整数 > 16#10FFFF(最大 Unicode 字符)

  • 16#D800 到 16#DFFF 范围内的整数(为 UTF-16 代理项对保留的无效范围)

• UTF 编码不正确。

  如果 InEncoding 是 UTF 类型之一，则任何二进制文件中的字节在该编码中都必须有效。

  发生错误的原因有多种，包括：

  • "Pure"解码错误(例如字节的高位错误)。

  • 字节被解码为太大的数字。

  • 这些字节被解码为无效 Unicode 范围内的代码点。

  • 编码是"overlong"，这意味着数字应该用更少的字节进行编码。

  截断的 UTF 的情况会被特殊处理，请参阅下面有关不完整二进制文件的段落。

  如果 InEncoding 是 latin1 ，则二进制文件只要包含整个字节就始终有效，因为每个字节都属于有效的 ISO Latin-1 范围。

一种特殊类型的错误是未找到实际无效整数或字节，但尾随 binary() 包含的字节太少，无法解码最后一个字符。如果从文件中以块的形式读取字节，或者以其他方式在非 UTF 字符边界上分割二进制文件，则可能会发生此错误。然后返回 incomplete 元组而不是 error 元组。它由与 error 元组相同的部分组成，但标记是 incomplete 而不是 error，并且最后一个元素始终保证是由(到目前为止)有效 UTF 字符的第一部分组成的二进制文件。

如果将一个 UTF 字符拆分为 Data 中的两个连续二进制文件，则转换成功。这意味着只要将整个范围指定为输入，就可以从一系列二进制文件中解码字符，而不会发生错误。

例子：

decode_data(Data) ->
   case unicode:characters_to_list(Data,unicode) of
      {incomplete,Encoded, Rest} ->
            More = get_some_more_data(),
            Encoded ++ decode_data([Rest, More]);
      {error,Encoded,Rest} ->
            handle_error(Encoded,Rest);
      List ->
            List
   end.

但是，不允许使用非完整字节的位字符串，因此必须沿 8 位边界分割 UTF 字符才能进行解码。

以下情况会引发 badarg 异常：

• 任何参数的类型都是错误的。
• 列表结构无效(尾部为数字)。
• 二进制文件不包含整个字节(位字符串)。