Skip to main content

%Library.DynamicArray

dynamic class %Library.DynamicArray extends %Library.DynamicAbstractObject [ Final ]

For information on this class, see Using Dynamic Entities.

Dynamic Array type class.

Method Inventory

Methods

method %DispatchMethod(methodName As %String(MAXLEN=""), args...)
Inherited description: Is used to implement an unknown method call. It is also used to resolve an unknown multidimensional property reference (to get the value of a property) because that syntax is identical to a method call.
method %Get(key As %Integer, default As %Any, type As %String) as %Any
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. Note that the key of a %DynamicArray is evaluated as an ObjectScript integer expression so that dynarray.%Get("abc") gives the same value as dynarray.%Get(0).

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 to 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.Adaptor 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

Generates a %Iterator.Array object which contains a %GetNext(.key,.value,.type) method which will iterate over all the defined elements in the %DynamicArray object.

Warning: Adding or removing elements to the %DynamicArray during an interation can cause further calls on the %GetNext(.key,.value,.type) method to have undefined behavior. This happens because adding or removing an array element causes the following elements to have their index numbers modified. The modification of index numbers can cause elements to be skipped by the %GetNext iteration method or can cause elements to be visited more than once by the %GetNext iteration method.

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

     set iter = DynArray.%GetIterator()
     while iter.%GetNext(.key, .value, .type ) {
        write "key = "_key_", value = "_value_", type = "_type,!
     }
  
See the descriptions of the %GetNext() method in the %Iterator.Array for more details.
method %IsDefined(key As %Integer) 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. Note that the key of a %DynamicArray is evaluated as an ObjectScript integer expression so that dynarray.%IsDefined("abc") gives the same value as dynarray.%IsDefined(0).

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

method %Pop() as %Library.Any
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 As %Library.Any, type As %String) 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 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> 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> 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 %Integer) as %DynamicAbstractObject
Remove the element at the specified index position from the %DynamicArray. All %DynamicArray elements following the removed element will have their subscript position decremented by 1. This may cause problems with any %Iterator.Array object iterating over this %DynamicArray.

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

Returns The value of the removed %DynamicArray element.

method %Set(key As %Integer, value As %Library.Any, type As %String) 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. Note that the key of a %DynamicArray is evaluated as an ObjectScript integer expression so that dynarray.%Set("abc",value,type) provides the same operation as dynarray.%Set(0,value,type).

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.

method add(value As %Library.Any) as %Library.DynamicArray

add value to the set.

It is left to the implementation to decide whether duplicates are allowed (multiset) or not (proper set).

parameters:

  • value: value to add to the set

returns:

  • oref referencing the modified set

throws:

  • exception

method addAll(value As %Library.AbstractSet) as %Library.DynamicArray
add() all values[n] where 0≤n≤ size(values)

parameters:

  • values: array of values to add to the set

returns:

  • oref referencing the modified set

throws:

  • exception

Inherited Members

Inherited Methods

FeedbackOpens in a new tab