/// An iterator over a snapshot of the environment variables of this process.
///
-/// This iterator is created through `std::env::vars()` and yields `(OsString,
-/// OsString)` pairs.
-pub struct Vars { inner: os_imp::Env }
+/// This iterator is created through `std::env::vars()` and yields `(String,
+/// String)` pairs.
+pub struct Vars { inner: VarsOs }
-/// Returns an iterator of (variable, value) pairs, for all the environment
-/// variables of the current process.
+/// An iterator over a snapshot of the environment variables of this process.
+///
+/// This iterator is created through `std::env::vars_os()` and yields
+/// `(OsString, OsString)` pairs.
+pub struct VarsOs { inner: os_imp::Env }
+
+/// Returns an iterator of (variable, value) pairs of strings, for all the
+/// environment variables of the current process.
///
/// The returned iterator contains a snapshot of the process's environment
/// variables at the time of this invocation, modifications to environment
/// variables afterwards will not be reflected in the returned iterator.
///
+/// # Panics
+///
+/// While iterating, the returned iterator will panic if any key or value in the
+/// environment is not valid unicode. If this is not desired, consider using the
+/// `env::vars_os` function.
+///
/// # Example
///
/// ```rust
/// // We will iterate through the references to the element returned by
/// // env::vars();
/// for (key, value) in env::vars() {
-/// println!("{:?}: {:?}", key, value);
+/// println!("{}: {}", key, value);
/// }
/// ```
pub fn vars() -> Vars {
- let _g = ENV_LOCK.lock();
- Vars { inner: os_imp::env() }
-}
-
-impl Iterator for Vars {
- type Item = (OsString, OsString);
- fn next(&mut self) -> Option<(OsString, OsString)> { self.inner.next() }
- fn size_hint(&self) -> (usize, Option<usize>) { self.inner.size_hint() }
+ Vars { inner: vars_os() }
}
-/// Fetches the environment variable `key` from the current process, returning
-/// None if the variable isn't set.
+/// Returns an iterator of (variable, value) pairs of OS strings, for all the
+/// environment variables of the current process.
+///
+/// The returned iterator contains a snapshot of the process's environment
+/// variables at the time of this invocation, modifications to environment
+/// variables afterwards will not be reflected in the returned iterator.
///
/// # Example
///
/// ```rust
/// use std::env;
///
-/// let key = "HOME";
-/// match env::var(key) {
-/// Some(val) => println!("{}: {:?}", key, val),
-/// None => println!("{} is not defined in the environment.", key)
+/// // We will iterate through the references to the element returned by
+/// // env::vars_os();
+/// for (key, value) in env::vars_os() {
+/// println!("{:?}: {:?}", key, value);
/// }
/// ```
-pub fn var<K: ?Sized>(key: &K) -> Option<OsString> where K: AsOsStr {
+pub fn vars_os() -> VarsOs {
let _g = ENV_LOCK.lock();
- os_imp::getenv(key.as_os_str())
+ VarsOs { inner: os_imp::env() }
+}
+
+impl Iterator for Vars {
+ type Item = (String, String);
+ fn next(&mut self) -> Option<(String, String)> {
+ self.inner.next().map(|(a, b)| {
+ (a.into_string().unwrap(), b.into_string().unwrap())
+ })
+ }
+ fn size_hint(&self) -> (usize, Option<usize>) { self.inner.size_hint() }
+}
+
+impl Iterator for VarsOs {
+ type Item = (OsString, OsString);
+ fn next(&mut self) -> Option<(OsString, OsString)> { self.inner.next() }
+ fn size_hint(&self) -> (usize, Option<usize>) { self.inner.size_hint() }
}
/// Fetches the environment variable `key` from the current process.
/// use std::env;
///
/// let key = "HOME";
-/// match env::var_string(key) {
+/// match env::var(key) {
/// Ok(val) => println!("{}: {:?}", key, val),
/// Err(e) => println!("couldn't interpret {}: {}", key, e),
/// }
/// ```
-pub fn var_string<K: ?Sized>(key: &K) -> Result<String, VarError> where K: AsOsStr {
- match var(key) {
+pub fn var<K: ?Sized>(key: &K) -> Result<String, VarError> where K: AsOsStr {
+ match var_os(key) {
Some(s) => s.into_string().map_err(VarError::NotUnicode),
None => Err(VarError::NotPresent)
}
}
+/// Fetches the environment variable `key` from the current process, returning
+/// None if the variable isn't set.
+///
+/// # Example
+///
+/// ```rust
+/// use std::env;
+///
+/// let key = "HOME";
+/// match env::var_os(key) {
+/// Some(val) => println!("{}: {:?}", key, val),
+/// None => println!("{} is not defined in the environment.", key)
+/// }
+/// ```
+pub fn var_os<K: ?Sized>(key: &K) -> Option<OsString> where K: AsOsStr {
+ let _g = ENV_LOCK.lock();
+ os_imp::getenv(key.as_os_str())
+}
+
/// Possible errors from the `env::var` method.
#[derive(Debug, PartialEq, Eq, Clone)]
pub enum VarError {
///
/// let key = "KEY";
/// env::set_var(key, "VALUE");
-/// assert_eq!(env::var_string(key), Ok("VALUE".to_string()));
+/// assert_eq!(env::var(key), Ok("VALUE".to_string()));
/// ```
pub fn set_var<K: ?Sized, V: ?Sized>(k: &K, v: &V)
where K: AsOsStr, V: AsOsStr
/// use std::env;
///
/// let key = "PATH";
-/// match env::var(key) {
+/// match env::var_os(key) {
/// Some(paths) => {
/// for path in env::split_paths(&paths) {
/// println!("'{}'", path.display());
/// ```rust
/// use std::env;
///
-/// if let Some(path) = env::var("PATH") {
+/// if let Some(path) = env::var_os("PATH") {
/// let mut paths = env::split_paths(&path).collect::<Vec<_>>();
/// paths.push(Path::new("/home/xyz/bin"));
/// let new_path = env::join_paths(paths.iter()).unwrap();
EXIT_STATUS.load(Ordering::SeqCst) as i32
}
-/// An iterator over the arguments of a process, yielding an `OsString` value
+/// An iterator over the arguments of a process, yielding an `String` value
/// for each argument.
///
/// This structure is created through the `std::env::args` method.
-pub struct Args { inner: os_imp::Args }
+pub struct Args { inner: ArgsOs }
+
+/// An iterator over the arguments of a process, yielding an `OsString` value
+/// for each argument.
+///
+/// This structure is created through the `std::env::args_os` method.
+pub struct ArgsOs { inner: os_imp::Args }
/// Returns the arguments which this program was started with (normally passed
/// via the command line).
/// set to arbitrary text, and it may not even exist, so this property should
/// not be relied upon for security purposes.
///
+/// # Panics
+///
+/// The returned iterator will panic during iteration if any argument to the
+/// process is not valid unicode. If this is not desired it is recommended to
+/// use the `args_os` function instead.
+///
/// # Example
///
/// ```rust
///
/// // Prints each argument on a separate line
/// for argument in env::args() {
-/// println!("{:?}", argument);
+/// println!("{}", argument);
/// }
/// ```
pub fn args() -> Args {
- Args { inner: os_imp::args() }
+ Args { inner: args_os() }
+}
+
+/// Returns the arguments which this program was started with (normally passed
+/// via the command line).
+///
+/// The first element is traditionally the path to the executable, but it can be
+/// set to arbitrary text, and it may not even exist, so this property should
+/// not be relied upon for security purposes.
+///
+/// # Example
+///
+/// ```rust
+/// use std::env;
+///
+/// // Prints each argument on a separate line
+/// for argument in env::args_os() {
+/// println!("{:?}", argument);
+/// }
+/// ```
+pub fn args_os() -> ArgsOs {
+ ArgsOs { inner: os_imp::args() }
}
impl Iterator for Args {
+ type Item = String;
+ fn next(&mut self) -> Option<String> {
+ self.inner.next().map(|s| s.into_string().unwrap())
+ }
+ fn size_hint(&self) -> (usize, Option<usize>) { self.inner.size_hint() }
+}
+
+impl Iterator for ArgsOs {
type Item = OsString;
fn next(&mut self) -> Option<OsString> { self.inner.next() }
fn size_hint(&self) -> (usize, Option<usize>) { self.inner.size_hint() }
let n = format!("TEST{}", rng.gen_ascii_chars().take(10)
.collect::<String>());
let n = OsString::from_string(n);
- assert!(var(&n).is_none());
+ assert!(var_os(&n).is_none());
n
}
fn test_set_var() {
let n = make_rand_name();
set_var(&n, "VALUE");
- eq(var(&n), Some("VALUE"));
+ eq(var_os(&n), Some("VALUE"));
}
#[test]
let n = make_rand_name();
set_var(&n, "VALUE");
remove_var(&n);
- eq(var(&n), None);
+ eq(var_os(&n), None);
}
#[test]
let n = make_rand_name();
set_var(&n, "1");
set_var(&n, "2");
- eq(var(&n), Some("2"));
+ eq(var_os(&n), Some("2"));
set_var(&n, "");
- eq(var(&n), Some(""));
+ eq(var_os(&n), Some(""));
}
#[test]
}
let n = make_rand_name();
set_var(&n, s.as_slice());
- eq(var(&n), Some(s.as_slice()));
+ eq(var_os(&n), Some(s.as_slice()));
}
#[test]
let n = make_rand_name();
let s = repeat("x").take(10000).collect::<String>();
set_var(&n, &s);
- eq(var(&n), Some(s.as_slice()));
+ eq(var_os(&n), Some(s.as_slice()));
remove_var(&n);
- eq(var(&n), None);
+ eq(var_os(&n), None);
}
#[test]
fn test_env_set_var() {
let n = make_rand_name();
- let mut e = vars();
+ let mut e = vars_os();
set_var(&n, "VALUE");
assert!(!e.any(|(k, v)| {
&*k == &*n && &*v == "VALUE"
}));
- assert!(vars().any(|(k, v)| {
+ assert!(vars_os().any(|(k, v)| {
&*k == &*n && &*v == "VALUE"
}));
}
projects / rust.git / commitdiff