Amend RFC 517: Add material on std::env

[aturon]

The IO reform RFC is being split into several semi-independent pieces, posted as PRs like this one.

This RFC amendment adds material for std::env.

Rendered

[sfackler]

IntoOsStrBuf or IntoOsStr?

[alexcrichton]

I believe that these APIs will need to go into an OsStrBuf regardless as they need to be passed to a system API which means they have to be nul-terminated (and a slice won't have the terminator).

[alexcrichton]

These actually all ended up being AsStrBuf anyway, so I think the RFC just needs to be updated.

[wycats]

I think it would make more sense for these APIs to return a Result<String, EnvError> where EnvError is:

enum EnvError {
  Missing,
  NotUnicode(OsString)
}

That way you can quickly and ergonomically get at a String, which is usually what you want, but still get at the OsString if you really need it (usually to present a good error message).

[wycats]

Sorry, to be more precise, I think it makes sense to have two variants of these APIs, one of which provides an Option<OsString> and one of which provides a Result.

I would propose var for the version that returns a Result<String, E> and raw_var for the one that returns an Option<OsString>

[arthurprs]

Please let's get the names consistent using cpu_count instead of num_cpus.

Ya, there's a lot of discussion in the previous PR about thread/physical-core count and here.
I believe that in the software world what matters (at least in 95%+ of the cases) is the thread count and thus that's what should be in the stdlib. This is also consistent with other programming languages behaviors (GO, C++, etc..). Details like socket count, physical core counts, etc.. should be elsewhere.

[alexcrichton]

I've got a working implementation of std::env currently through cargo here: https://github.com/alexcrichton/io2/blob/master/src/env.rs

There are still a few lingering questions on this RFC, but I'd like to propose marking those APIs as #[unstable] so we can start moving to OsString instead of String being returned from some of the less controversial APIs to get some traction using it. Specifically, I believe the remaining will all still be #[unstable] pending a future RFC to stabilize them:

• num_cpus - we could rename to cpu_count perhaps right now, but there are also reasons to avoid cpu_count. All in all the naming and semantics here haven't been totally pinned down, so we should leave ourselves to tweaking this in the future.
• {get,set}_exit_status - this may not be the precise interface we'd like to stabilize one. We may want to allow fn main() -> i32 for example, in which case we may not need these at all. For now they're going to remain #[unstable] as they may go away in the future pending other design changes.
• page_size - better safe than sorry! (this also isn't used too too often)

If I missed something though please let me know!

[brson]

join_paths and split_paths seem out of place in a module that seems to be about modifying the global environment.

current_exe is a sort of eccentric function - it exists to support rustc, and I'm not sure that this functionality can be supported universally.

[pcwalton]

@brson: current_exe is used by my e10s patch in Servo. That said, it doesn't have to live in libstd of course.

[aturon]

re: current_exe, note that it yield an Option.

[aturon]

An update on this RFC:

Use of Cow

After discussion above and on IRC, it seems that everyone is basically happy to use Cow in principle for things like arg, but there are some concerns about the implementation and the possible interaction with mutation by non-Rust code. Based on IRC discussion, all parties are OK to go with OsString for now, and to move to Cow if a good enough implementation is available before stabilization.

Variants for returning `String

The idea that @wycats mentioned about String variants came out of an IRC discussion, and I think it's quite nice.

However, it focuses just on var, and the story is somewhat less clear for args and vars, because they return multiple strings (each of which might or might not be unicode). In addition, changing var to be the String variant and having a separate raw_var breaks the symmetry with set_var, which wants an OsString.

I suggest that instead we keep var as proposed, but add a var_string variant with the API @wycats proposed.

[alexcrichton]

There seems to be broad enough support for this RFC that I am going to merge it. There are still some components which are going to be left #[unstable] for a future RFC as the semantics are hammered out and we're still going to allow for future minor updates which may tweak semantics slightly.

Thanks again for all the feedback everyone, it has all been quite helpful!