Fix and undeprecate home_dir()

Author: kornelski

library/std/src/env.rs

@@ -608,20 +608,16 @@ impl Error for JoinPathsError {
 ///
 /// # Windows
 ///
-/// - Returns the value of the 'HOME' environment variable if it is set
-///   (including to an empty string).
-/// - Otherwise, returns the value of the 'USERPROFILE' environment variable if it is set
-///   (including to an empty string).
-/// - If both do not exist, [`GetUserProfileDirectory`][msdn] is used to return the path.
+/// - Returns the value of the 'USERPROFILE' environment variable if it is set, and is not an empty string.
+/// - Otherwise, [`GetUserProfileDirectory`][msdn] is used to return the path. This may change in the future.
 ///
 /// [msdn]: https://docs.microsoft.com/en-us/windows/win32/api/userenv/nf-userenv-getuserprofiledirectorya
 ///
-/// # Deprecation
+/// In UWP (Universal Windows Platform) targets this function is unimplemented and always returns `None`.
 ///
-/// This function is deprecated because the behavior on Windows is not correct.
-/// The 'HOME' environment variable is not standard on Windows, and may not produce
-/// desired results; for instance, under Cygwin or Mingw it will return `/home/you`
-/// when it should return `C:\Users\you`.
+/// Before Rust CURRENT_RUSTC_VERSION, this function used to return the value of the 'HOME' environment variable
+/// on Windows, which in Cygwin or Mingw environments could return non-standard paths like `/home/you`
+/// instead of `C:\Users\you`.
 ///
 /// # Examples
 ///

library/std/src/sys/pal/windows/os.rs

@@ -377,8 +377,8 @@ fn home_dir_crt() -> Option<PathBuf> {
 }
 
 pub fn home_dir() -> Option<PathBuf> {
-    crate::env::var_os("HOME")
-        .or_else(|| crate::env::var_os("USERPROFILE"))
+    crate::env::var_os("USERPROFILE")
+        .filter(|s| !s.is_empty())
         .map(PathBuf::from)
         .or_else(home_dir_crt)
 }

library/std/tests/env.rs

@@ -122,19 +122,19 @@ fn env_home_dir() {
 
             assert!(home_dir().is_some());
 
-            set_var("HOME", "/home/MountainView");
+            set_var("HOME", "/home/PaloAlto");
+            assert_ne!(home_dir(), Some(PathBuf::from("/home/PaloAlto")), "HOME must not be used");
+
+            set_var("USERPROFILE", "/home/MountainView");
             assert_eq!(home_dir(), Some(PathBuf::from("/home/MountainView")));
 
             remove_var("HOME");
 
-            set_var("USERPROFILE", "/home/MountainView");
             assert_eq!(home_dir(), Some(PathBuf::from("/home/MountainView")));
 
-            set_var("HOME", "/home/MountainView");
-            set_var("USERPROFILE", "/home/PaloAlto");
-            assert_eq!(home_dir(), Some(PathBuf::from("/home/MountainView")));
+            set_var("USERPROFILE", "");
+            assert_ne!(home_dir(), Some(PathBuf::from("")), "Empty USERPROFILE must be ignored");
 
-            remove_var("HOME");
             remove_var("USERPROFILE");
 
             if let Some(oldhome) = oldhome { set_var("HOME", oldhome); }