%Iterator.Object

Adding an element to the %DynamicObject object can cause further calls on the %GetNext(.key,.value,.type) method to have undefined behavior. It is undefined whether the %GetNext iteration method will visit or skip the added element.

The first argument is an output argument key which contains the key name string for the element that is returned.

The second argument is an output argument value which contains the value for the returned element converted to ObjectScript. If the optional third argument is not pressent then a <MAXNUMBER> error signal may occur if the element value is a JSON number that is too large to be converted to an ObjectScript computational canonical number. If the optional third argument is not present then a <MAXSTRING> error signal may occur if the element value is a JSON string that exceeds the string length limit for ObjectScript string values. If the optional third argument is present then these conversion errors will be avoided.

The optional third output argument type, when it is present, will be modified to contain the %GetTypeOf(key) string representing the original type of the returned %DynamicObject element. When this third argument variable is present it changes some of the conversion rules for converting a %DynamicObject element into an ObjectScript value.

If the third parameter variable is present then an element which was originally a JSON format number will be returned as an ObjectScript string containing the JSON format number. If the element was originally an ObjectScript number then the returned value will be an ObjectScript computational canonical number.

If the element in the %DynamicObject was originally an ObjectScript oref then the type argument will contain "oref". If the element was originally a very long JSON string that could not be converted to an ObjectScript string then the value argument will contain the oref for a readonly ObjectScript %Stream.DynamicCharacter or %Stream.DynamicBinary object containing the JSON string characters but the type argument will still contain "string" and not "oref".

The type value allows you to deterimine whether a %Stream oref returned in the value argument was originally an ObjectScript oref or a long JSON string.

The type can also allow you to determine whether a value containing the ObjectScript empty string, "", was originally type "string" or "null" or whether a value containing 0 or 1 was originally type "number" or type "boolean".

To call this method, pass the key and value arguments, and optionally the type argument, by reference to receive their return values. To iterate over a %DynamicObject use the following pattern:

      while iterator.%GetNext(.key,.value,.type) {
          // key contains the element key name
          // and value contains the value
          // and type contains a %GetTypeOf string
      }