DOC: Add FFI example for slice::from_raw_parts()

[mgeier]

For some discussion, see https://users.rust-lang.org/t/missing-guidance-on-converting-ffi-ptr-length-to-slice/106048

See also #120608.

[rustbot]

r? @scottmcm

rustbot has assigned @scottmcm.
They will have a look at your PR within the next two weeks and either review your PR or reassign to another reviewer.

Use r? to explicitly pick a reviewer

[scottmcm]

Thanks for making a PR! Agreed it'd be good to have guidance like this in the docs 👍

[scottmcm]

A couple of requests for the example:

• When there's unsafe functions or blocks in the documentation, please put # Safety header and // SAFETY comments so the docs are a good example of what we'd like people to do.
• dbg! inside rustdoc examples isn't particularly useful, especially for a function that's never called. Could you maybe do some simple computation on it and return it, so that it could be called and assert!ed instead? That way Miri can check that it's not accidentally UB, too.

[mgeier]

Thanks for the review!

I have added the "safety" comments, please let me know if I should make any changes to the text.

I also changed the function to return a value and added an assert.

I'm not sure if that makes sense, though, since this function would normally be called from C++ or some other FFI language.

Alternatively, I could also provide a more general (and more useful) function:

unsafe fn ffi_slice<'a, T>(ptr: *const T, len: usize) -> &'a [T] {
    if ptr.is_null() {
        // NB: `len` is assumed to be 0.
        &[]
    } else {
        unsafe { std::slice::from_raw_parts(ptr, len) }
    }
}

I have actually used that function in my code: https://github.com/AudioSceneDescriptionFormat/asdfspline-rust/blob/e2608b07e2749caf71e43f23d4592849d27dd450/ffi/src/lib.rs#L59-L89.

However, this is a bit more complicated due to the lifetime annotation, so it might not be appropriate here?

[scottmcm]

Thanks, this addresses my concerns. I agree a caller from C++ would be more realistic, but there's not really a good way to put that in a doctest, so it's fine. The point is just to make sure that it runs, giving an opportunity for the runtime UB checks to double-check that everything is fine. (Which I do think it is, but for unsafe I always appreciate the double-checks.)

@bors r+ rollup

[bors]

📌 Commit 30b676c has been approved by scottmcm

It is now in the queue for this repository.