GetNextKey

Description:	Allows a linear search through a dictionary in place. i.e. without copying the contents to an array.
Returns:	Varies
Usage:	Script Only.
Function Groups:	Dictionary
Related to:	Dictionary | MetaData | DictionaryCopy | DictionaryRemove | ListKeys
Format:	GetNextKey(Dictionary[, Key, Order, KeyFound ] )
Parameters:

Dictionary

Required. Any dictionary you wish to search.

Key

The key to start from. If this is invalid, or if the key is not found in the dictionary, then the first key in the given order will be returned.

Order

An optional numeric expression. Defines the search according to the following table of values. Defaults to 0 if missing. Setting this parameter to Invalid will result in the function returning Invalid. Order Meaning 0 Forward alphabetic search 1 Forward ordinal search. Returns the next newer key. Begins at the oldest key if the parameter Key is invalid. 2 Backward alphabetic search 3 Backward ordinal search. Returns the next older key. Begins at the newest key if the parameter Key is invalid.

Key Found

Upon completion of the function, this value will receive the key of the record found, which matches with the value of that record returned by the function. If there are no further keys in the given order, this value will be set to INVALID.

Comments:

The return value is the value associated with the key found, or INVALID if no key was found. Only the first parameter is required.

Example:

    result_str = "";
    myDict = Dictionary();
    myDict["key4"] = "contents4";
    myDict["key1"] = "contents1";
    myDict["key3"] = "contents3";
    myDict["key2"] = "contents2";
    curVal = GetNextKey(myDict, Invalid, 0, curKey);
    WhileLoop(Valid(curKey),
      result_str = Concat(result_str, " """, curVal, """");
      curVal = GetNextKey(myDict, curKey, 0, curKey);
    );

result_str will be: "contents1" "contents2" "contents3" "contents4"