### IArgumentDictionary

  IArgumentDictionary is a general-purpose class for parsing text arguments on a command line and creating an ordered collection of key/value pairs. It parses arguments from an ITest object, a single string, or UNIX-style argc/argv parameters.

  A leading hyphen character identifies keywords. Anything without a leading hyphen is a value argument. A keyword picks up the following argument if it is not another keyword. This example shows how IArgumentDictionary parses the command line input to create the key/value pairs.

      Command-line input:

        -parm -n sample1 Sue Tom -ccc 84 85

  This table lists the options defined for the example:

         Key     Value     Description
         ---     -----     -----------
         -parm             The value associated with -parm is an empty IText, not NIL.
         -n      sample1   The -n argument picks up the following argument.
         1       Sue       There is no associated key so "1" is assigned.
         2       Tom       There is no associated key so "2" is assigned.
         -ccc    84        The -ccc argument picks up the value "84".
         3       85        There is no associated key so "3" is assigned.

  The command line input arguments should be parsed and handled in the setup member function.

### IArgumentDictionary - Member Functions and Data by Group

### Constructors & Destructor

Class constructors and destructors.

~IArgumentDictionary
  Destructor

      public:
      virtual ~IArgumentDictionary()

  IArgumentDictionary destructor function.

Supported Platforms

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

IArgumentDictionary
  IArgumentDictionary provides several constructors with a variety of signatures. Each constructor calls a corresponding importTextArguments functions. All constructors accept an optional parameter that specifies the options to be treated as naked options. (Naked options are input options never take values in a key/value pair.)

  Overload 1
  Constructor that uses the input values in theTest parameter as inputs

      public:
      IArgumentDictionary( ITest& theTest,
                           const IString& nakedOptions = IArgumentDictionary::kEmptyText )

  This constructor takes a constant reference to a ITest object and uses the inputs in theTest as arguments.

  This unique constructor uses the outputTextStream() of the ITest object for its own error message output. When this constructor is used within an ITest, a failure to parse a number (which typically causes the test to fail) produces an error message in the diagnostic output of the ITest. If a different constructor is used, the error message appears but is lost thereafter. It can then be difficult to determine what caused the test to fail.

  theTest
    Test object
  nakedOptions
    The options that never take values

Supported Platforms

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

  Overload 2
  Constructor that takes input string as inputs

      public:
      IArgumentDictionary( const IString& argumentString,
                           const IString& nakedOptions = IArgumentDictionary::kEmptyText )

  Constructor that takes an argument input string as inputs to the constructor.

  argumentString
    The argument string
  nakedOptions
    The options that never take values

Supported Platforms

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

  Overload 3
  Copy constructor

      public:
      IArgumentDictionary(const IArgumentDictionary& source)

  source
    The IArgumentDictionary object to be copied

Supported Platforms

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

  Overload 4
  Constructor with standard UNIX style argc and argv arguments as inputs

      public:
      IArgumentDictionary( const int argc,
                           const char * const* argv,
                           const IString& nakedOptions = IArgumentDictionary::kEmptyText )

  Constructor that takes standard UNIX style argc and argv arguments as inputs.

  argc
    The standard argc argument as passed in from the command line
  argv
    The standard argv argument as passed in from the command line
  nakedOptions
    The options that never take values

Supported Platforms

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

  Overload 5
  Default constructor

      public:
      IArgumentDictionary()

Supported Platforms

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

### Assignment

Standard assignment operators.

operator =

      public:
      IArgumentDictionary&
        operator =( const IArgumentDictionary& rhs )

  Standard assignment operator for IArgumentDictionary class.

  rhs
    The IArgumentDictionary object used to do assignment

Supported Platforms

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

### General Lookup

Member functions used to do general lookup of IArgumentDictionary values.

countOfArguments
  Returns the number of key/value pairs in the dictionary

      public:
      unsigned long countOfArguments() const

  The function countofArugments returns the number of key/value pairs that are currently stored in the dictionary.

