Pre-RFC: Add join_seq method to slices and strs

[dhm]

@RalfJung

The entire memory range of this slice must be contained within a single allocated object! Slices can never span across multiple allocated objects.

I am not sure if there are other places where such a warning can be more useful.

Imho simply adding this very counter example there should suffice (in a similar fashion to your improving the Pin docs by a lot when you added counter-examples):

Something like this

@Preview

pub unsafe fn from_raw_parts<'a, T>(data: *const T, len: usize) -> &'a [T]

Safety

Behavior is undefined if any of the following conditions are violated:

• data must be valid for reads for len * mem::size_of::<T>() many bytes, and it must be properly aligned. This means in particular:
  • The entire memory range of this slice must be contained within a single allocated object! Slices can never span across multiple allocated objects.
  • data must be non-null and aligned even for zero-length slices. One reason for this is that enum layout optimizations may rely on references (including slices of any length) being aligned and non-null to distinguish them from other data. You can obtain a pointer that is usable as data for zero-length slices using NonNull::dangling() .
• The memory referenced by the returned slice must not be mutated for the duration of lifetime 'a , except inside an UnsafeCell .
• The total size len * mem::size_of::<T>() of the slice must be no larger than isize::MAX . See the safety documentation of pointer::offset .

Caveat

The lifetime for the returned slice is inferred from its usage. To prevent accidental misuse, it's suggested to tie the lifetime to whichever source lifetime is safe in the context, such as by providing a helper function taking the lifetime of a host value for the slice, or by explicit annotation.

Examples

use ::std::slice;

// manifest a slice for a single element
let x = 42;
let ptr = &x as *const _;
let slice = unsafe { slice::from_raw_parts(ptr, 1) };
assert_eq!(slice[0], 42);

Counterexamples

Objects from different allocations may end up contiguous in memory, so the following function is unsound:

use ::std::slice;

fn join_slices<'a, T>(fst: &'a [T], snd: &'a [T]) -> &'a [T] {
    let fst_end = self.as_ptr().wrapping_add(self.len());
    let snd_start = snd.as_ptr();
    assert_eq!(fst_end, snd_start, "Slices must be contiguous!");
    unsafe {
        // Not sound! `fst` and `snd` may still originate
        // from *two distinct* allocations!
        slice::from_raw_parts(fst.as_ptr(), fst.len() + snd.len())
    }
}