Rust 的 WHATWG URL 解析器

快速、符合 WHATWG URL 规范的 Rust URL 解析器。经过充分测试，并自 Node 18 起被 Node.js 广泛使用。

Ada 库通过了规范中全范围的测试，适用于广泛的平台（例如 Windows、Linux、macOS）。它完全支持相关的 Unicode 技术标准。

用法

参见此处获取使用示例。你可以使用 cargo run --example simple 在本地运行它。请随意调整它以进一步探索此 crate。

特性

std: 需要 std 的功能。此特性默认启用，如果你想要 no-std，请将 no-default-features 设置为 true。

serde: 允许 Url 与 serde 配合使用。此特性默认禁用。启用此特性而不启用 std 将仅提供 Serialize。启用此特性和 std 将同时提供 Serialize 和 Deserialize。

libcpp: 使用 libc++ 构建 ada-url。此特性默认禁用。在未安装 libc++ 的情况下启用此特性将导致编译错误。

bundled: 编译并静态链接捆绑的 C++ ada 源代码。此特性默认启用。有关如何禁用它，请参阅下文“链接外部 ada”。

链接外部 ada

默认情况下（bundled 特性），构建脚本会编译捆绑的 C++ ada 源代码并静态链接它们。如果你的宿主构建系统（例如 Bazel、CMake 或发行版软件包）已经提供了 ada，编译捆绑副本将在最终二进制文件中产生第二个重复的 ada 副本。

禁用 bundled 功能以跳过捆绑构建，并改为链接外部 ada：

# Cargo.toml — re-enable `std` since disabling default features also drops it
ada-url = { version = "4", default-features = false, features = ["std"] }

当 bundled 被禁用时，这些可选的环境变量用于配置外部 ada 的链接方式：

变量	描述
`ADA_LIB_DIR`	添加到链接器搜索路径的可选目录（`cargo:rustc-link-search=native`）。
`ADA_LIB_NAME`	要链接的可选库，原样传递给 `cargo:rustc-link-lib`（例如 `ada` 或 `static=ada`）。

如果两者均未提供，则不会发出链接指令，由宿主构建系统在最终链接时提供 ada 符号。外部 ada 必须暴露相同的 C ABI（ada_*），并且与本 crate 的版本保持 ABI 兼容。

# Link against a system-installed libada in /usr/local/lib
ADA_LIB_DIR=/usr/local/lib ADA_LIB_NAME=ada \
  cargo build --no-default-features --features std

性能

Ada 速度很快。下方的基准测试显示，与 url 相比，URL 解析速度快了 3.49 倍

can_parse/ada_url       time:   [1.2109 µs 1.2121 µs 1.2133 µs]
                        thrpt:  [635.09 MiB/s 635.75 MiB/s 636.38 MiB/s]

parse/ada_url           time:   [2.0124 µs 2.0157 µs 2.0190 µs]
                        thrpt:  [381.67 MiB/s 382.28 MiB/s 382.91 MiB/s]

parse/url               time:   [7.0530 µs 7.0597 µs 7.0666 µs]
                        thrpt:  [109.04 MiB/s 109.15 MiB/s 109.25 MiB/s]

已实现的 trait

Url 实现了以下 trait。

Trait(s)	Description
`Display`	提供 `to_string` 并允许该值用于 format! 宏（例如 `println!`）。
`Debug`	允许在格式化宏中输出调试信息，（`{:?}` 语法）
`PartialEq`, `Eq`	允许进行比较，`url1 == url2`，`url1.eq(url2)`
`PartialOrd`, `Ord`	允许按字母顺序进行排序 `url1 < url2`。这也允许将 `Url` 用作 `BTreeMap` 中的键
`Hash`	使得 `Url` 可以基于字符串表示进行哈希。这很重要，因为 `Url` 可以用作 `HashMap` 中的键
`FromStr`	允许与 `str` 的 `parse` 方法一起使用
`TryFrom<String>`, `TryFrom<&str>`	为 `String` 和 `&str` 提供 `try_into` 方法
`Borrow<str>`, `Borrow<[u8]>`	在某些 crate 中使用，以便 `Url` 可以用作键。
`Deref<Target=str>`	允许 `&Url` 作为 `&str` 进行解引用。还提供一系列字符串方法
`AsRef<[u8]>`, `AsRef<str>`	用于执行廉价的引用到引用的转换。
`Send`	用于声明该类型可以在线程边界之间传输。
`Sync`	用于声明该类型是线程安全的。

开发

`justfile`

The justfile 包含可由 just 执行的命令（称为“recipes”），以提供便利。

运行所有 lints 和 tests：

just all

跳过功能：

just all --skip=libcpp,serde

许可证

本代码在 Apache License 2.0 以及 MIT 许可证下提供。

我们的测试包含第三方代码和数据。基准测试代码包含第三方代码：它仅用于研究目的，不属于库的一部分。