Class: TTextArgumentDictionary

Declaration: TextArgumentDictionary.h

Taxonomy Categories:

Member Functions:

Interface Category:

Developer Tool Programmer Interface.

Inherits From:

None.

Inherited By:

None.

Purpose:

Parses input arguments. It takes as input an ordered collection of TText objects (in some form or another). It parses these TTexts as arguments on a command line, forming key-value pairs.

Instantiation:

Allocate on the heap or the stack.

Deriving Classes:

You do not need to derive TTextArgumentDictionary. Use TTextArgumentDictionary directly.

Concurrency:

Not multithread safe.

Resource Use:

No special requirements.

Member Function: TTextArgumentDictionary::TTextArgumentDictionary

TTextArgumentDictionary ()
TTextArgumentDictionary (TTest & theTest, const TText & nakedOptions =TTextArgumentDictionary :: kEmptyText, const TText & multipleValueOptions =TTextArgumentDictionary :: kEmptyText)
TTextArgumentDictionary (const TSequenceOf < TText > & textArguments, const TText & nakedOptions =TTextArgumentDictionary :: kEmptyText, const TText & multipleValueOptions =TTextArgumentDictionary :: kEmptyText)
TTextArgumentDictionary (const TText & argumentString, const TText & nakedOptions =TTextArgumentDictionary :: kEmptyText, const TText & multipleValueOptions =TTextArgumentDictionary :: kEmptyText)
TTextArgumentDictionary (const TTextArgumentDictionary & source)

Interface Category:

Developer Tool Programmer Interface.

Purpose:

Default constructor.
Constructor that takes a constant reference to a TTest object. Uses inputs in TTest as arguments.
Constructor that takes a sequence of TText objects.
Constructor that takes an argument string.
Copy constructor.

Calling Context:

Called by the stream-in operators and directly.
Called by Test Framework and directly.
Called by Test Framework and directly.
Called by Test Framework and directly.
Called to copy an object.

Parameters:

Takes no parameters.
TTest & theTest -Test object.
const TText & nakedOptions =TTextArgumentDictionary :: kEmptyText -The options that never take values.
const TText & multipleValueOptions =TTextArgumentDictionary :: kEmptyText -The options that take multiple values.
const TSequenceOf < TText > & textArguments -The arguments stored as a sequence of TText.
const TText & nakedOptions =TTextArgumentDictionary :: kEmptyText -The options that never take values.
const TText & multipleValueOptions =TTextArgumentDictionary :: kEmptyText -The options that take multiple values.
const TText & argumentString -The argument string stored as TText.
const TText & nakedOptions =TTextArgumentDictionary :: kEmptyText -The options that never take values.
const TText & multipleValueOptions =TTextArgumentDictionary :: kEmptyText -The options that take multiple values.
const TTextArgumentDictionary & source -The object to be copied.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TTextArgumentDictionary::operator=

TTextArgumentDictionary & operator =(const TTextArgumentDictionary & rhs)

Interface Category:

Developer Tool Programmer Interface.

Purpose:

Assignment operator.

Calling Context:

Called when an object is assigned to another compatible object.

Parameters:

const TTextArgumentDictionary & rhs -The right-hand side object.

Return Value:

A non-const reference to the left-hand side object.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TTextArgumentDictionary::~TTextArgumentDictionary

virtual ~ TTextArgumentDictionary ()

Interface Category:

Developer Tool Programmer Interface.

Purpose:

Destructor.

Calling Context:

Called to destroy an object.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TTextArgumentDictionary::SpecifyNakedOptions

void SpecifyNakedOptions (const TText & nakedOptions)

Interface Category:

Developer Tool Programmer Interface.

Purpose:

Specifies that the given options never take values.

Calling Context:

Called by TTextArgumentDictionary constructors.

Parameters:

const TText & nakedOptions -The options that never take values.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TTextArgumentDictionary::SpecifyMultipleValueOptions

void SpecifyMultipleValueOptions (const TText & multipleValueOptions)

Interface Category:

