%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
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)
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,! }
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).
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, "".
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.
pos Index position within the %DynamicArray of the element you wish to remove.
Returns The value of the removed %DynamicArray element.
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.
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
parameters:
- values: array of values to add to the set
returns:
- oref referencing the modified set
throws:
- exception
Inherited Members
Inherited Methods
- %ClassIsLatestVersion()
- %ClassName()
- %Clear()
- %DispatchClassMethod()
- %DispatchGetModified()
- %DispatchSetModified()
- %DispatchSetMultidimProperty()
- %Extends()
- %FromJSON()
- %FromJSONFile()
- %FromObject()
- %FromObjectMulti()
- %FromObjectSwizzle()
- %FromOref()
- %GetDocumentCollection()
- %GetDocumentID()
- %GetDocumentVersion()
- %GetParameter()
- %GetSerial()
- %GetSwizzleObject()
- %GetTypeOf()
- %IsA()
- %New()
- %OnClose()
- %OriginalNamespace()
- %PackageName()
- %SetDocumentMetadata()
- %SetModified()
- %SetSerial()
- %Size()
- %ToJSON()
- _isLabeled()
- addList()
- apply()
- clear()
- contains()
- containsAll()
- get()
- getDocumentCollection()
- getDocumentId()
- getDocumentVersion()
- iterator()
- put()
- putAll()
- putAllIfAbsent()
- putIfAbsent()
- remove()
- removeAll()
- removeIf()
- rename()
- replace()
- replaceAll()
- size()
- toDao()
- toJson()
- toString()