std-Vec docs: "slices are read-only objects"

[iampi31415]

Location

https://doc.rust-lang.org/nightly/std/vec/struct.Vec.html#slicing

Summary

A Vec can be mutable. On the other hand, slices are read-only objects. To get a slice, use &.

I assume that &mut are slices as well (not just &[...]). Hence isn't that quote above inaccurate ? (see example below.)

#![allow(unused)]
fn main() {

    let mut v = vec![0, 1];

    let u: &mut [usize] = &mut v;
    u[0] = 42;
    println!("{v:?}");
}

[iampi31415]

ChatGPT's correction, which seems appropriate to me, is:

A Vec can be mutable. Slices are views into a collection’s data. Immutable slices (&[T]) are read-only, while mutable slices (&mut [T]) allow mutation of the underlying data.

But you may want to rephrase it —assuming this isn't just a misinterpretation of the docs, that is.

[JasonHonKL]

I would give this a try.

@rustbot claim

[orlp]

Slices have two components: a start pointer and a length. You can't change either of those attributes, therefore slices are immutable.

Given a mutable reference to a slice you may change the elements contained in the slice, but not the slice itself.

Is this a useful nitpick to state without any further context in the docs? Probably not. It also somewhat depends on what you mean by 'slice'. Do you mean the unsized type [T], or do you really mean 'reference to slice', &[T] or &mut [T].

[iampi31415]

@orlp
This isn't a nitpick, in my opinion the sentence "On the other hand, slices are read-only objects." is misleading and can easily be improved.

The slice struct is not be changeable, but the underlying data can be, I think compounded with the "To get a slice, use &." it gives the wrong impression.

If others disagree as well I'll drop it, no problem.

[orlp]

@iampi31415 I meant that the current comment in the docs (and my explanation of it) is a technical nitpick which is probably confusing for newcomers, at least how it's currently worded in the docs.

[fee1-dead]

Slices have two components: a start pointer and a length. You can't change either of those attributes, therefore slices are immutable.

Given a mutable reference to a slice you may change the elements contained in the slice, but not the slice itself.

Slices are sometimes confusing w.r.t. &[T] vs. [T]. I largely agree with the slice documentation: https://doc.rust-lang.org/nightly/std/primitive.slice.html

[T] represents a contiguous sequence of T. &[T] is a shared slice into that contiguous sequence. &mut [T] is a mutable slice into that contiguous sequence.

Giving a mutable reference to a slice &mut &[T] you can change the length and the pointer of the slice:

pub fn uwu<T>(s: &mut &[T]) {
    let s2 = &(*s)[1..];
    *s = s2;
}

The slicing section only talks about shared slices, and not mutable slices. It should be changed to acknowledge that mutable slices can also be created.