编码

Rust 的字符编码支持。它基于 WHATWG 编码标准，同时也提供了高级接口用于错误检测和恢复。

使用方法

将此内容放入你的 Cargo.toml

[dependencies]
encoding-next = "0.3"

数据表

默认情况下，Encoding 包含约 480 KB 的数据表（"索引"）。这使得 Encoding 能够高效地对旧版编码进行编码和解码，但这可能不适合某些应用程序。

Encoding 提供了 no-optimized-legacy-encoding Cargo 功能，通过牺牲编码性能（通常慢 5 到 20 倍）来减小编码表的大小（到约 185 KB）。解码性能保持不变。 此功能强烈建议用于最终用户。请勿尝试从库仓库中启用此功能。

有关更精细的优化，请参阅 src/index/gen_index.py 用于自定义表生成。

概述

编码一个字符串

use encoding::{Encoding, EncoderTrap};
use encoding::all::ISO_8859_1;

assert_eq!(ISO_8859_1.encode("caf\u{e9}", EncoderTrap::Strict),
           Ok(vec![99,97,102,233]));

编码一个包含无法表示的字符的字符串

use encoding::{Encoding, EncoderTrap};
use encoding::all::ISO_8859_2;

assert!(ISO_8859_2.encode("Acme\u{a9}", EncoderTrap::Strict).is_err());
assert_eq!(ISO_8859_2.encode("Acme\u{a9}", EncoderTrap::Replace),
           Ok(vec![65,99,109,101,63]));
assert_eq!(ISO_8859_2.encode("Acme\u{a9}", EncoderTrap::Ignore),
           Ok(vec![65,99,109,101]));
assert_eq!(ISO_8859_2.encode("Acme\u{a9}", EncoderTrap::NcrEscape),
           Ok(vec![65,99,109,101,38,35,49,54,57,59]));

解码字节序列

use encoding::{Encoding, DecoderTrap};
use encoding::all::ISO_8859_1;

assert_eq!(ISO_8859_1.decode(&[99,97,102,233], DecoderTrap::Strict),
           Ok("caf\u{e9}".to_string()));

解码包含无效序列的字节序列

use encoding::{Encoding, DecoderTrap};
use encoding::all::ISO_8859_6;

assert!(ISO_8859_6.decode(&[65,99,109,101,169], DecoderTrap::Strict).is_err());
assert_eq!(ISO_8859_6.decode(&[65,99,109,101,169], DecoderTrap::Replace),
           Ok("Acme\u{fffd}".to_string()));
assert_eq!(ISO_8859_6.decode(&[65,99,109,101,169], DecoderTrap::Ignore),
           Ok("Acme".to_string()));

将输入编码或解码到已分配的缓冲区中

use encoding::{Encoding, EncoderTrap, DecoderTrap};
use encoding::all::{ISO_8859_2, ISO_8859_6};

let mut bytes = Vec::new();
let mut chars = String::new();

assert!(ISO_8859_2.encode_to("Acme\u{a9}", EncoderTrap::Ignore, &mut bytes).is_ok());
assert!(ISO_8859_6.decode_to(&[65,99,109,101,169], DecoderTrap::Replace, &mut chars).is_ok());

assert_eq!(bytes, [65,99,109,101]);
assert_eq!(chars, "Acme\u{fffd}");

自定义编码器陷阱的实际示例

use encoding::{Encoding, ByteWriter, EncoderTrap, DecoderTrap};
use encoding::types::RawEncoder;
use encoding::all::ASCII;

// hexadecimal numeric character reference replacement
fn hex_ncr_escape(_encoder: &mut dyn RawEncoder, input: &str, output: &mut dyn ByteWriter) -> bool {
    let escapes: Vec<String> =
        input.chars().map(|ch| format!("&#x{:x};", ch as isize)).collect();
    let escapes = escapes.concat();
    output.write_bytes(escapes.as_bytes());
    true
}
static HEX_NCR_ESCAPE: EncoderTrap = EncoderTrap::Call(hex_ncr_escape);

let orig = "Hello, 世界!".to_string();
let encoded = ASCII.encode(&orig, HEX_NCR_ESCAPE).unwrap();
assert_eq!(ASCII.decode(&encoded, DecoderTrap::Strict),
           Ok("Hello, &#x4e16;&#x754c;!".to_string()));

从字符串标签获取编码，如 WHATWG 编码标准指定

use encoding::{Encoding, DecoderTrap};
use encoding::label::encoding_from_whatwg_label;
use encoding::all::WINDOWS_949;

