Home > Class Reference > %SYS namespace > %Library.DynamicArray

%Library.DynamicArray

donotuse class %Library.DynamicArray extends %Library.DynamicAbstractObject

Dynamic Array type class.

Method Inventory

Methods

method %Get(key, default, type) as %RawString [ Language = objectscript ]
Given the index position of a value in an array, return the actual value that corresponds to the index. If the value is the JSON null value then an empty string "" is returned. By default an empty string "" is also returned if the value does not exist. You can differentiate between a null value or an unassigned value that returns a "" string or a real "" string value by using the %GetTypeOf()() method.

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.

type The 'type' argument is optional, and if missing then it is assumed contain the empty string.

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

""          - %Get(key) without conversions
"string"       - Convert to text string
"string>base64"  - Convert to text string then encode into base64
"string<base64"  - Convert to text string then decode from base64
"stream"      - Place string conversion into %Stream
"stream>base64" - String encoded into base64 into %Stream
"stream<base64" - String decoded from base64 into %Stream
"json"        - Convert to JSON representation

Returns The value of the array data element as selected by the index value of the key argument.

If the 'type' argument is the 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 an ObjectScript string value. The JSON null value is converted to the empty string; the values dervied from JSON false, JSON true and a JSON format number will keep their JSON textual representation; an ObjectScript numeric value will use its ObjectScript canonical numeric representation (this includes the IEEE floating-point values for $DOUBLE("nan") and $DOUBLE("inf")); JSON array and JSON object values (represented by %DynamicArray and %DynamicObject oref values) and any other ObjectScript oref values are given their default ObjectScript conversion to string representation (e.g., "99@%Library.DynamicArray").

If the 'type' argument is "string>base64" then the value is first converted using the string type and then that result is encoded using Base64 encoding. The characters of the string value must be values between $CHAR(0) and $CHAR(255) because only those character values can be converted using Base64 encoding. If the string contains a character value greater-than %CHAR(255) then a <WIDE CHAR> error is signaled.

If the 'type' argument is "string<base64" then the string value of the element must contain a Base64 encoded string and the string characters are decoded into binary bytes. If a character not supported by the Base64 encoding is encountered then an <ILLEGAL VALUE> error is signaled. The white-space characters supported by the Base64 encoding may appear in the string and those characters will be ignored. Decoding stops when either the "=" termination character is encountered or the end of the string is encountered.

If the 'type' argument is "stream" then the value of the array element is converted to a string value and then that string value is loaded into a newly created %Stream.DynamicCharacter object or a newly created %Stream.DynamicBinary object. The oref of the newly created %Stream becomes the return value of %Get(...). Unlike ObjectScript string values, converting a large array element into a %Stream.DynamicCharacter object or a %Stream.DynamicBinary object will never signal the <MAXSTRING> error (although it may signal <STORE> if the memory capacity of the process is exceeded.) The "stream" 'type' will convert array elements using the same conventions and conversions as the "string" 'type' value.

If the 'type' argument is "stream>base64" then the value of the array element is first converted to a string value. Then that string value is encoded using Base64 conventions and loaded into a newly created %Stream.DynamicBinary object whose oref will become the return value of %Get(...). Unlike ObjectScript string values, converting a large array element into a %Stream.DynamicBinary object will never signal the <MAXSTRING> error (although it may signal <STORE> if the memory capacity of the process is exceeded.) The "stream>base64" 'type' will convert array elements using the same conventions, conversions, restrictions and errors as the "string>base64" 'type' value.

If the 'type' argument is "stream<base64" then the value of the array element is first converted to a string value. Then that string value is decoded using Base64 conventions and loaded into a newly created %Stream.DynamicBinary object whose oref will become the return value of %Get(...). Unlike ObjectScript string values, converting a large array element into a %Stream.DynamicBinary object will never signal the <MAXSTRING> error (although it may signal <STORE> if the memory capacity of the process is exceeded.) The "stream<base64" 'type' will convert array elements using the same conventions, conversions, restrictions and errors as the "string<base64" 'type' value.

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

There is a possible workaround for the case where dao.%Get(index,,"json") signals a not supported error when the dao element is an ObjectScript oref value. You can modify the class of that object to be "JSON enabled" by inheriting the %JSON.Adapter class. You will then be able to call the %JSONExportToString()(...) method to convert that class object to JSON text that can be imported back into an IRIS system.

  Set Result = dao.%Get(index,,"json")
  ;; could be replaced by
  Set Status=dao.%Get(index).%JSONExportToString(.Result)
  
method %GetIterator() as %Iterator.Array [ Language = objectscript ]
Inherited description:

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 %IsDefined(key) as %Boolean [ Language = objectscript ]
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).

method %Pop() as %RawString [ Language = objectscript ]
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 [ Language = objectscript ]

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 its value must be one of the following string values:

""          - %Push(value) without conversions
"null"        - "" becomes null; else push with no conversion
"boolean"      - 0/nonzero becomes JSON false/true
"number"      - Convert to numeric value
"string"       - Convert to text string
"string>base64"  - Convert to text string then encode into base64
"string<base64"  - Convert to text string then decode from base64
"stream"      - %Stream contents converted to text string
"stream>base64" - %Stream contents are encoded into base64 string
"stream<base64" - %Stream is decoded from base64 into byte string

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

If the 'type' argument is the empty string then ObjectScript 'value' argument is pushed onto the array without conversion.

