Fix vector terminology in the manual.

[steveklabnik]

fixes #17148

[nodakai]

This update is not yet enough because the underlying semantics is not considered. For example,

+[Array](#vector,-array,-and-slice-types)-typed expressions can be indexed by writing a
 square-bracket-enclosed expression (the index) after them. When the

this sentence refers only to the array type among three related types. Now we know what [0i][0] means but don't know what vec![0i][0] means. I think you need to introduce a new term to group vector, array, and slice types which all accept the index notation.

Moreover, while the vector and slice types are covered in the API reference, the array type is not. So we don't know why [0i].len() compiles at all and what it means.

The (non-)relationship between [int, .. 1] and [int, .. 2] should also be expliciltly stated.

fn main() {
    let a: [int, .. 1] = [0i, 1i];
}

http://is.gd/O8EJGx

What are the differences between arrays and immutable Vec? The former can be allocated on the stack is not usually visible to a Rust programmer.

[huonw]

Note that this update is literally just correcting the name to the accepted conventions, it is doing nothing to the actual content.

Now we know what [0i][0] means but don't know what vec![0i][0] means

The meaning of this is implied by the trait impls of Vec; unlike array (and slice) expressions. I imagine we don't want to be talking about e.g. Bitv here (which also accepts [] indexing notation).

What are the differences between arrays and immutable Vec? The former can be allocated on the stack is not usually visible to a Rust programmer.

One is in the language (arrays) and one is entirely defined in libraries (Vec).

[steveklabnik]

Arrays and slices are the only native types technically, Vec is a library type. We haven't decided, but the manual will probably be only the language spec, without libraries.

Also, while it's true that there's not more information, this is actually about just fixing it to not be broken. Eventually the manual is going to get a full overhaul, but now is not that time, and I'd rather not let the perfect be the enemy of the better.

[nodakai]

@huonw My bad, I overlooked the fact that Vec implements Index.

I can indeed read vec.rs but I wanted you to clarify how the built-in array types are semantically different from Vec. Then we will understand array better; Vec + (array - Vec) = array, you know.

Incidentally, please note that good programming languages shouldn't force a programmer to distinguish built-in types and library types. Programmers praise Lisp and Smalltalk and badmouth Java partly because of that. My understanding is that the array type is unique in Rust that it is parametrized by its element type and its size (compare Rust traits with C++ templates which can also accept compile-time constant integers.) The official documents should do their best to minimize newcomers' surprise on that.

I hope this issue is regarded as a showstopper for 1.0.

[pcwalton]

I am opposed to blocking 1.0 on this.