[Chapter 3-2] Hard to read paragraph

[YSqQrH0zurvGmYfF]

• I have searched open and closed issues and pull requests for duplicates, using these search terms:
  • 3.2
  • "3.2"
  • stack rather
  • stack rather than heap
  • flexible
• I have checked the latest main branch to see if this has already been fixed, in this file:
  • book/src/ch03-02-data-types.md

URL to the section(s) of the book with this problem:
https://doc.rust-lang.org/book/ch03-02-data-types.html#the-array-type

Description of the problem:

After first reading it seemed that the first sentence compares array to tuple, but not vector, and only in the second sentence vector is mentioned. Also, I'm not sure about the usefulness of the pre-last sentence, as the difference becomes clear after reading chapter 4.

Arrays are useful when you want your data allocated on the stack rather than the heap (we will discuss the stack and the heap more in Chapter 4) or when you want to ensure you always have a fixed number of elements. An array isn’t as flexible as the vector type, though. A vector is a similar collection type provided by the standard library that is allowed to grow or shrink in size. If you’re unsure whether to use an array or a vector, chances are you should use a vector. Chapter 8 discusses vectors in more detail.

Suggested fix:

We need to clarify that an array isn’t as flexible as the vector type. A vector is a similar collection type provided by the standard library that is allowed to grow or shrink in size. But arrays are useful when you want your data allocated on the stack rather than the heap (we will discuss the stack and the heap more in Chapter 4) or when you want to ensure you always have a fixed number of elements. Chapter 8 discusses vectors in more detail.

[StefanSalewski]

I think your suggestion is a tiny improvement. But this section shows a general problem when writing for a broad target audience: For experts, i.e. experienced C++ programmers, explanations can be boring, while for beginners, e.g. people with only some Python experience, terms like stack and heap might be unfamiliar, and the pros and cons between arrays and vectors would need a much more detailed explanation.

[YSqQrH0zurvGmYfF]

I made the mistake of not attaching the paragraph before the problem paragraph.

Another way to have a collection of multiple values is with an array. Unlike a tuple, every element of an array must have the same type. Unlike arrays in some other languages, arrays in Rust have a fixed length.

The second sentence compares a vector to a tuple. So I thought it continued in the next paragraph. The array is allocated on the stack and the tuple is allocated on the heap. But it isn't. Only after some time I realized that the paragraphs are not connected and the sentence refers to a vector.

[chriskrycho]

I can kind of see why you got hung up here. I think a smaller change might actually serve to clarify (new text emphasized):

Arrays are useful when you want your data allocated on the stack, like the other types we have seen so far, rather than the heap (we will discuss the stack and the heap more in Chapter 4) or when you want to ensure you always have a fixed number of elements. An array isn’t as flexible as the vector type, though. A vector is a similar collection type provided by the standard library that is allowed to grow or shrink in size. If you’re unsure whether to use an array or a vector, chances are you should use a vector. Chapter 8 discusses vectors in more detail.

That avoids introducing confusion about the non-tuple types, and also avoids trying to distinguish between array and vector before we have even said what a vector is.

[YSqQrH0zurvGmYfF]

I tend to agree. With this remark, the text becomes clearer.