cargo::util::context::environment

# Struct Env

Source

    pub struct Env {
        env: HashMap<OsString, OsString>,
        normalized_env: HashMap<String, String>,
        case_insensitive_env: HashMap<String, String>,
    }

Expand description

A snapshot of the environment variables available to `GlobalContext`.

Currently, the `GlobalContext` supports lookup of environment variables through two different means:

- `GlobalContext::get_env` and `GlobalContext::get_env_os` for process environment variables (similar to `std::env::var` and `std::env::var_os`),
- Typed Config Value API via `GlobalContext::get`. This is only available for `CARGO_` prefixed environment keys.

This type contains the env var snapshot and helper methods for both APIs.

## Fields§

§`env: HashMap<OsString, OsString>`

A snapshot of the process’s environment variables.

§`normalized_env: HashMap<String, String>`

Used in the typed Config value API for warning messages when config keys are given in the wrong format.

Maps from “normalized” (upper case and with “-” replaced by “_”) env keys to the actual keys in the environment. The normalized format is the one expected by Cargo.

This only holds env keys that are valid UTF-8, since `super::ConfigKey` only supports UTF-8 keys. In addition, this only holds env keys whose value in the environment is also valid UTF-8, since the typed Config value API only supports UTF-8 values.

§`case_insensitive_env: HashMap<String, String>`

Used to implement `get_env` and `get_env_os` on Windows, where env keys are case-insensitive.

Maps from uppercased env keys to the actual key in the environment. For example, this might hold a pair `("PATH", "Path")`. Currently only supports UTF-8 keys and values.

## Implementations§

Source§

### impl Env

Source

#### pub fn new() -> Self

Create a new `Env` from process’s environment variables.

Source

#### pub(super) fn from_map(env: HashMap<String, String>) -> Self

Set the env directly from a `HashMap`. This should be used for debugging purposes only.

Source

#### pub fn iter_str(&self) -> impl Iterator<Item = (&str, &str)>

Returns all environment variables as an iterator, keeping only entries where both the key and value are valid UTF-8.

Source

#### pub fn keys_str(&self) -> impl Iterator<Item = &str>

Returns all environment variable keys, filtering out keys that are not valid UTF-8.

Source

#### pub fn get_env_os(&self, key: impl AsRef<OsStr>) -> Option<&OsStr>

Get the value of environment variable `key` through the snapshot in `GlobalContext`.

This can be used similarly to `std::env::var_os`. On Windows, we check for case mismatch since environment keys are case-insensitive.

Source

#### pub fn get_env(&self, key: impl AsRef<OsStr>) -> CargoResult<&str>

Get the value of environment variable `key` through the `self.env` snapshot.

This can be used similarly to `std::env::var`. On Windows, we check for case mismatch since environment keys are case-insensitive.

Source

#### fn get_env_case_insensitive(&self, key: impl AsRef<OsStr>) -> Option<&OsStr>

Performs a case-insensitive lookup of `key` in the environment.

This is relevant on Windows, where environment variables are case-insensitive. Note that this only works on keys that are valid UTF-8 and it uses Unicode uppercase, which may differ from the OS’s notion of uppercase.

Source

#### pub(super) fn get_str(&self, key: impl AsRef<OsStr>) -> Option<&str>

Get the value of environment variable `key` as a `&str`. Returns `None` if `key` is not in `self.env` or if the value is not valid UTF-8.

This is intended for use in private methods of `GlobalContext`, and does not check for env key case mismatch.

