Stabilize mutable slice API

[aturon]

This commit is another in the series of vector slice API stabilization. The focus here is the mutable slice API.

Largely, this API inherits the stability attributes previously assigned to the analogous methods on immutable slides. It also adds comments to a few unstable attributes that were previously missing them.

In addition, the commit adds several _mut variants of APIs that were missing:

• init_mut
• head_mut
• tail_mut
• splitn_mut
• rsplitn_mut

Some of the unsafe APIs -- unsafe_set, init_elem, and copy_memory -- were deprecated in favor of working through as_mut_ptr, to simplify the API surface.

Due to deprecations, this is a:

[breaking-change]

[rust-highfive]

Warning

• These commits modify unsafe code. Please review it carefully!

[alexcrichton]

This may also want to mention the set part as well:

#[deprecated = "use `*foo.as_mut_ptr().offset(index) = val`"]

[alexcrichton]

#[deprecated = "use `ptr::write(foo.as_mut_ptr().offset(i), val)`"]

[alexcrichton]

#[deprecated = "use as_mut_ptr and ptr::copy_memory"]

[alexcrichton]

Looks good to me! r=me with some adjustments to the deprecation messages.

[aturon]

r=alexcrichton

[pcwalton]

Why is this a regression for low-level Rust?

[pcwalton]

This is a small change that affects two methods that are rarely used in the extant codebase. Nobody felt that it would be controversial and the implication that we were deliberately attempting to sidestep community consensus is incorrect.

[brson]

@thestinger Can you be more specific about how this is making unchecked indexing on slices harder?

Discussion about this is happening now.

[brson]

@thestinger Do you have specific criticisms of the content of this pull request that you would like to discuss?

[aturon]

I think the problem here is just a poor deprecation message. It should instead suggest:

Replace v.unsafe_set(i, x) with *v.unsafe_mut(i) = x.

[Gankro]

Isn't *foo.unsafe_mut(index) = val a better choice here?

Edit: ah, this was already stated elsewhere.

[aturon]

Yes -- see comment in the github thread above. This was just a mistake in the message.

[aturon]

init_elem and copy_memory are clearly more specialized operations than skipping a bounds check.

As with many other deprecations (of safe APIs), these were eliminated as conveniences that weren't worth the extra API surface area. There's also a general push toward funneling conveniences through central traits/data structures, like Iterator and in this case ptr. The benefit is that conveniences added to these central structures have a multiplicative effect, and it's much easier to remember a single API surface rather than ad hoc convenience methods spread through different types.

If you want to do extensive unsafe work with slices, the simplest avenue would be to use .as_mut_ptr() once, and then apply as many operations as you like to the resulting pointer. And of course there's always the option to add extension traits providing any conveniences you like.

It's also worth noting that deprecations like these don't entail never providing such conveniences in the future, if they are ultimately deemed worthwhile. But there has been a lot of accumulation of ad hoc APIs, and the stabilization process is trying to move things toward a somewhat minimalistic, consistent, coherent, clean, and reasonably ergonomic state heading toward 1.0. (For bigger changes, like conventions, or removing the collection traits, or consolidating the numerics hierarchy, this involves RFCs.)

As an aside, we should consider adding an Index implementation to raw pointers, which would recover ergonomics very similar to C's -- and all by funneling through raw pointers.

[thestinger]

I still think it's a regression and I disagree with this process but I'm not interested in arguing about it anymore. I don't care enough about the standard library to deal with that.

[bors]

saw approval from alexcrichton
at aturon@c59ef66