Class Environment

Class Documentation

class Environment

The Environment class is intended to make dealing with managing process environments simpler, in a cross-platform manner. Environments can be copied for mamipulation without affecting the current running environment; they can be applied at will for immediate effect; variables can be added and removed easily.

Public Types

typedef void (*KeyValuePairEnumerateFn)(char const *key, char const *value, int index, void *context)

Public Functions

Environment()

Creates an empty Environment (no key/value pairs).

Environment(char const *const *envp)

Creates an environment that is initialized from a null-terminated array of UTF-8 string pointers.

Parameters

envp -- Null-terminated array of UTF-8 strings. Usually this variable comes from either the "environ" variable available in most C runtimes, or the "envp" variable that is available in both execve() and main().

Environment(Environment const &other)

Environment copy constructor.

Parameters

other -- Existing environment to duplicate

~Environment()
Environment &operator=(Environment const &other)
bool operator!=(Environment const &other) const
int GetKeyCount() const

Obtain number of key/value pairs defined in the environment.

Returns

The number of key/value pairs defined in the environment.

bool Empty() const

Determine if any key/value pairs exist in the Environment.

Returns

True if one or more key value pairs exist; false otherwise

char const *Get(char const *key) const

Get the current value for the given key.

Parameters

key -- Variable name (case-sensitive)

Returns

Variable value if present, or nullptr if the variable is not defined.

void GetAllKeysValues(char const **keys, char const **values, int *count) const

Get all keys and their values into two different user-supplied arrays.

keys, values and count pointers must not be nullptr; the value pointed to by count must be positive (non-zero). The caller can obtain the number of environment variables by calling GetKeyCount(). Copying of keys and values will proceed in lexical order of key names, and will stop when reaching the number of value specified by the integer pointed to by count. If fewer variables exist in the environment than the integer value in count, then upon return the integer variable pointed to by count will contain the actual number of values copied.

Parameters

  • keys -- Array of const-char* to receive the key names.

  • values -- Array of const-char* to receive the key values.

  • count -- Length of each array.

void Set(char const *key, char const *newValue)

Set an environment variable.

Parameters

  • key -- Name of the variable

  • newValue -- New variable value. Existing variable values will be overwritten; if no variable named by key existed prior to this call, a new variable will be created and will have newValue for its value.

void Remove(char const *key)

Remove an environment variable.

Parameters

key -- Name of the variable to remove from the environment. No effect if the variable does not exist.

void AppendToPathValue(char const *key, char const *additionalPath)

AppendToPathValue Add additionalPath at the end of the specified path environment variable.

Does not perform automatic conversion of platform-specific path separators (for example, converting / to \ on Windows, and vice versa on POSIX systems). Will first append, if necessary, a platform-specific environment-variable separator (for example, ; on Windows and : on POSIX systems). Will create a new variable named after key if environment variable does not yet exist.

Parameters

  • key -- Name of the path environment variable to append.

  • additionalPath -- Path data to append.

void PrependToPathValue(char const *key, char const *additionalPath)

PrependToPathValue Add additionalPath to the beginning of the specified path environment variable.

Does not perform automatic conversion of platform-specific path separators (for example, converting / to \ on Windows, and vice versa on POSIX systems). Will append, if necessary, a platform-specific environment-variable separator (for example, ; on Windows and : on POSIX systems). Will create a new variable named after key if environment variable does not yet exist.

Parameters

  • key -- Name of the path environment variable to prepend.

  • additionalPath -- Path data to prepend.

void RemoveFromPathValue(char const *key, char const *pathToRemove)

Remove specified path from an existing path variable.

No effect if key does not exist. Otherwise, upon return, if the specified path string was present in the path variable, it will be removed and the new path variable value will be present for thie environment variable. Does not perform path-separator conversion (for example, / to \ on Windows or vice versa on POSIX).

Parameters

  • key -- Path variable to modify

  • pathToRemove -- Path string to remove

void RemovePathValueContaining(char const *key, char const *stringToFind)

Removes all path entries that contain the specified search string.

Treats the path variable as a list of path entries; for each entry that contains the string specified, that entry will be removed from the list. The string compare is case-sensitive. When this call returns, the variable will be recomposed in the original order, with all matching entries removed.

Parameters

  • key -- Name of path variable to alter.

  • stringToFind -- Substring to find in the path variable.

void InitializeFromCurrentProcess()

(Re-)Initialize this Environment with all key/value pairs from the current process' environment.

void ApplyToCurrentProcess(bool replaceWholeEnvironment = false)

Apply this Environment to the current process, optionally overwriting the entire process environment.

Parameters

replaceWholeEnvironment -- If true, then the entire process' current environment will be wiped out and replaced fully by this Environment. If false (the default), then this Environment will be merged into the current process' environment (overwriting environment entries with names matching keys in this Environment — entries will not be merged!)

void MergeFrom(Environment const &other)

Merge all variables from other into this Environment object. Existing keys in this environment will be fully overwritten by matching values from other Environment.

Parameters

other -- Environment to merge into this Environment.

void EnumerateKeyValuePairs(KeyValuePairEnumerateFn callback, void *context) const