Developer Tool Programmer Interface.

Purpose:

Specifies that the given options take multiple values.

Calling Context:

Called by TTextArgumentDictionary constructors.

Parameters:

const TText & multipleValueOptions -The options that take multiple values.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TTextArgumentDictionary::LookupSimilarKeys

void LookupSimilarKeys (bool)

Interface Category:

Developer Tool Programmer Interface.

Purpose:

If LookupSimilarKeys(true) is called, the dictionary henceforth calls FindSimilarKey for all lookups. It also matches similar keys during ImportTextArguments calls when checking to see if keys are naked or multiple value keys.

Calling Context:

Called by Test Framework and directly.

Parameters:

bool -A flag indicating whether FindSimilarKey should be called for lookups.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TTextArgumentDictionary::ImportTextArguments

void ImportTextArguments (TTest & theTest)
void ImportTextArguments (const TSequenceOf < TText > & textArguments)
void ImportTextArguments (const TText & argumentString)

Interface Category:

Developer Tool Programmer Interface.

Purpose:

Copies text arguments from the given TTest object.
Copies text arguments from the given sequence of text.
Copies text arguments from the given argument string.

Calling Context:

Called by TTextArgumentDictionary constructors and directly.
Called by TTextArgumentDictionary constructors and directly.
Called by TTextArgumentDictionary constructors and directly.

Parameters:

TTest & theTest -Test object.
const TSequenceOf < TText > & textArguments -The sequence of arguments stored as TText.
const TText & argumentString -The argument string given as TText.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TTextArgumentDictionary::ExportTextArguments

void ExportTextArguments (TText & argumentString)

Interface Category:

Developer Tool Programmer Interface.

Purpose:

Exports the arguments in this dictionary as a string of space-delimited keys and values.

Calling Context:

Called by Test Framework and directly.

Parameters:

TText & argumentString -The string where the arguments are copied.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TTextArgumentDictionary::CopyTextArguments

void CopyTextArguments (TSequenceOf < TText > & textArguments)

Interface Category:

Developer Tool Programmer Interface.

Purpose:

Exports the arguments in this dictionary as a sequence of TText keys and values.

Calling Context:

Called by Test Framework and directly.

Parameters:

TSequenceOf < TText > & textArguments -The sequence where the arguments are copied.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TTextArgumentDictionary::CountOfArguments

unsigned long CountOfArguments () const

Interface Category:

Developer Tool Programmer Interface.

Purpose:

Returns the number of key-value pairs in the dictionary.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

Returns the number of key-value pairs in the dictionary.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TTextArgumentDictionary::RemoveOnLookup

void RemoveOnLookup (bool)

Interface Category:

Developer Tool Programmer Interface.

Purpose:

If Remove on Lookup(true) is called, then the keys and values are removed from the dictionary as they are looked up.

Calling Context:

Called by Test Framework and directly.

Parameters:

bool -A flag indicating whether key-value pairs are to be removed as they are looked up.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

The caller owns the returned values from the lookup and must delete them if RemoveOnLookup is called with true.

Member Function: TTextArgumentDictionary::TextAt

TText * TextAt (const TText & key)

Interface Category:

Developer Tool Programmer Interface.

Purpose:

Retrieves the value associated with the given key.

Calling Context:

Called by Test Framework and directly.

Parameters:

const TText & key -The key used to look up the value.

Return Value:

If the value is numeric, TextAt returns it as a string. If no value is given, an empty TText object is returned. If the key is not present at all, then TextAt returns zero.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TTextArgumentDictionary::NthValue

TText * NthValue (const short index)

Interface Category:

Developer Tool Programmer Interface.

Purpose:

Returns the keyless value with the given index number.

Calling Context:

Called by Test Framework and directly.

Parameters:

const short index -The index used to look up the value.

Return Value:

Returns a pointer to the value. If no value is found for the given index, then NthValue returns zero.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TTextArgumentDictionary::MultipleValuesAt

bool MultipleValuesAt (const TText & key, TCollectionOf<TText> & toReceiveTTexts)

