From f9fe6585dcfd6f2912bc33b8cf5a3a9fa6eadcd7 Mon Sep 17 00:00:00 2001 From: Dirk Gadsden Date: Sun, 14 Feb 2016 17:00:46 -0800 Subject: [PATCH] Clarify contiguous memory array structure of vectors in documentation Closes #31554. Contributes to #29380. --- src/doc/book/vectors.md | 11 +++++++++-- src/libcollections/vec.rs | 6 +++--- 2 files changed, 12 insertions(+), 5 deletions(-) diff --git a/src/doc/book/vectors.md b/src/doc/book/vectors.md index b09735c3fee..f5a543d75b1 100644 --- a/src/doc/book/vectors.md +++ b/src/doc/book/vectors.md @@ -11,8 +11,8 @@ let v = vec![1, 2, 3, 4, 5]; // v: Vec ``` (Notice that unlike the `println!` macro we’ve used in the past, we use square -brackets `[]` with `vec!` macro. Rust allows you to use either in either situation, -this is just convention.) +brackets `[]` with `vec!` macro. Rust allows you to use either in either +situation, this is just convention.) There’s an alternate form of `vec!` for repeating an initial value: @@ -20,6 +20,12 @@ There’s an alternate form of `vec!` for repeating an initial value: let v = vec![0; 10]; // ten zeroes ``` +Vectors store their contents as contiguous arrays of `T` on the heap. This means +that they must be able to know the size of `T` at compile time (that is, how +many bytes are needed to store a `T`?). The size of some things can't be known +at compile time. For these you'll have to store a pointer to that thing: +thankfully, the [`Box`][box] type works perfectly for this. + ## Accessing elements To get the value at a particular index in the vector, we use `[]`s: @@ -113,6 +119,7 @@ Vectors have many more useful methods, which you can read about in [their API documentation][vec]. [vec]: ../std/vec/index.html +[box]: ../std/boxed/index.html [generic]: generics.html [panic]: concurrency.html#panics [get]: http://doc.rust-lang.org/std/vec/struct.Vec.html#method.get diff --git a/src/libcollections/vec.rs b/src/libcollections/vec.rs index 1bc9e6588ad..270a01014c1 100644 --- a/src/libcollections/vec.rs +++ b/src/libcollections/vec.rs @@ -8,8 +8,8 @@ // option. This file may not be copied, modified, or distributed // except according to those terms. -//! A growable list type with heap-allocated contents, written `Vec` but -//! pronounced 'vector.' +//! A contiguous growable array type with heap-allocated contents, written +//! `Vec` but pronounced 'vector.' //! //! Vectors have `O(1)` indexing, amortized `O(1)` push (to the end) and //! `O(1)` pop (from the end). @@ -78,7 +78,7 @@ use borrow::{Cow, IntoCow}; use super::range::RangeArgument; -/// A growable list type, written `Vec` but pronounced 'vector.' +/// A contiguous growable array type, written `Vec` but pronounced 'vector.' /// /// # Examples ///