@@ -2375,32 +2375,118 @@ impl<'a, I: Iterator + ?Sized> Iterator for &'a mut I {
2375
2375
}
2376
2376
2377
2377
/// Conversion from an `Iterator`.
2378
+ ///
2379
+ /// By implementing `FromIterator` for a type, you define how it will be
2380
+ /// created from an iterator. This is common for types which describe a
2381
+ /// collection of some kind.
2382
+ ///
2383
+ /// `FromIterator`'s [`from_iter()`] is rarely called explicitly, and is instead
2384
+ /// used through [`Iterator`]'s [`collect()`] method. See [`collect()`]'s
2385
+ /// documentation for more examples.
2386
+ ///
2387
+ /// [`from_iter()`]: #tymethod.from_iter
2388
+ /// [`Iterator`]: trait.Iterator.html
2389
+ /// [`collect()`]: trait.Iterator.html#method.collect
2390
+ ///
2391
+ /// See also: [`IntoIterator`].
2392
+ ///
2393
+ /// [`IntoIterator`]: trait.IntoIterator.html
2394
+ ///
2395
+ /// # Examples
2396
+ ///
2397
+ /// Basic usage:
2398
+ ///
2399
+ /// ```
2400
+ /// use std::iter::FromIterator;
2401
+ ///
2402
+ /// let five_fives = std::iter::repeat(5).take(5);
2403
+ ///
2404
+ /// let v = Vec::from_iter(five_fives);
2405
+ ///
2406
+ /// assert_eq!(v, vec![5, 5, 5, 5, 5]);
2407
+ /// ```
2408
+ ///
2409
+ /// Using [`collect()`] to implicitly use `FromIterator`:
2410
+ ///
2411
+ /// ```
2412
+ /// let five_fives = std::iter::repeat(5).take(5);
2413
+ ///
2414
+ /// let v: Vec<i32> = five_fives.collect();
2415
+ ///
2416
+ /// assert_eq!(v, vec![5, 5, 5, 5, 5]);
2417
+ /// ```
2418
+ ///
2419
+ /// Implementing `FromIterator` for your type:
2420
+ ///
2421
+ /// ```
2422
+ /// use std::iter::FromIterator;
2423
+ ///
2424
+ /// // A sample collection, that's just a wrapper over Vec<T>
2425
+ /// #[derive(Debug)]
2426
+ /// struct MyCollection(Vec<i32>);
2427
+ ///
2428
+ /// // Let's give it some methods so we can create one and add things
2429
+ /// // to it.
2430
+ /// impl MyCollection {
2431
+ /// fn new() -> MyCollection {
2432
+ /// MyCollection(Vec::new())
2433
+ /// }
2434
+ ///
2435
+ /// fn add(&mut self, elem: i32) {
2436
+ /// self.0.push(elem);
2437
+ /// }
2438
+ /// }
2439
+ ///
2440
+ /// // and we'll implement FromIterator
2441
+ /// impl FromIterator<i32> for MyCollection {
2442
+ /// fn from_iter<I: IntoIterator<Item=i32>>(iterator: I) -> Self {
2443
+ /// let mut c = MyCollection::new();
2444
+ ///
2445
+ /// for i in iterator {
2446
+ /// c.add(i);
2447
+ /// }
2448
+ ///
2449
+ /// c
2450
+ /// }
2451
+ /// }
2452
+ ///
2453
+ /// // Now we can make a new iterator...
2454
+ /// let iter = (0..5).into_iter();
2455
+ ///
2456
+ /// // ... and make a MyCollection out of it
2457
+ /// let c = MyCollection::from_iter(iter);
2458
+ ///
2459
+ /// assert_eq!(c.0, vec![0, 1, 2, 3, 4]);
2460
+ ///
2461
+ /// // collect works too!
2462
+ ///
2463
+ /// let iter = (0..5).into_iter();
2464
+ /// let c: MyCollection = iter.collect();
2465
+ ///
2466
+ /// assert_eq!(c.0, vec![0, 1, 2, 3, 4]);
2467
+ /// ```
2378
2468
#[ stable( feature = "rust1" , since = "1.0.0" ) ]
2379
2469
#[ rustc_on_unimplemented="a collection of type `{Self}` cannot be \
2380
2470
built from an iterator over elements of type `{A}`"]
2381
2471
pub trait FromIterator < A > : Sized {
2382
- /// Builds a container with elements from something iterable.
2472
+ /// Creates a value from an iterator.
2473
+ ///
2474
+ /// See the [module-level documentation] for more.
2475
+ ///
2476
+ /// [module-level documentation]: trait.FromIterator.html
2383
2477
///
2384
2478
/// # Examples
2385
2479
///
2386
- /// ```
2387
- /// use std::collections::HashSet;
2388
- /// use std::iter::FromIterator;
2480
+ /// Basic usage:
2389
2481
///
2390
- /// let colors_vec = vec!["red", "red", "yellow", "blue"];
2391
- /// let colors_set = HashSet::<&str>::from_iter(colors_vec);
2392
- /// assert_eq!(colors_set.len(), 3);
2393
2482
/// ```
2483
+ /// use std::iter::FromIterator;
2394
2484
///
2395
- /// `FromIterator` is more commonly used implicitly via the
2396
- /// `Iterator::collect` method:
2485
+ /// let five_fives = std::iter::repeat(5).take(5);
2397
2486
///
2398
- /// ```
2399
- /// use std::collections::HashSet;
2487
+ /// let v = Vec::from_iter(five_fives);
2400
2488
///
2401
- /// let colors_vec = vec!["red", "red", "yellow", "blue"];
2402
- /// let colors_set = colors_vec.into_iter().collect::<HashSet<&str>>();
2403
- /// assert_eq!(colors_set.len(), 3);
2489
+ /// assert_eq!(v, vec![5, 5, 5, 5, 5]);
2404
2490
/// ```
2405
2491
#[ stable( feature = "rust1" , since = "1.0.0" ) ]
2406
2492
fn from_iter < T : IntoIterator < Item =A > > ( iterator : T ) -> Self ;
@@ -2415,9 +2501,13 @@ pub trait FromIterator<A>: Sized {
2415
2501
/// One benefit of implementing `IntoIterator` is that your type will [work
2416
2502
/// with Rust's `for` loop syntax](index.html#for-loops-and-intoiterator).
2417
2503
///
2504
+ /// See also: [`FromIterator`].
2505
+ ///
2506
+ /// [`FromIterator`]: trait.FromIterator.html
2507
+ ///
2418
2508
/// # Examples
2419
2509
///
2420
- /// Vectors implement `IntoIterator` :
2510
+ /// Basic usage :
2421
2511
///
2422
2512
/// ```
2423
2513
/// let v = vec![1, 2, 3];
@@ -2489,7 +2579,33 @@ pub trait IntoIterator {
2489
2579
#[ stable( feature = "rust1" , since = "1.0.0" ) ]
2490
2580
type IntoIter : Iterator < Item =Self :: Item > ;
2491
2581
2492
- /// Consumes `Self` and returns an iterator over it.
2582
+ /// Creates an iterator from a value.
2583
+ ///
2584
+ /// See the [module-level documentation] for more.
2585
+ ///
2586
+ /// [module-level documentation]: trait.IntoIterator.html
2587
+ ///
2588
+ /// # Examples
2589
+ ///
2590
+ /// Basic usage:
2591
+ ///
2592
+ /// ```
2593
+ /// let v = vec![1, 2, 3];
2594
+ ///
2595
+ /// let mut iter = v.into_iter();
2596
+ ///
2597
+ /// let n = iter.next();
2598
+ /// assert_eq!(Some(1), n);
2599
+ ///
2600
+ /// let n = iter.next();
2601
+ /// assert_eq!(Some(2), n);
2602
+ ///
2603
+ /// let n = iter.next();
2604
+ /// assert_eq!(Some(3), n);
2605
+ ///
2606
+ /// let n = iter.next();
2607
+ /// assert_eq!(None, n);
2608
+ /// ```
2493
2609
#[ stable( feature = "rust1" , since = "1.0.0" ) ]
2494
2610
fn into_iter ( self ) -> Self :: IntoIter ;
2495
2611
}
0 commit comments