Auto merge of #33312 - Byron:double-ended-iterator-for-args, r=alexcrichton

DoubleEndedIterator for Args

This PR implements the DoubleEndedIterator trait for the `std::env::Args[Os]` structure, as well
as the internal implementations.

It is primarily motivated by me, as I happened to implement a simple `reversor` program many times
now, which so far had to use code like this:

```Rust
for arg in std::env::args().skip(1).collect::<Vec<_>>().iter().rev() {}
```

... even though I would have loved to do this instead:

```Rust
for arg in std::env::args().skip(1).rev() {}
```

The latter is more natural, and I did not find a reason for not implementing it.
After all, on every system, the number of arguments passed to the program are known
at runtime.

To my mind, it follows KISS, and does not try to be smart at all. Also, there are no unit-tests,
primarily as I did not find any existing tests for the `Args` struct either.

The windows implementation is basically a copy-pasted variant of the `next()` method implementation,
and I could imagine sharing most of the code instead. Actually I would be happy if the reviewer would
ask for it.

src/libstd/env.rs

@@ -625,6 +625,13 @@ impl ExactSizeIterator for Args {
     fn len(&self) -> usize { self.inner.len() }
 }
 
+#[stable(feature = "env_iterators", since = "1.11.0")]
+impl DoubleEndedIterator for Args {
+    fn next_back(&mut self) -> Option<String> {
+        self.inner.next_back().map(|s| s.into_string().unwrap())
+    }
+}
+
 #[stable(feature = "env", since = "1.0.0")]
 impl Iterator for ArgsOs {
     type Item = OsString;
@@ -637,6 +644,10 @@ impl ExactSizeIterator for ArgsOs {
     fn len(&self) -> usize { self.inner.len() }
 }
 
+#[stable(feature = "env_iterators", since = "1.11.0")]
+impl DoubleEndedIterator for ArgsOs {
+    fn next_back(&mut self) -> Option<OsString> { self.inner.next_back() }
+}
 /// Constants associated with the current target
 #[stable(feature = "env", since = "1.0.0")]
 pub mod consts {

src/libstd/sys/unix/os.rs

@@ -317,6 +317,10 @@ impl ExactSizeIterator for Args {
     fn len(&self) -> usize { self.iter.len() }
 }
 
+impl DoubleEndedIterator for Args {
+    fn next_back(&mut self) -> Option<OsString> { self.iter.next_back() }
+}
+
 /// Returns the command line arguments
 ///
 /// Returns a list of the command line arguments.

src/libstd/sys/windows/os.rs

@@ -278,23 +278,30 @@ pub struct Args {
     cur: *mut *mut u16,
 }
 
+unsafe fn os_string_from_ptr(ptr: *mut u16) -> OsString {
+    let mut len = 0;
+    while *ptr.offset(len) != 0 { len += 1; }
+
+    // Push it onto the list.
+    let ptr = ptr as *const u16;
+    let buf = slice::from_raw_parts(ptr, len as usize);
+    OsStringExt::from_wide(buf)
+}
+
 impl Iterator for Args {
     type Item = OsString;
     fn next(&mut self) -> Option<OsString> {
-        self.range.next().map(|i| unsafe {
-            let ptr = *self.cur.offset(i);
-            let mut len = 0;
-            while *ptr.offset(len) != 0 { len += 1; }
-
-            // Push it onto the list.
-            let ptr = ptr as *const u16;
-            let buf = slice::from_raw_parts(ptr, len as usize);
-            OsStringExt::from_wide(buf)
-        })
+        self.range.next().map(|i| unsafe { os_string_from_ptr(*self.cur.offset(i)) } )
     }
     fn size_hint(&self) -> (usize, Option<usize>) { self.range.size_hint() }
 }
 
+impl DoubleEndedIterator for Args {
+    fn next_back(&mut self) -> Option<OsString> {
+        self.range.next_back().map(|i| unsafe { os_string_from_ptr(*self.cur.offset(i)) } )
+    }
+}
+
 impl ExactSizeIterator for Args {
     fn len(&self) -> usize { self.range.len() }
 }

src/test/run-pass/env-args-reverse-iterator.rs

+// Copyright 2014 The Rust Project Developers. See the COPYRIGHT
+// file at the top-level directory of this distribution and at
+// http://rust-lang.org/COPYRIGHT.
+//
+// Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or
+// http://www.apache.org/licenses/LICENSE-2.0> or the MIT license
+// <LICENSE-MIT or http://opensource.org/licenses/MIT>, at your
+// option. This file may not be copied, modified, or distributed
+// except according to those terms.
+
+use std::env::args;
+use std::process::Command;
+
+fn assert_reverse_iterator_for_program_arguments(program_name: &str) {
+    let args: Vec<_> = args().rev().collect();
+
+    assert!(args.len() == 4);
+    assert_eq!(args[0], "c");
+    assert_eq!(args[1], "b");
+    assert_eq!(args[2], "a");
+    assert_eq!(args[3], program_name);
+
+    println!("passed");
+}
+
+fn main() {
+    let mut args = args();
+    let me = args.next().unwrap();
+
+    if let Some(_) = args.next() {
+        assert_reverse_iterator_for_program_arguments(&me);
+        return
+    }
+
+    let output = Command::new(&me)
+        .arg("a")
+        .arg("b")
+        .arg("c")
+        .output()
+        .unwrap();
+    assert!(output.status.success());
+    assert!(output.stderr.is_empty());
+    assert_eq!(output.stdout, b"passed\n");
+}