### IEnvironment

  IEnvironment is a mechanism for building and manipulating environmental variables for passing to the IExternalProcess class. It can certainly have other uses, but that is its primary reason for being added to the OpenClass system. IEnvironment objects are little associative maps, in which the key is a string (the name of the environment variable) and the associated data is also a string (the value of the environment variable.)

  IEnvironment objects can be iterated, in order to step through all of the environment variables that it holds. It also allows you to add or remove variables, and to modify the contents of existing variables.

### IEnvironment - Member Functions and Data by Group

### Constructors & Destructor

Construct and destruct IEnvironment objects.

~IEnvironment
  Cleans up the list of variable/value nodes maintained by the object.

      public:
      ~IEnvironment()

  The destructor will destroy the internal list of variable and and value strings.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

IEnvironment
  Constructing an environment object sets up the internal data structures to get it ready for use. It can also optionally suck in all of the existing environmental variables from the process' environment.

  Overload 1
  Copies another environment object's contents.

      public:
      IEnvironment(const IEnvironment& toCopy)

  The copy constructor just replicates the contents of the passed environment object.

  toCopy
    is the source object to copy construct from

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

  Overload 2
  Constructs an IEnvironment object with all existing process environment variables

      public:
      IEnvironment(const bool copyCurrentEnv)

  This version will optionally create the environment object and initialize it to hold all of the process' current environmental variables. This is often very convenient since you will want to pass along all of your own environment to your child processes.

  copyCurrentEnvironment
    indicates whether the object should initialize itself to represent the process' current environment

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

  Overload 3
  Constructs an empty IEnvironment object.

      public:
      IEnvironment()

  The default constructor creates an empty environment object, with no initial variables.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

### Assignment

Assign one environment object to another.

operator =
  Resets this object's contents to equal the passed object's.

      public:
      void operator =(const IEnvironment& toAssign)

  Deletes any existing contents and duplicates the variables of the source object being assigned.

  toAssign
    is the source object whose contents are to be replicated.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

### Data Access Methods

Access members of IEnvironment objects.

add
  Adds a new variable to the environment object.

      public:
      void add(const IText& keyText, const IText& valueText)

  add() will add a new variable to the environment object. The new variable is given the passed value. Values are not iterated in the order that they are added necessarily.

  keyText
    is the name of the variable to add
  valueText
    is the text value to give to this new variable

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

clear
  Clears all existing variables from the object.

      public:
      void clear()

  Clears out all of the existing variables from the environment object, leaving it as though it was just default constructed.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

getCount
  Returns the count of variables in the object.

      public:
      unsigned long getCount() const

  Gets the count of variables in the environment object.

Return
  The count of variables in the object.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

remove
  Removes a variable by name

      public:
      bool remove(const IText& keyText)

  Finds a variable by its key name (the name of the variable), and removes it from the environment object. The count of variables is bumped down to account for this removal. If the name is not found, then the return is false.

  If the node removed is the current internal iterator node, then the internal iterator is moved up to the next node so that it remains valid (unless the node removed was the last node in the list or the only node.)

  keyText
    is the name of the variable to remove.

Return
  true if the variable was found and removed, else false.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

update
  Update the value of a variable

      public:
      bool update(const IText& keyText, const IText& newValue)

  Finds a variable by its key name (the name of the variable) and updates its associated text value to the passed new text value. If the variable is not found, then the return is false.

  keyText
    is the name of the variable to update
  newValue
    is the new value text to assign to this variable.

Return
  true if the indicated variable was found and updated, else false.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

### Iterator Methods

Iterator through an environment object.

first
  Sets the internal iterator to the first variable and returns its name and value.

      public:
      bool first(IText& keyText, IText& valueText)

  Finds the first variable in the list and sets up the internal iterator on that first element. This is required before calling next() to continue iterating through the variables, or any time that you wish to restart the iteration back to the head of the list.

  keyText
    is filled with the name of the first variable
  keyValue
    is filled with the value of the first variable

Return
  true if there were any variables in the object to iterate. If false, then the parameters are not changed.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

next
  Moves the internal iterator to the next node and returns its name and value.

      public:
      bool next(IText& keyText, IText& valueText)

  After calling first() to find the first variable in the environment object, next() may be called to find subsequent variables. When there are no more variables available, next() will return false.

  keyText
    is filled with the name of the next variable
  valueText
    is filled with the value of the next variable

Return
  true if there was another variable to iterator. If false, then the passed parameters are not changed.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

### Search Methods

Find particular items in an environment object.

find
  Looks up a variable in the environment object and returns its value, either by an IText return value or by copying the value into a provided IText object. The latter is obviously more efficient if you already have a target text object, avoiding the need for the creation of a temporary for return.

  Overload 1
  Finds a variable in the environment object.

      public:
      IText find(const IText& keyText) const

  This version take a key name (the name of the variable to find), and returns its contents in a temporary IText object. If its not found, then the returned object just contains an empty string.

  keyText
    is the name of the variable to find

Return
  An IText string with the variable's value. It will be an empty string if the variable does not exist.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

  Overload 2
  Finds a variable in the environment object.

      public:
      bool find(const IText& keyText, IText& valueText) const

  This version takes a key (the variable to find) and copies the contents of that variable's value into a passed IText object.

  keyText
    is the name of the variable to find
  ValueText
    is filled with the value of the key, if it is found.

Return
  true if the indicated key is found, else false.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

### IEnvironment - Inherited Member Functions and Data

#### Inherited Public Functions

  - None

#### Inherited Public Data

  - None

#### Inherited Protected Functions

  - None

#### Inherited Protected Data

  - None