Return
  the number of key/value pairs stored in the dictionary.

Supported Platforms

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

findSimilarKey
  Looks for a key similar to keyToMatch

      public:
      bool
        findSimilarKey( const IString& keyToMatch,
                        IString& newKey ) const

  This function looks for a key similar to value passed in the argument keyToMatch. If a similar key is found, it is returned in the argument newKey.

  Note: key is considered to match if it is of equal length or longer than the match key, and if all characters in the match key are equal (case insensitive) to those in the key. Call lookupSimilarKeys(true) to always have the dictionary look for similar keys.

  keyToMatch
    Name of the key to match
  newKey
    Name of the key similar to keyToMatch

Return
  false if no similar key is found; otherwise true.

Supported Platforms

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

nthValue
  Retrieve the index-th option-less value

      public:
      bool nthValue(const short index, IString& value)

  This function attempts to retrieve the index-th option-less value. It returns false if no such value exists.

  index
    The given index
  value
    IString for retrieved value

Return
  false if no such value exists; otherwise true.

Supported Platforms

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

removeOnLookup
  Removes key/value pairs from the dictionary as they are looked up

      public:
      void removeOnLookup(bool)

  Causes key/value pairs to be removed from the dictionary as they are looked up.

  If removeOnLookup is called with argument true, then keys and values will be removed from the dictionary (keys will also be deleted) as they are looked up. This is useful if you want to make sure that all arguments are parsed by:

  - calling removeOnLookup(true) to turn on automatic key/value pair removal
  - deleting each argument as you retrieve it
  - checking count() == 0 to make sure there are no leftover arguments

  bool
    true to turn on automatic key/value pair removal; false to turn it off

Supported Platforms

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

textAt
  Value lookup for a given key

      public:
      bool textAt(const IString& key, IString& value)

  Returns the value associated with the given key.

  If the value was numeric, textAt returns it as a string. If no value was given, an empty IString object is returned.

  key
    The given key for lookup
  value
    The retrieved value, if one is found

Return
  bool false if no such key exists; otherwise true

Supported Platforms

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

### Importing and Exporting

Member functions used to import and export information to and from the IArugmentDictionary.

exportTextArguments
  Exports the arguments in this dictionary

      public:
      void exportTextArguments(IString& argumentString)

  This function exports the arguments in the given dictionary as a string of space-delimited keys and values.

  argumentString
    The string of keys and values

Supported Platforms

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

importTextArguments
  Copies input text arguments from the passed-in parameters.

  It places the key/value pairs from the input arguments in the dictionary. Arguments are added to any existing dictionary entries. Options are recognized by a leading '-' character. IArgumentDictionary tries to recognize negative numbers so you can not have input options that could be confused with negative numbers. For example, "-2ab" is a valid option; "-123" is not.

  Overload 1
  Copies the white-spaced delimited string of keys and values from the inputs

      public:
      void importTextArguments(const IString& argumentString)

  Copies the white-spaced delimited string of keys and values from the input argument string.

  argumentString
    Name of a white-space delimited string of keys and values

Supported Platforms

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

  Overload 2
  Copies the UNIX style argc and argv key/value input text parameters

      public:
      void
        importTextArguments( const int argc,
                             const char * const* argv )

  Copies the UNIX style argc and argv key/value input text parameters.

  argc
    UNIX-style argument count
  argv
    UNIX-style argument vector

Supported Platforms

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

  Overload 3
  Copies text arguments from the ITest object parameter

      public:
      void importTextArguments(ITest& theTest)

  Copies text arguments from the ITest object parameter.

  theTest
    The ITest object where the text arguments should be copied from

Supported Platforms

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

lookupSimilarKeys
  Toggles on or off the use of the findSimilarKey lookups

      public:
      void lookupSimilarKeys(bool)

  This function toggles on or off the use of the findSimilarKey lookups. If lookupSimilarKeys(true) is called, the dictionary will henceforth call findSimilarKey for all lookups. It will also match similar keys during importTextArguments calls when checking to see if keys are naked keys.

  bool
    true/false

