Module std::ffi1.0.0[−][src]

Expand description

与 FFI 绑定有关的实用工具。

该模块提供了实用工具来处理跨非 Rust 接口的数据，例如其他编程语言和底层操作系统。它主要用于 FFI (外部函数接口) 绑定和需要与其他语言交换类 C 字符串的代码。

Overview

Rust 代表 String 类型的拥有的字符串，而借用 str 原语的字符串切片。两者始终都是 UTF-8 编码，并且中间可能包含 nul 个字节，即，如果您查看组成字符串的字节，则其中可能有一个 \0。 String 和 str 都明确存储它们的长度。像 C 中的字符串末尾没有 nul 终止符。

C 字符串不同于 Rust 字符串:

  • 编码-Rust 字符串是 UTF-8，但是 C 字符串可以使用其他编码。如果使用的是来自 C 的字符串，则应显式检查其编码，而不是像在 Rust 中那样假定它是 UTF-8。

  • 字符大小-C 字符串可以使用 char 或 wchar_t 大小的字符; 请 注意 C 的 char 与 Rust 的不同。 C 标准使这些类型的实际大小易于解释，但是为由每个字符类型组成的字符串定义了不同的 API。Rust 字符串始终为 UTF-8，因此每个不同的 Unicode 字符将以可变的字节数进行编码。 Rust 类型 char 表示 [Unicode 标量值]，与 [Unicode 代码点] 相似但不相同。

  • Nul 终止符和隐式字符串长度-C 字符串通常以 Nul 终止，即，它们的末尾有 \0 字符。 字符串缓冲区的长度不存储，而是必须计算; 要计算字符串的长度，C 代码必须手动调用一个函数，例如 strlen() 表示基于 char 的字符串，wcslen() 表示基于 wchar_t 的字符串。 这些函数返回字符串中不包括 nul 终止符的字符数，因此缓冲区长度实际上是 len+1 字符。 Rust 字符串没有 nul 终止符; 它们的长度总是存储的，不需要计算。 在 Rust 中，访问字符串的长度是 O(1) 操作 (因为存储了长度) ; 在 C 中，它是 O(length) 操作，因为需要通过扫描字符串中的 nul 终止符来计算长度。

  • 内部 nul 字符- 当 C 字符串具有 nul 终止符时，这通常意味着它们中间不能包含 nul 字符 - nul 字符实际上会截断字符串。 Rust 字符串 可以 中间有 nul 个字符，因为 nul 不必在 Rust 中标记字符串的结尾。

非 Rust 字符串的表示形式

CString 当您需要在具有 C ABI 的语言之间来回传输 UTF-8 字符串时 (例如 Python)，X 和 CStr 很有用。

  • 从 Rust 到 C:CString 表示一个拥有的，对 C 友好的字符串: 它是 nul 终止的，并且没有内部 nul 字符。 Rust 代码可以从普通字符串中创建 CString (前提是该字符串的中间没有 nul 字符)，然后使用多种方法来获取原始的 * mut [u8]，然后作为参数传递给使用 C 约定的字符串的函数。

  • 从 C 到 Rust:CStr 表示借用的 C 字符串; 这就是您用来包装从 C 函数获得的原始 * constu8 的方式。CStr 保证是一个以 nul 结尾的字节数组。 拥有 CStr 后，可以将其转换为 Rust &str (如果它是有效的 UTF-8)，或者通过添加替换字符有损地对其进行转换。

OsString 当您需要在操作系统本身之间来回传输字符串，或者在捕获外部命令的输出时，X 和 OsStr 很有用。 OsString，OsStr 和 Rust 字符串之间的转换与 CString 和 CStr 的转换相似。

  • OsString 以操作系统喜欢的任何表示形式表示一个拥有的字符串。在 Rust 标准库中，用于传输字符串 to/from 的各种 API，操作系统使用 OsString 代替纯字符串。 例如，env::var_os() 用于查询环境变量; 它返回一个 Option<OsString>。如果环境变量存在，您将得到一个 Some(os_string)，然后您可以 然后 尝试将其转换为 Rust 字符串。 这将产生一个 Result，以便在环境变量实际上不包含有效的 Unicode 数据的情况下，您的代码可以检测到错误。

  • OsStr 表示借用字符串引用的形式，该形式可以传递给操作系统。可以按照与 OsString 相似的方式将其转换为 UTF-8 Rust 字符串切片。

Conversions

在 Unix 上

在 Unix 上，OsStr 实现了 std::ffi::[OsStrExt][unix.OsStrExt] trait，并使用两种方法 [from_bytes] 和 [as_bytes`] 对其进行了扩充。 它们可以进行 UTF-8 字节片和 UTF-8 字节片之间的廉价转换。

此外，在 Unix 上，OsString 实现了 std::ffi::[OsStringExt]][unix.OsStringExt] trait，它提供了 [from_vec] 和 [into_vec] 方法，这些方法使用其参数，并采用或产生 vectors 作为 [u8`]。

在 Windows 上

在 Windows 上，OsStr 实现了 std::ffi::[OsStrExt][windows.OsStrExt] trait，它提供了 [encode_wide] 方法。这提供了一个迭代器，可以将其迭代到 [u16`] 的 vector 中。

另外，在 Windows 上，OsString 实现了 std::windows: ffi::[OsStringExt][windows.OsStringExt] trait，它提供了 [from_wide] 方法。此方法的结果是一个 [OsString`]，它可以无损地往返于 Windows 字符串。

Structs

FromVecWithNulErrorExperimental

指示 nul 字节不在预期位置中的错误。

VaListExperimental

va_list 的包装

VaListImplExperimental

va_list 的基本实现。

CStr

借用的 C 字符串的表示形式。

CString

一种类型，表示拥有的，C 兼容的，以 nul 终止的字符串，中间没有 nul 字节。

FromBytesWithNulError

指示 nul 字节不在预期位置中的错误。

IntoStringError

将 CString 转换为 String 时，指示 UTF-8 无效的错误。

NulError

指示发现内部 nul 字节的错误。

OsStr

借用引用到 OS 字符串 (请参见 OsString)。

OsString

一种类型，可以表示拥有的，可变的平台原生字符串，但可以廉价地与 Rust 字符串互转换。

Enums

c_void

当用作 指针 时，等效于 C 的 void 类型。