API Docs: vec

[steveklabnik]

Part of #29329

http://doc.rust-lang.org/std/vec/

[e-oz]

Please mention danger effect of vec! macros, panicking.
Example:
http://is.gd/tXpV3W

[gyscos]

@e-oz , how is this specific to the vec! macro? Isn't this simply out-of-bound indexing?

[e-oz]

@gyscos with promises Rust gives, "simply out-of-bound indexing" is oxymoron :) Read example to see how it's related.

[ranma42]

It might be appropriate to point out that vec's implementation of Index will result in panics upon out-of-bound, but it should also be expected from conventions and from its signature (it does not return an Option).
It might be desirable to mention that functions which perform allocations might either panic or oom() (abort the whole application instead of the panicking thread). I remember that some discussion had already happened on this (about whether it was an inconsistency to be fixed or not), but I do not think this has been documented.