Improve `VaList` stdlib docs
tracking issue: https://github.com/rust-lang/rust/issues/44930
Some improvements to the `VaList` documentation, at least adding an example. We should link to the reference for c-variadic functions once stable. I've tried to call out explicitly that the type is meant for sending over the FFI boundary.
r? workingjubilee
cc @tgross35
Expand `str_as_str` to more types
Tracking issue: rust-lang/rust#130366
ACP: https://github.com/rust-lang/libs-team/issues/643
This PR expands `str_from_str` feature and adds analogous methods to more types. Namely:
- `&CStr`
- `&[T]`, `&mut [T]`
- `&OsStr`
- `&Path`
- `&ByteStr`, `&mut ByteStr` (tracking issue: rust-lang/rust#134915) (technically was not part of ACP)
Add doc for va_list APIs
I observed that [PR146521](https://github.com/rust-lang/rust/pull/146521) submitted two weeks ago resolved some documentation issues related to `VaListImpl`, similar to the previous [PR136969](https://github.com/rust-lang/rust/pull/136969).
This PR specifically adds requirements about argument availability for `VaListImpl::arg`, and also adds safety descriptions to the three associated intrinsic APIs.
Fix link in c_longlong documentation
Ran across this mistake when reading [the documentation](https://doc.rust-lang.org/std/ffi/type.c_longlong.html). I went through the other `.md` files in this directory and didn't spot any other errors.
**I did not check the output of this change** - I couldn't figure out how to get `cargo doc` to work and I figured it's not worth the distraction. It can't really go wrong, can it?
The CStr docs used to say things about CStr that are only true for &CStr.
Also, it's the bytes that are being borrowed, not the reference. One could say that it's the reference that is doing the borrowing, rather than being borrowed.
Allow comparisons between `CStr`, `CString`, and `Cow<CStr>`.
Closes: #137265
This PR adds the trait implementations proposed in the [ACP](https://github.com/rust-lang/libs-team/issues/517/) under the `c_string_eq_c_str` feature gate:
```rust
// core::ffi
impl PartialEq<&Self> for CStr;
impl PartialEq<CString> for CStr;
impl PartialEq<Cow<'_, Self>> for CStr;
// alloc::ffi
impl PartialEq<CStr> for CString;
impl PartialEq<&CStr> for CString;
impl PartialEq<Cow<'_, CStr>> for CString;
// alloc::borrow
impl PartialEq<CStr> for Cow<'_, CStr>;
impl PartialEq<&CStr> for Cow<'_, CStr>;
impl PartialEq<CString> for Cow<'_, CStr>;
```
As I understand it, stable traits cannot be unstably implemented for stable types, and we would thereby be forced to skip the FCP and directly stabilise these implementations (as is done in this PR).
(`@joshtriplett` mentioned that Crater may have to be run).
use `cfg_select!` to select the right `VaListImpl` definition
tracking issue: https://github.com/rust-lang/rust/issues/44930
Just a bit of cleanup really.
We could use `PhantomInvariantLifetime<'f>` (https://github.com/rust-lang/rust/issues/135806) to make it more precise what that `PhantomData<&'f mut &'f c_void>` marker is doing. I'm not sure how ready that feature is though, `@jhpratt` are these types good to use internally?
---
Some research into the lifetimes of `VaList` and `VaListImpl`:
It's easy to see why the lifetime of these types should not be extended, a `VaList` or `VaListImpl` escaping its function is a bad idea. I don't currently see why coercing the lifetime to a shorter lifetime is problematic though, but probably I just don't understand variance well enough to see it. The history does not provide much explanation:
- https://github.com/immunant/rust/commit/08140878fefaa4b16939b904bf825b7107069b42 original implementation
- https://github.com/immunant/rust/commit/b9ea653aee231114acbe6d4b3c7b1d692772d060 adds `VaListImpl<'f>`, but it is only covariant in `'f`
- https://github.com/rust-lang/rust/pull/62639 makes `VaListImpl<'f>` invariant over `'f` (because `VaList<'a, 'f>` is already invariant over `'f`, but I think that is just an implementation detail?)
Beyond that I don't see how the lifetime situation can be simplified significantly, e.g. this function really needs `'copy` to be unconstrained.
```rust
/// Copies the `va_list` at the current location.
pub unsafe fn with_copy<F, R>(&self, f: F) -> R
where
F: for<'copy> FnOnce(VaList<'copy, 'f>) -> R,
{
let mut ap = self.clone();
let ret = f(ap.as_va_list());
// SAFETY: the caller must uphold the safety contract for `va_end`.
unsafe {
va_end(&mut ap);
}
ret
}
```
`@rustbot` label +F-c_variadic
r? `@workingjubilee`
8 and 16-bit integers are subject to upcasting in C, and hence are not reliably safe. users should perform their own casting and deal with the consequences
Stabilise `std::ffi::c_str`
This finished FCP in #112134 but never actually got a stabilisation PR. Since the FCP in #120048 recently passed to add the `os_str` module, it would be nice to also merge this too, to ensure that both get added in the next version.
Note: The added stability attributes which *somehow* were able to be omitted before (rustc bug?) were added based on the fact that they were added in 302551388b, which ended up in 1.85.0.
Closes: https://github.com/rust-lang/rust/issues/112134
r? libs-api
bjorn3