The docs (which are generally very good, especially for a language this young) should: 1. Distinguish between abort and panic. 2. Explain that allocation fail

The docs (which are generally very good, especially for a language this young) should: 1. Distinguish between abort and panic. 2. Explain that allocation failure is an abort. 3. Explain that a vec can allocate up to twice its nominal size, which is a common cause of OOMs. To their credit, the docs do explain that vec over-allocates, but not that it allocates double the memory. They could also explain that you don't get that memory back unless you ask for it, even if you pop() or remove() elements. Scenario: I'm a new systems programmer excited to try Rust (fast and safe? wow!). I have 8GB of memory in my computer. I push ~4GB of data into a vector so I can process it, something I'm used to doing in Python. POW! My program exits with no error message. What happened? I look at the error handling docs: https://doc.rust-lang.org/book/error-handling.html https://doc.rust-lang.org/book/error-handling.html Well, it sure wasn't a recoverable failure! Must have been a panic. So I look at the docs for vec.push: https://doc.rust-lang.org/std/vec/struct.Vec.html https://doc.rust-lang.org/std/vec/struct.Vec.html "Panics if the number of elements in the vector overflows a usize." A usize is big, right? I didn't overflow that. I guess I could have run out of memory, but I have 8GB. That should be plenty!