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 異常：

• 任何參數的類型都是錯誤的。
• 列表結構無效(尾部為數字)。
• 二進製文件不包含整個字節(位字符串)。