let euckr = encoding_from_whatwg_label("euc-kr").unwrap();
assert_eq!(euckr.name(), "windows-949");
assert_eq!(euckr.whatwg_name(), Some("euc-kr")); // for the sake of compatibility
let broken = &[0xbf, 0xec, 0xbf, 0xcd, 0xff, 0xbe, 0xd3];
assert_eq!(euckr.decode(broken, DecoderTrap::Replace),
           Ok("\u{c6b0}\u{c640}\u{fffd}\u{c559}".to_string()));

// corresponding Encoding native API:
assert_eq!(WINDOWS_949.decode(broken, DecoderTrap::Replace),
           Ok("\u{c6b0}\u{c640}\u{fffd}\u{c559}".to_string()));

类型和相关内容

Encoding 有三个主要入口点。

Encoding 是一种单字符编码。它包含 encode 和 decode 方法，用于将 String 转换为 Vec<u8> 以及反向转换。对于错误处理，它们接收 陷阱（分别对应 EncoderTrap 和 DecoderTrap），将任何错误替换为某些字符串（例如 U+FFFD）或序列（例如 ?）。您还可以使用 EncoderTrap::Strict 和 DecoderTrap::Strict 陷阱在错误时停止。

获取 Encoding 有两种方法。

• encoding::all 为每种支持的编码提供了静态项。当编码不会改变或只需要少量时，应使用它们。结合链接时间优化，任何未使用的编码都会从二进制文件中删除。
• encoding::label 提供了从给定字符串（“标签”）动态获取编码的函数。它们将返回对编码的静态引用，其类型也称为 EncodingRef。当事先不知道所需的编码列表时，这很有用，但它会导致二进制文件更大，错过优化机会。

RawEncoder 是一个实验性的增量编码器。在 raw_feed 的每个步骤中，它接收一个字符串切片，并将任何编码的字节输出到通用的 ByteWriter（通常是 Vec<u8>）。如果出现任何错误，它将在第一个错误处停止，并返回一个 CodecError 结构体。调用者负责在编码过程结束时调用 raw_finish。

RawDecoder 是一个实验性的增量解码器。在 raw_feed 的每个步骤中，它接收一个字节序列切片，并将任何解码的字符输出到通用的 StringWriter（通常是 String）。否则它与 RawEncoder 相同。

应首选 Encoding::{encode,decode} 作为主要接口。 RawEncoder 和 RawDecoder 是实验性的，可能会有很大变化。有关更多信息，请参阅 encoding::types 模块中的附加文档。

支持的编码

编码涵盖了 WHATWG 编码标准中指定的所有编码以及一些更多

• 7位严格ASCII（ascii）
• ArmSCII-8（armscii-8）
• UTF-8（utf-8）
• 小端UTF-16（utf-16 或 utf-16le）和大端UTF-16（utf-16be）
• WHATWG 编码标准中所有的单字节编码
  • IBM代码页 866
  • ISO 8859-{2,3,4,5,6,7,8,10,13,14,15,16}
  • KOI8-R, KOI8-U
  • MacRoman（macintosh），Macintosh 西里尔编码（x-mac-cyrillic）
  • Windows代码页 874, 1250, 1251, 1252（代替ISO 8859-1），1253, 1254（代替ISO 8859-9），1255, 1256, 1257, 1258
• WHATWG 编码标准中所有的多字节编码
  • Windows代码页 949（euc-kr，因为严格的 EUC-KR 几乎不用）
  • EUC-JP 和 Windows代码页 932（shift_jis，因为它是 Shift_JIS 最广泛的应用扩展）
  • ISO-2022-JP 与非对称 JIS X 0212 支持（注意：这还没有达到当前标准）
  • GBK
  • GB 18030
  • Big5-2003 与 HKSCS-2008 扩展
• 最初由 WHATWG 编码标准指定的编码
  • HZ
• ISO 8859-1（与 Windows 代码页 1252 区分开来）
• 代码页 437（cp437）

括号内的名称指的是由 WHATWG 编码标准指定的编码的主名称。

许多遗留字符编码缺乏适当的规范，即使那些有规范的定义，也高度依赖于实际实现。因此，在选择所需的字符编码时应谨慎。在这方面唯一可靠的标准是 WHATWG 编码标准和来自 Unicode 联盟的供应商提供的映射 http://www.unicode.org/Public/MAPPINGS/。如有疑问，请查看源代码和规范以获取详细说明。

lib.rs:

为 encoding-next 的简体中文索引表。