GetNextKey

(Engine-Level Function)

Description:	Allows a linear search through a dictionary.
Returns:	Varies according to the stored values. (Returns values, not keys.)
Usage:	Script Only.
Function Groups:	Dictionary
Related to:	Dictionary | MetaData | DictionaryCopy | DictionaryRemove | ListKeys
Format:	GetNextKey(Dictionary[, StartKey, Order, KeyName ] )
Parameters:

Dictionary

Required. Any dictionary you wish to search.

StartKey

Optional. The key, from which to start. 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 value associated with 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 value associated with the next older key. Begins at the newest key if the parameter Key is invalid.

KeyName

This parameter 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:

In spite of this function's name, the return value is not the key but the value associated with the key found, or INVALID if no key was found. The matching key can be obtained from the fourth parameter.

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"