This is case-sensitive on Windows (even though environment keys on Windows are usually case-insensitive) due to an unintended regression in 1.28 (via #5552). This should only affect keys used for cargo’s config-system env variables (`CARGO_` prefixed ones), which are currently all uppercase. We may want to consider rectifying it if users report issues. One thing that adds a wrinkle here is the unstable advanced-env option that requires case-sensitive keys.

Do not use this for any other purposes. Use `Env::get_env_os` or `Env::get_env` instead, which properly handle case insensitivity on Windows.

Source

#### pub(super) fn contains_key(&self, key: impl AsRef<OsStr>) -> bool

Check if the environment contains `key`.

This is intended for use in private methods of `GlobalContext`, and does not check for env key case mismatch. See the docstring of `Env::get_str` for more context.

Source

#### pub(super) fn get_normalized(&self, key: &str) -> Option<&str>

Looks up a normalized `key` in the `normalized_env`. Returns the corresponding (non-normalized) env key if it exists, else `None`.

This is used by `super::GlobalContext::check_environment_key_case_mismatch`.

## Trait Implementations§

Source§

### impl Debug for Env

Source§

#### fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter. Read more

## Auto Trait Implementations§

§

### impl Freeze for Env

§

### impl RefUnwindSafe for Env

§

### impl Send for Env

§

### impl Sync for Env

§

### impl Unpin for Env

§

### impl UnwindSafe for Env

## Blanket Implementations§

Source§

### impl<T> Any for T
where T: 'static + ?Sized,

Source§

#### fn type_id(&self) -> TypeId

Gets the `TypeId` of `self`. Read more
Source§

### impl<T> Borrow<T> for T
where T: ?Sized,

Source§

#### fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
Source§

### impl<T> BorrowMut<T> for T
where T: ?Sized,

Source§

#### fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
Source§

### impl<T> From<T> for T

Source§

#### fn from(t: T) -> T

Returns the argument unchanged.

§

### impl<T> Instrument for T

§

#### fn instrument(self, span: Span) -> Instrumented<Self>

Instruments this type with the provided [`Span`], returning an `Instrumented` wrapper. Read more
§

#### fn in_current_span(self) -> Instrumented<Self>

Instruments this type with the current `Span`, returning an `Instrumented` wrapper. Read more
Source§

### impl<T, U> Into<U> for T
where U: From<T>,

Source§

#### fn into(self) -> U

Calls `U::from(self)`.

That is, this conversion is whatever the implementation of `From<T> for U` chooses to do.

Source§

### impl<T> IntoEither for T

Source§

#### fn into_either(self, into_left: bool) -> Either<Self, Self>

Converts `self` into a `Left` variant of `Either<Self, Self>` if `into_left` is `true`. Converts `self` into a `Right` variant of `Either<Self, Self>` otherwise. Read more
Source§

#### fn into_either_with<F>(self, into_left: F) -> Either<Self, Self>
where F: FnOnce(&Self) -> bool,

Converts `self` into a `Left` variant of `Either<Self, Self>` if `into_left(&self)` returns `true`. Converts `self` into a `Right` variant of `Either<Self, Self>` otherwise. Read more
§

### impl<T> Pointable for T

§

#### const ALIGN: usize

The alignment of pointer.
§

#### type Init = T

The type for initializers.
§

#### unsafe fn init(init: <T as Pointable>::Init) -> usize

Initializes a with the given initializer. Read more
§

#### unsafe fn deref<'a>(ptr: usize) -> &'a T

Dereferences the given pointer. Read more
§

#### unsafe fn deref_mut<'a>(ptr: usize) -> &'a mut T

Mutably dereferences the given pointer. Read more
§

#### unsafe fn drop(ptr: usize)

Drops the object pointed to by the given pointer. Read more
Source§

### impl<T> Same for T

Source§

#### type Output = T

Should always be `Self`
Source§

### impl<T, U> TryFrom<U> for T
where U: Into<T>,

Source§

#### type Error = Infallible

The type returned in the event of a conversion error.
Source§

#### fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.
Source§

### impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

Source§

#### type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
Source§

#### fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.
§

### impl<V, T> VZip<V> for T
where V: MultiLane<T>,

§

#### fn vzip(self) -> V

§

### impl<T> WithSubscriber for T

§

#### fn with_subscriber<S>(self, subscriber: S) -> WithDispatch<Self>
where S: Into<Dispatch>,

Attaches the provided `Subscriber` to this type, returning a [`WithDispatch`] wrapper. Read more
§

#### fn with_current_subscriber(self) -> WithDispatch<Self>

Attaches the current default `Subscriber` to this type, returning a [`WithDispatch`] wrapper. Read more
§

### impl<T> ErasedDestructor for T
where T: 'static,

§

### impl<T> MaybeSendSync for T

## Layout§

Note: Most layout information is completely unstable and may even differ between compilations. The only exception is types with certain `repr(...)` attributes. Please see the Rust Reference's “Type Layout” chapter for details on type layout guarantees.

Size: 144 bytes