Class Reference
IRIS for UNIX 2019.1
InterSystems: The power behind what matters   
Documentation  Search
  [%SYS] >  [%Library] >  [DynamicArray]
Private  Storage   

class %Library.DynamicArray extends %Library.DynamicAbstractObject

Dynamic Array type class.

This class uses features not available on VMS and will generate the <UNIMPLEMENTED> signal on VMS platforms.

Inventory

Parameters Properties Methods Queries Indices ForeignKeys Triggers
11


Summary

Methods
%DispatchGetProperty %DispatchSetProperty %Get %GetIterator
%GetTypeCodeOf %IsDefined %Pop %Push
%Remove %Set


Methods

• method %DispatchGetProperty(propertyName As %String)
Property dispatch method to catch references to virtual properties.
This should not be called directly.
• method %DispatchSetProperty(propertyName As %String(MAXLEN=""), value As %String)
Property dispatch method to catch references to virtual properties.
This should not be called directly.
• method %Get(key, default, type) as %RawString
Given the index position of a value in an array, return the actual value that corresponds to the index. If the value does not exist, an empty string "" is returned. You can differentiate between an unassigned value that returns a "" string and a real "" string using %GetTypeOf().

key The 'key' argument contains the index value of the array element that you wish to retrieve.

default The 'default' argument is optional and if missing then it is assumed to contain the empty string. The 'default' value is returned when the selected array element is undefined; if the 'default' argument is missing then the empty string is returned if the selected array element is undefined.

type The 'type' argument is optional and if missing then it is assumed contain the empty string. Permissible value of 'type' are the values of "", "string", "stream" and "json".

If the 'type' argument is empty string then the selected array element is converted to the corresponding ObjectScript value.

If the 'type' argument is the text value "string" then the value of the array element is converted to a string value. The JSON 'null' value is converted to the empty string; the values dervied from JSON 'false', JSON 'true' and JSON number will keep their JSON textual representation; an ObjectScript numeric value will use its ObjectScript canonical numeric representation; JSON array and JSON object values (represented by %DynamicArray and %DynamicObject oref values) are not currently supported but you can use the %ToJSON() method call to convert %DynamicArray and %DynamicObject objects to JSON text; ObjectScript oref values are not currently supported but if an oref is "JSON enabled" by inheriting the %JSON.Adapter class then you can call the %JSONExportToString(...) method to convert a class object to JSON text.

If the 'type' argument is the string value "stream" then the value of the array element is converted to a string value and that string value is loaded into a %Stream.DynamicCharacter object or a %Stream.DynamicBinary object. Unlike ObjectScript string variables, converting a large array element into a %Stream.DynamicCharacter and %Stream.DynamicCharacter objects will never signal the <MAXSTRING> error. The "stream" 'type' value converts non-string array elements using the same conventions as the "string" 'type' value. The "stream" 'type' does not currently support elements which are nested JSON array or nested JSON object values although you can use the %ToJSON(stream) method call to transfer JSON text of such a value into some other class object in the %Stream package; ObjectScript oref values are not supported but if an oref is "JSON enabled" by inheriting the %JSON.Adapter class then you can call the %JSONExportToStream(...) method to transmit the JSON text of a class object into some other class in the %Stream package.

If the 'type' argument is the string value "json" then the value of the selected array element is converted to the corresponding JSON value. Note that converting the following selected array element values to JSON will signal the <ILLEGAL VALUE> error: the $DOUBLE values for a NaN and an Infinity and any oref value that does not refer to an object of the %DynamicAbstractObject class.

Returns The value of the array data as selected by index position key. If the value does not exist, an empty string "" is returned when there is no default argument specified. Also, when the JSON null value is converted to an ObjectScript value then the returned value will be the empty string "". You can differentiate between an unassigned value or the JSON null value, which both return a "" string, and a real "" string using %GetTypeOf().

• method %GetIterator() as %Iterator.Array

Perform an iteration of all the values in a %DynamicAbstractObject subclass.

In the example below, we will output all values contained in a %DynamicArray or a %DynamicObject.

	   set iter = AbstractObject.%GetIterator()
	   while iter.%GetNext(.key , .value ) {
	      write "key = "_key_" , value = "_value,!
	   }
• method %GetTypeCodeOf(key) as %Integer
INTERNAL ONLY!

The %GetTypeCodeOf(key) method is for internal use only. The actions taken by this method may change in the future as additional capabilities are added to %DynamicAbstractObject class objects.

• method %IsDefined(key) as %Boolean
Tests if a key is defined within an array.

key The index position of the value you wish to test, indexes begin at position 0.

Returns A boolean value to show if a value is defined (1) or not (0).

• private method %OnNew(initvalue As %RawString) as %Status
• method %Pop() as %RawString
Returns the value of the last member of the array. The value is then removed from the array. Nothing is removed if the array is empty.

Note: Any of the 4 situations causes %Pop() to return the empty string, "":

  • (1) Popping from an empty array
  • (2) Last member is the empty string
  • (3) Last member is the value null
  • (4) Last member is unassigned

If you want to differentiate between these 4 cases then you must test the array and its last element before calling the %Pop method.

Returns The value of the last member of the array.
If the array is empty, the method returns the empty string, "".

• method %Push(value, type) as %DynamicAbstractObject

Given a new value, append it to the end of the current array, increasing the length of the array.

value The new value to push.

type OPTIONAL, the 'type' of the value to push.

If the 'type' argument is present then it must be one of the following string values:

"" - %Set(key,value) without conversions
"null" - convert "" value to JSON null; else assign with no conversion
"boolean" - Either 0 or nonzero integer converted to JSON false/true
"number" - Convert to numeric value
"string" - Convert to text string
"stream" - Convert contents of %Stream to text string

Returns An OREF referencing the current modified array, allowing calls to %Push() to be nested.

• method %Remove(pos) as %DynamicAbstractObject
Remove the element at the specified index position from the %DynamicArray. If the value of the %DynamicArray element is an embedded %DynamicArray or an embedded %DynamicObject, delete all subordinate nodes as well. All %DynamicArray elements following the removed element will have their subscript position decremented by 1.

pos Index position within the %DynamicArray of the element you wish to remove.

Returns The value of the removed %DynamicArray element.

• method %Set(key, value, type) as %DynamicAbstractObject
Create a new value or update an existing value.

key The index position of the value you wish to create, indexes begin at position 0.

value The new value with which to update the previous value or create a new value.

type OPTIONAL, the type of the value being assigned.

If the 'type' argument is present then its value must be one of the following string values:

"" - %Set(key,value) without conversions
"null" - convert "" value to JSON null; else assign with no conversion
"boolean" - Either 0 or nonzero integer converted to JSON false/true
"number" - Convert to numeric value
"string" - Convert to text string
"stream" - Convert contents of %Stream to text string

Returns An OREF to the current modified array, allowing calls to %Set() to be nested.



Copyright (c) 2019 by InterSystems Corporation. Cambridge, Massachusetts, U.S.A. All rights reserved. Confidential property of InterSystems Corporation.