Interface Category:

Developer Tool Programmer Interface.

Purpose:

Returns a collection of values for keys that accept multiple values.

Calling Context:

Called by Test Framework and directly.

Parameters:

const TText & key -The key used to look up the values.
TCollectionOf<TText> & toReceiveTTexts -The collection where the values are copied.

Return Value:

Returns true if the key is found in the dictionary.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

The multiple values feature is incompatible with type-safe collections, and, as such, is not recommended for use with any long-term test code. Later versions of the Test Framework will include a new method of handling this kind of argument.

Member Function: TTextArgumentDictionary::FindSimilarKey

TText * FindSimilarKey (const TText & keyToMatch) const

Interface Category:

Developer Tool Programmer Interface.

Purpose:

Should be called to explicitly look for a key similar to the one given. A key is considered to match if it is of equal length or longer then the match key, and if all characters in the match key are equal (case insensitive) to those in the key.

Calling Context:

Called by Test Framework and directly.

Parameters:

const TText & keyToMatch -The key used for matching the similar key.

Return Value:

Returns the similar key if found. Returns zero if no similar key is found.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TTextArgumentDictionary::NumberAt

bool NumberAt (const TText & key, double & value, double minAllowed =-DBL_MAX, double maxAllowed =DBL_MAX)
bool NumberAt (const TText & key, long & value, long minAllowed =LONG_MIN, long maxAllowed =LONG_MAX)

Interface Category:

Developer Tool Programmer Interface.

Purpose:

Looks up a number corresponding to the given key. The value is returned as a double.
Looks up a number corresponding to the given key. The value is returned as a long.

Calling Context:

Called by Test Framework and directly.
Called by Test Framework and directly.

Parameters:

const TText & key -The key used for the lookup.
double & value -The value for the given key if found.
double minAllowed =-DBL_MAX -The minimum double value for the value of the key.
double maxAllowed =DBL_MAX -The maximum double value for the value of the key.
const TText & key -The key used for the lookup.
long & value -The value for the given key if found.
long minAllowed =LONG_MIN -The minimum long value for the value of the key.
long maxAllowed =LONG_MAX -The maximum long value for the value of the key.

Return Value:

Returns true if the value is found, it parses perfectly, and it is within the given range. If the argument does not exist, NumberAt returns false and leaves value unchanged.

Exceptions:

Throws TArgumentDictionaryLookupFailureException if the number parses badly or is out of range.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TTextArgumentDictionary::NthNumber

bool NthNumber (const short index, double & value, double minAllowed =-DBL_MAX, double maxAllowed =DBL_MAX)
bool NthNumber (const short index, long & value, long minAllowed =LONG_MIN, long maxAllowed =LONG_MAX)

Interface Category:

Developer Tool Programmer Interface.

Purpose:

Looks up a number corresponding to the given index. The value is returned as a double.
Looks up a number corresponding to the given index. The value is returned as a long.

Calling Context:

Called by Test Framework and directly.
Called by Test Framework and directly.

Parameters:

const short index -The index used for the lookup.
double & value -The value for the given index if found.
double minAllowed =-DBL_MAX -The minimum double value for the value at the index.
double maxAllowed =DBL_MAX -The maximum double value for the value at the index.
const short index -The index used for the lookup.
double & value -The value for the given index if found.
double minAllowed =-DBL_MAX -The minimum long value for the value at the index.
double maxAllowed =DBL_MAX -The maximum long value for the value at the index.

Return Value:

Returns true if the value is found, it parses perfectly, and it is within the given range. If the argument does not exist, NumberAt returns false and leaves value unchanged.

Exceptions:

Throws TArgumentDictionaryLookupFailureException if number parses badly or is out of range.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TTextArgumentDictionary::DeleteAll

void DeleteAll ()

Interface Category:

Developer Tool Programmer Interface.

Purpose:

Deletes all key-value pairs from the dictionary.

Calling Context:

Called by Test Framework and directly.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Click the icon to mail questions or corrections about this material to Taligent personnel.