Fix and undeprecate home_dir()

[kornelski]

home_dir() has been deprecated for 6 years due to using HOME env var on Windows.

It's been a long time, and having a perpetually buggy and deprecated function in the standard library is not useful. I propose fixing and undeprecating it.

6 years seems more than long enough to warn users against relying on this function. The change in behavior is minor, and it's more of a bug fix than breakage. The old behavior is unlikely to be useful, and even if anybody actually needed to specifically use the non-standard HOME on Windows, they can trivially mitigate this change by reading the env var themselves.

---

Use of USERPROFILE is in line with the home crate: https://github.com/rust-lang/cargo/blob/37bc5f0232a0bb72dedd2c14149614fd8cdae649/crates/home/src/windows.rs#L12

The home crate uses SHGetKnownFolderPath instead of GetUserProfileDirectoryW. AFAIK it doesn't make any difference in practice, because SHGetKnownFolderPath merely adds support for more kinds of folders, including virtual (non-filesystem) folders identified by a GUID, but the specific case of FOLDERID_Profile is documented as a FIXED folder (a regular filesystem path). Just in case, I've added a note to documentation that the use of GetUserProfileDirectoryW can change.

I've used CURRENT_RUSTC_VERSION in a doccomment. replace-version-placeholder tool seems to perform a simple string replacement, so hopefully it'll get updated.

[rustbot]

r? @jhpratt

rustbot has assigned @jhpratt.
They will have a look at your PR within the next two weeks and either review your PR or reassign to another reviewer.

Use r? to explicitly pick a reviewer

[jhpratt]

This is a question for @rust-lang/libs-api (or T-libs? not sure). Implementation-wise I don't see anything wrong, so r=me if the team wants it.

[joshtriplett]

I think this is completely reasonable, and having a useful function for this in the standard library is appealing. Let's see if we have consensus to update it.

@rfcbot merge

[rfcbot]

Team member @joshtriplett has proposed to merge this. The next step is review by the rest of the tagged team members:

• @Amanieu
• @BurntSushi
• @dtolnay
• @joshtriplett
• @m-ou-se

No concerns currently listed.

Once a majority of reviewers approve (and at most 2 approvals are outstanding), this will enter its final comment period. If you spot a major issue that hasn't been raised at any point in this process, please speak up!

See this document for info about what commands tagged team members can give me.