std: Add a new `env` module

This is an implementation of [RFC 578][rfc] which adds a new `std::env` module
to replace most of the functionality in the current `std::os` module. More
details can be found in the RFC itself, but as a summary the following methods
have all been deprecated:

[rfc]: https://github.com/rust-lang/rfcs/pull/578

* `os::args_as_bytes`   => `env::args`
* `os::args`            => `env::args`
* `os::consts`          => `env::consts`
* `os::dll_filename`    => no replacement, use `env::consts` directly
* `os::page_size`       => `env::page_size`
* `os::make_absolute`   => use `env::current_dir` + `join` instead
* `os::getcwd`          => `env::current_dir`
* `os::change_dir`      => `env::set_current_dir`
* `os::homedir`         => `env::home_dir`
* `os::tmpdir`          => `env::temp_dir`
* `os::join_paths`      => `env::join_paths`
* `os::split_paths`     => `env::split_paths`
* `os::self_exe_name`   => `env::current_exe`
* `os::self_exe_path`   => use `env::current_exe` + `pop`
* `os::set_exit_status` => `env::set_exit_status`
* `os::get_exit_status` => `env::get_exit_status`
* `os::env`             => `env::vars`
* `os::env_as_bytes`    => `env::vars`
* `os::getenv`          => `env::var` or `env::var_string`
* `os::getenv_as_bytes` => `env::var`
* `os::setenv`          => `env::set_var`
* `os::unsetenv`        => `env::remove_var`

Many function signatures have also been tweaked for various purposes, but the
main changes were:

* `Vec`-returning APIs now all return iterators instead
* All APIs are now centered around `OsString` instead of `Vec<u8>` or `String`.
  There is currently on convenience API, `env::var_string`, which can be used to
  get the value of an environment variable as a unicode `String`.

All old APIs are `#[deprecated]` in-place and will remain for some time to allow
for migrations. The semantics of the APIs have been tweaked slightly with regard
to dealing with invalid unicode (panic instead of replacement).

The new `std::env` module is all contained within the `env` feature, so crates
must add the following to access the new APIs:

    #![feature(env)]

[breaking-change]

2 files changed, 88 insertions, 5 deletions

diff --git a/src/libstd/ffi/mod.rs b/src/libstd/ffi/mod.rs
index 69ada28a4b4..76f925a23f1 100644
--- a/src/libstd/ffi/mod.rs
+++ b/src/libstd/ffi/mod.rs
@@ -20,7 +20,12 @@ pub use self::c_str::c_str_to_bytes_with_nul;
 
 pub use self::os_str::OsString;
 pub use self::os_str::OsStr;
-pub use self::os_str::AsOsStr;
 
 mod c_str;
 mod os_str;
+
+/// Freely convertible to an `&OsStr` slice.
+pub trait AsOsStr {
+    /// Convert to an `&OsStr` slice.
+    fn as_os_str(&self) -> &OsStr;
+}
diff --git a/src/libstd/ffi/os_str.rs b/src/libstd/ffi/os_str.rs
index 18e2aa8c098..57489e86230 100644
--- a/src/libstd/ffi/os_str.rs
+++ b/src/libstd/ffi/os_str.rs
@@ -41,9 +41,11 @@ use string::{String, CowString};
 use ops;
 use cmp;
 use hash::{Hash, Hasher, Writer};
+use path::{Path, GenericPath};
 
 use sys::os_str::{Buf, Slice};
 use sys_common::{AsInner, IntoInner, FromInner};
+use super::AsOsStr;
 
 /// Owned, mutable OS strings.
 #[derive(Clone)]
@@ -69,6 +71,11 @@ impl OsString {
         OsString { inner: Buf::from_str(s) }
     }
 
+    /// Constructs a new empty `OsString`.
+    pub fn new() -> OsString {
+        OsString { inner: Buf::from_string(String::new()) }
+    }
+
     /// Convert the `OsString` into a `String` if it contains valid Unicode data.
     ///
     /// On failure, ownership of the original `OsString` is returned.
@@ -117,6 +124,62 @@ impl Debug for OsString {
     }
 }
 
+impl PartialEq for OsString {
+    fn eq(&self, other: &OsString) -> bool {
+        &**self == &**other
+    }
+}
+
+impl PartialEq<str> for OsString {
+    fn eq(&self, other: &str) -> bool {
+        &**self == other
+    }
+}
+
+impl PartialEq<OsString> for str {
+    fn eq(&self, other: &OsString) -> bool {
+        &**other == self
+    }
+}
+
+impl Eq for OsString {}
+
+impl PartialOrd for OsString {
+    #[inline]
+    fn partial_cmp(&self, other: &OsString) -> Option<cmp::Ordering> {
+        (&**self).partial_cmp(&**other)
+    }
+    #[inline]
+    fn lt(&self, other: &OsString) -> bool { &**self < &**other }
+    #[inline]
+    fn le(&self, other: &OsString) -> bool { &**self <= &**other }
+    #[inline]
+    fn gt(&self, other: &OsString) -> bool { &**self > &**other }
+    #[inline]
+    fn ge(&self, other: &OsString) -> bool { &**self >= &**other }
+}
+
+impl PartialOrd<str> for OsString {
+    #[inline]
+    fn partial_cmp(&self, other: &str) -> Option<cmp::Ordering> {
+        (&**self).partial_cmp(other)
+    }
+}
+
+impl Ord for OsString {
+    #[inline]
+    fn cmp(&self, other: &OsString) -> cmp::Ordering {
+        (&**self).cmp(&**other)
+    }
+}
+
+impl<'a, S: Hasher + Writer> Hash<S> for OsString {
+    #[inline]
+    fn hash(&self, state: &mut S) {
+        (&**self).hash(state)
+    }
+}
+
 impl OsStr {
     /// Coerce directly from a `&str` slice to a `&OsStr` slice.
     pub fn from_str(s: &str) -> &OsStr {
@@ -222,10 +285,10 @@ impl ToOwned<OsString> for OsStr {
     fn to_owned(&self) -> OsString { self.to_os_string() }
 }
 
-/// Freely convertible to an `&OsStr` slice.
-pub trait AsOsStr {
-    /// Convert to an `&OsStr` slice.
-    fn as_os_str(&self) -> &OsStr;
+impl<'a, T: AsOsStr + ?Sized> AsOsStr for &'a T {
+    fn as_os_str(&self) -> &OsStr {
+        (*self).as_os_str()
+    }
 }
 
 impl AsOsStr for OsStr {
@@ -252,6 +315,21 @@ impl AsOsStr for String {
     }
 }
 
+#[cfg(unix)]
+impl AsOsStr for Path {
+    fn as_os_str(&self) -> &OsStr {
+        unsafe { mem::transmute(self.as_vec()) }
+    }
+}
+
+#[cfg(windows)]
+impl AsOsStr for Path {
+    fn as_os_str(&self) -> &OsStr {
+        // currently .as_str() is actually infallible on windows
+        OsStr::from_str(self.as_str().unwrap())
+    }
+}
+
 impl FromInner<Buf> for OsString {
     fn from_inner(buf: Buf) -> OsString {
         OsString { inner: buf }