From 42053b9ea1529830d20ac664b4b57f4507e8c9c7 Mon Sep 17 00:00:00 2001
From: Alex Crichton <alex@alexcrichton.com>
Date: Sun, 15 Feb 2015 21:04:20 -0800
Subject: [PATCH] std: Add Vec::from_iter comment

Requested by Niko in #22200 (and is good to have anyway)
---
 src/libcollections/vec.rs | 11 +++++++++++
 1 file changed, 11 insertions(+)

diff --git a/src/libcollections/vec.rs b/src/libcollections/vec.rs
index 4fb8f52a57b4..4e6e40ea693d 100644
--- a/src/libcollections/vec.rs
+++ b/src/libcollections/vec.rs
@@ -1387,6 +1387,17 @@ impl<T> FromIterator<T> for Vec<T> {
         let (lower, _) = iterator.size_hint();
         let mut vector = Vec::with_capacity(lower);
 
+        // This function should be the moral equivalent of:
+        //
+        //      for item in iterator {
+        //          vector.push(item);
+        //      }
+        //
+        // This equivalent crucially runs the iterator precisely once. The
+        // optimization below (eliding bound/growth checks) means that we
+        // actually run the iterator twice. To ensure the "moral equivalent" we
+        // do a `fuse()` operation to ensure that the iterator continues to
+        // return `None` after seeing the first `None`.
         let mut i = iterator.fuse();
         for element in i.by_ref().take(vector.capacity()) {
             let len = vector.len();