Supported Platforms

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

specifyNakedOptions
  Specifies which options are "naked"

      public:
      void specifyNakedOptions(const IString& nakedOptions)

  Specifies that the given options never take values in a key/value pair.

  Call these methods *before* calling ImportTextArguments to change the way input arguments are handled.

  nakedOptions
    IString containing a space delineated list of the options that never takes values (e.g., ("-p -i -q)")@@@@@

Supported Platforms

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

### Number lookup

Member functions used to lookup values in the IArgumentDictionary based on a given key or index.

nthNumber
  This function returns the index-th option-less value parsed as a number in the parameter value. It behaves like the range-checked numberAt methods. The number must fall in the range minAllowed and maxAllowed.

  Overload 1
  Returns the index-th option-less value parsed as a number in the parameter value

      public:
      bool
        nthNumber( const short index,
                   long& value,
                   long minAllowed = LONG_MIN,
                   long maxAllowed = LONG_MAX )

  index
    Index number of the value that is being looked up
  value
    Retrieved value (long)
  minAllowed
    Minimum value allowed (long)
  maxAllowed
    Maximum value allowed (long)

Return
  true if the argument exists, it parses perfectly, and it is within the given range. false if the number parses badly, is out of range, or the argument does not exist, leaving value unchanged.

Supported Platforms

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

  Overload 2
  Returns the index-th option-less value parsed as a number in the parameter value

      public:
      bool
        nthNumber( const short index,
                   double& value,
                   double minAllowed = - DBL_MAX,
                   double maxAllowed = DBL_MAX )

  index
    Index number of the value that is being looked up
  value
    Retrieved value (double)
  minAllowed
    Minimum value allowed (double)
  maxAllowed
    Maximum value allowed (double)

Return
  true if the argument exists, it parses perfectly, and it is within the given range. false if the number parses badly, is out of range, or the argument does not exist, leaving value unchanged.

Supported Platforms

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

numberAt
  Looks up a number argument corresponding to the given key. The number must fall in the range minAllowed <= x <= maxAllowed. If the number parse badly, the argument does not exist, or is out of range, false is returned and leaves "value" unchanged.

  Overload 1

      public:
      bool
        numberAt( const IString& key,
                  double& value,
                  double minAllowed = - DBL_MAX,
                  double maxAllowed = DBL_MAX )

  key
    Key of the value that is being looked up
  value
    Retrieved value (double)
  minAllowed
    Minimum value allowed (double)
  maxAllowed
    Maximum value allowed (double)

Return
  true if the argument exists, it parses perfectly and is within the given range, inclusively. false if the number parses badly, is out of range, or the argument does not exist, leaving value unchanged.

Supported Platforms

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

  Overload 2

      public:
      bool
        numberAt( const IString& key,
                  long& value,
                  long minAllowed = LONG_MIN,
                  long maxAllowed = LONG_MAX )

  key
    Key of the number
  value
    Retrieved value (long)
  minAllowed
    Minimum value allowed (long)
  maxAllowed
    Maximum value allowed (long)

Return
  true if the argument exists, it parses perfectly and is within the given range, inclusively. false if the number parses badly, is out of range, or the argument does not exist, leaving value unchanged.

Supported Platforms

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

### Public Constants

Public constants

kEmptyText
  Used to represent empty text fields in the IArgumentDictionary class.

  Overload 1
  Class member for empty text fields.

      public:
      static const IString & _Import kEmptyText

Supported Platforms

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

  Overload 2
  Class member for empty text fields.

      public:
      static const IString& kEmptyText

Supported Platforms

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

AIX Considerations
  This definition used for AIX Platforms only.

### IArgumentDictionary - Inherited Member Functions and Data

#### Inherited Public Functions

  - None

#### Inherited Public Data

  - None

#### Inherited Protected Functions

  - None

#### Inherited Protected Data

  - None