If the 'type' argument is "null" and the 'value' argument contains the empty string then the JSON value null is pushed onto the array; all other ObjectScript values are pushed without conversion.

If the 'type' argument is "boolean" then the 'value' argument is first converted to a number. If that value is zero then the JSON value false is pushed; otherwise the JSON value true is pushed.

If the 'type' argument is "number" then the 'value' argument is converted to an ObjectScript numeric representation before being pushed.

If the 'type' argument is "string" then the 'value' argument is converted to string representation before being pushed.

If the 'type' argument is "string>base64" then the 'value' argument is converted to string representation and then the Base64 encoding of that string is pushed. The characters of the string value must be values between $CHAR(0) and $CHAR(255) because only those character values can be converted using Base64 encoding. If the string contains a character value greater-than %CHAR(255) then a <WIDE CHAR$gt; error is signaled.

If the 'type' argument is "string<base64" then the 'value' argument is converted to string representation and then the Base64 decoding of that string is pushed. If a character not supported by the Base64 encoding is encountered then an <ILLEGAL VALUE> error is signaled. The white-space characters supported by the Base64 encoding may appear in the string and those characters will be ignored. Decoding stops when either the "=" termination character is encountered or the end of the string is encountered.

If the 'type' argument is "stream" then the 'value' argument must contain a reference to an object which is a subclass of the %Stream.Object class. The entire contents of the %Stream are pushed onto the array as a string value.

If the 'type' argument is "stream>base64" then the 'value' argument must contain a reference to an object which is a subclass of the %Stream.Object class. The entire contents of the %Stream must consist of binary characters and the Base64 encoding of those characters are pushed onto the array as a string value. The characters in the %Stream must be values between $CHAR(0) and $CHAR(255) because only those character values can be converted using Base64 encoding. If the %Stream contains a character value greater-than %CHAR(255) then a <WIDE CHAR$gt; error is signaled.

If the 'type' argument is "stream<base64" then the 'value' argument must contain a reference to an object which is a subclass of the %Stream.Object class. The contents of that %Stream are decoded using Base64 conventions and the result is pushed onto the array as a string value. If a character not supported by the Base64 encoding is encountered in the %Stream then an <ILLEGAL VALUE> error is signaled. The white-space characters supported by the Base64 encoding may appear in the string and those characters will be ignored. Decoding stops when either the "=" termination character is encountered or the end of the string is encountered.

method %Remove(pos) as %DynamicAbstractObject [ Language = objectscript ]
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 [ Language = objectscript ]
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"        - "" becomes null; else assign with no conversion
"boolean"      - 0/nonzero becomes JSON false/true
"number"      - Convert to numeric value
"string"       - Convert to text string
"string>base64"  - Convert to text string then encode into base64
"string<base64"  - Convert to text string then decode from base64
"stream"      - %Stream contents converted to text string
"stream>base64" - %Stream contents are encoded into base64 string
"stream<base64" - %Stream is decoded from base64 into byte string

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

If the 'type' argument is the empty string then ObjectScript 'value' argument is stored in the array without conversion.

If the 'type' argument is "null" and the 'value' argument contains the empty string then the JSON value null is stored in the array element; all other ObjectScript values are stored without conversion.

If the 'type' argument is "boolean" then the 'value' argument is first converted to a number. If that value is zero then the JSON value false is stored; otherwise the JSON value true is stored.

If the 'type' argument is "number" then the 'value' argument is converted to an ObjectScript numeric representation before being stored.

If the 'type' argument is "string" then the 'value' argument is converted to string representation before being stored.

If the 'type' argument is "string>base64" then the 'value' argument is converted to string representation and then the Base64 encoding of that string is stored. The characters of the string value must be values between $CHAR(0) and $CHAR(255) because only those character values can be converted using Base64 encoding. If the string contains a character value greater-than %CHAR(255) then a <WIDE CHAR> error is signaled.

If the 'type' argument is "string<base64" then the 'value' argument is converted to string representation and then the Base64 decoding of that string is stored. If a character not supported by the Base64 encoding is encountered then an <ILLEGAL VALUE> error is signaled. The white-space characters supported by the Base64 encoding may appear in the string and those characters will be ignored. Decoding stops when either the "=" termination character is encountered or the end of the string is encountered.

If the 'type' argument is "stream" then the 'value' argument must contain a reference to an object which is a subclass of the %Stream.Object class. The entire contents of the %Stream are stored in the array element as a string value.

If the 'type' argument is "stream>base64" then the 'value' argument must contain a reference to an object which is a subclass of the %Stream.Object class. The entire contents of the %Stream must consist of binary characters and the Base64 encoding of those characters are stored in the array element as a string value. The characters in the %Stream must be values between $CHAR(0) and $CHAR(255) because only those character values can be converted using Base64 encoding. If the %Stream contains a character value greater-than %CHAR(255) then a <WIDE CHAR> error is signaled.

If the 'type' argument is "stream<base64" then the 'value' argument must contain a reference to an object which is a subclass of the %Stream.Object class. The contents of that %Stream are decoded using Base64 conventions and the result is stored in the array element as a string value. If a character not supported by the Base64 encoding is encountered in the %Stream then an <ILLEGAL VALUE> error is signaled. The white-space characters supported by the Base64 encoding may appear in the string and those characters will be ignored. Decoding stops when either the "=" termination character is encountered or the end of the string is encountered.