Rust 团队很高兴地宣布 Rust 新版本 1.48.0 发布。Rust 是一种编程语言,旨在赋能所有人构建可靠且高效的软件。
如果您之前通过 rustup 安装了 Rust,那么获取 Rust 1.48.0 非常简单,只需运行:
$ rustup update stable
如果您还没有安装,您可以从我们网站上的相应页面获取 rustup
,并查看 GitHub 上 1.48.0 版本的详细发布说明。
1.48.0 稳定版的新特性
此版本的亮点是 Rustdoc,它进行了一些更改,使编写文档更加容易!请参阅详细发布说明,了解本文未涵盖的其他更改。
Rustdoc 中更轻松的链接
Rustdoc 是 Rust 发行版中包含的库文档工具,它允许您使用 Markdown 编写文档。这使得它非常易于使用,但也存在一些痛点。假设您正在为一些如下所示的 Rust 代码编写文档:
pub mod foo {
pub struct Foo;
}
pub mod bar {
pub struct Bar;
}
我们有两个模块,每个模块内部都有一个结构体。假设我们想一起使用这两个结构体;我们可能想在文档中注明这一点。所以我们会编写一些看起来像这样的文档:
pub mod foo {
/// Some docs for `Foo`
///
/// You may want to use `Foo` with `Bar`.
pub struct Foo;
}
pub mod bar {
/// Some docs for `Bar`
///
/// You may want to use `Bar` with `Foo`.
pub struct Bar;
}
这一切都很好,但如果我们能够链接到这些其他类型,那就太好了。这将使我们的库用户在我们的文档中更轻松地在它们之间导航。
这里的问题是 Markdown 不了解任何关于 Rust 和 rustdoc 生成的 URL 的信息。因此,Rust 程序员不得不手动写出这些链接:
pub mod foo {
/// Some docs for `Foo`
///
/// You may want to use `Foo` with [`Bar`].
///
/// [`Bar`]: ../bar/struct.Bar.html
pub struct Foo;
}
pub mod bar {
/// Some docs for `Bar`
///
/// You may want to use `Bar` with [`Foo`].
///
/// [`Foo`]: ../foo/struct.Foo.html
pub struct Bar;
}
请注意,我们还必须使用相对链接,以便它可以离线工作。这个过程不仅繁琐且容易出错,而且在某些地方也是错误的。如果我们在 crate 根目录中放置一个 pub use bar::Bar
,那将在我们的根目录中重新导出 Bar
。现在我们的链接是错误的。但是如果我们修复它们,那么当我们导航到模块内部的 Bar
时,它们最终又会变成错误的。您实际上无法手动编写这些链接,并使其全部准确。
在此版本中,您可以使用一些语法让 rustdoc 知道您正在尝试链接到某个类型,它将为您生成 URL。以下是两个不同的示例,基于我们之前的代码:
pub mod foo {
/// Some docs for `Foo`
///
/// You may want to use `Foo` with [`Bar`](crate::bar::Bar).
pub struct Foo;
}
pub mod bar {
/// Some docs for `Bar`
///
/// You may want to use `Bar` with [`crate::foo::Foo`].
pub struct Bar;
}
第一个示例将显示与之前相同的文本;但会生成指向 Bar
类型的正确链接。第二个示例将链接到 Foo
,但会将整个 crate::foo::Foo
显示为链接文本。
这里有很多选项可供您使用。请参阅 rustdoc 书籍的“按名称链接到项目”部分了解更多信息。Inside Rust 上也有一篇关于此功能历史记录的文章,由一些幕后贡献者撰写!
添加搜索别名
您现在可以在项目上指定 #[doc(alias = "<alias>")]
,以便在使用 rustdoc
的 UI 进行搜索时添加搜索别名。 这是一个较小的更改,但仍然很有用。它看起来像这样:
#[doc(alias = "bar")]
struct Foo;
通过此注解,如果我们在 rustdoc 的搜索中搜索“bar”,即使我们的搜索文本中没有“Foo”,Foo
也会作为结果的一部分出现。
别名一个有趣的用例是 FFI 包装器 crate,其中每个 Rust 函数都可以别名为它包装的 C 函数。底层 C 库的现有用户将能够轻松搜索到正确的 Rust 函数!
库变更
最重要的 API 更改有点拗口:[T; N]: TryFrom<Vec<T>>
现在是稳定的了。这是什么意思?嗯,您可以使用它来尝试将 vector 转换为给定长度的数组:
use std::convert::TryInto;
let v1: Vec<u32> = vec![1, 2, 3];
// This will succeed; our vector has a length of three, we're trying to
// make an array of length three.
let a1: [u32; 3] = v1.try_into().expect("wrong length");
// But if we try to do it with a vector of length five...
let v2: Vec<u32> = vec![1, 2, 3, 4, 5];
// ... this will panic, since we have the wrong length.
let a2: [u32; 3] = v2.try_into().expect("wrong length");
在上一个版本中,我们讨论了标准库能够使用 const generics。这是我们可以使用这些类型的功能添加的 API 的一个很好的例子。预计很快会听到更多关于 const generics 稳定化的消息。
此外,此版本还稳定了五个新的 API:
以下先前稳定的 API 现在已变为 const
:
Option::is_some
Option::is_none
Option::as_ref
Result::is_ok
Result::is_err
Result::as_ref
Ordering::reverse
Ordering::then
有关更多信息,请参阅详细发布说明。
其他变更
Rust 1.48.0 版本还有其他更改:请查看 Rust、Cargo 和 Clippy 中的更改。
1.48.0 版本贡献者
许多人齐心协力创造了 Rust 1.48.0。没有你们所有人,我们不可能做到。谢谢!