Quick Reference for Dynamic Entity Methods

Given a JSON source, parse the source and return an object of datatype %DynamicAbstractObjectOpens in a new tab containing the parsed JSON. If an error occurs during parsing, an exception will be thrown. See “Converting Dynamic Entities to and from JSON” for details and examples.

parameters:

• str — The input can be from any one of the following sources:

  • string value containing the source.

  • stream object to read the source from.

  • file URI where the source can be read. The file must be encoded as UTF-8.

see also: %ToJSON(), Serializing Large Dynamic Entities to Streams

class reference: %DynamicAbstractObject.%FromJSON()Opens in a new tab

Given a valid object key or array index, returns the value. If the value does not exist, a null string "" is returned. See “Using %Set(), %Get(), and %Remove()” for details and examples.

parameters:

• key — the object key or array index of the value to be retrieved. An array index must be passed as a canonical integer value. Array indexes begin at position 0.

see also: %Set(), %Remove(), %Pop()

class reference: %DynamicObject.%Get()Opens in a new tab and %DynamicArray.%Get()Opens in a new tab

Returns a %Iterator object allowing iteration over all members of a dynamic entity. See “Iterating over a Dynamic Entity with %GetNext()” for details and examples.

see also: %GetNext()

class reference: %DynamicObject.%GetIterator()Opens in a new tab, %DynamicArray.%GetIterator()Opens in a new tab, %Iterator.ObjectOpens in a new tab, %Iterator.ArrayOpens in a new tab

This is a method of the %Iterator object returned by %GetIterator(). It advances the iterator and returns true if the iterator is positioned on a valid element, false if it is beyond the last element. The key and value arguments return values for a valid element at the current iterator position. See “Iterating over a Dynamic Entity with %GetNext()” for details and examples.

parameters:

• key — returns the object key or array index of the element at the current position

• value — returns the value of the element at the current position.

see also: %GetIterator()

class reference: %Iterator.Object.%GetNext()Opens in a new tab and %Iterator.Array.%GetNext()Opens in a new tab

Given a valid object key or array index, returns a string indicating the datatype of the value. See “Working with Datatypes” for details and examples.

parameters:

• key — the object key or array index of the value to be tested.

return values:

One of the following strings will be returned:

• "null" — a JSON null

• "boolean" — a zero (“false”) or non-zero (“true”) numeric value

• "number" — any canonical numeric value

• "oref" — a reference to another Caché object

• "object" — a nested object

• "array" — a nested array

• "string" — a standard text string

• "unassigned" — the property or element exists, but does not have an assigned value

see also: %IsDefined()

class reference: %DynamicAbstractObject.%GetTypeOf()Opens in a new tab

Tests if the item specified by key is defined within an object. Returns false if the item is unassigned or does not exist. See “Using %IsDefined() to Test for Valid Values” for details and examples.

parameters:

• key — the object key or array index of the item to be tested. An array index must be passed as a canonical integer value. Array indexes begin at position 0.

see also: Resolving Null, Empty String, and Unassigned Values

class reference: %DynamicObject.%IsDefined()Opens in a new tab and %DynamicArray.%IsDefined()Opens in a new tab

Returns the value of the last member of the array. The value is then removed from the array. If the array is already empty, the method returns the empty string, "". See “Using %Push and %Pop with Dynamic Arrays” for details and examples.

see also: %Push(), %Get(), %Remove(), Resolving Null, Empty String, and Unassigned Values

class reference: %DynamicArray.%Pop()Opens in a new tab

Given a new value, append it to the end of the current array, increasing the length of the array. value Returns An oref referencing the current modified array, allowing calls to %Push() to be chained. See “Using %Push and %Pop with Dynamic Arrays” for details and examples.

parameters:

• value — The value to be assigned to the new array element.

• type — optional string indicating the datatype of value. The following strings may be used:

  • "null" — a JSON null. The value argument must be "" (empty string).

  • "boolean" — a JSON false (value argument must be 0) or true (value argument must be 1).

  • "false" — a JSON false (value argument must be 0).

  • "true" — a JSON true (value argument must be 1).

  • "number" — convert value to a canonical numeric value

  • "string" — convert value to a text string

see also: %Pop(), %Set(), Overriding a Default Datatype with %Set() or %Push(), Method Chaining

class reference: %DynamicArray.%Push()Opens in a new tab

Removes the specified element from a dynamic object or array, and returns the value of the removed element. If the value of the element is an embedded dynamic object or array, all subordinate nodes are removed as well. In a dynamic array, all elements following the removed element will have their subscript position decremented by 1. See “Using %Set(), %Get(), and %Remove()” for details and examples.

parameters:

• key — the object key or array index of the element you wish to remove. An array index must be passed as a canonical integer value. Array indexes begin at position 0.

see also: %Set(), %Get(), %Pop()

class reference: %DynamicObject.%Remove()Opens in a new tab and %DynamicArray.%Remove()Opens in a new tab

Create a new value or update an existing value. Returns a reference to the modified array, allowing calls to %Set() to be nested. See “Using %Set(), %Get(), and %Remove()” for details and examples.

parameters:

• key — the object key or array index of the value you wish to create or update. An array index must be passed as a canonical integer value. Array indexes begin at position 0.

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

• type — optional string indicating the datatype of value. The following strings may be used:

  • "null" — a JSON null. The value argument must be "" (empty string).

  • "boolean" — a JSON false (value argument must be 0) or true (value argument must be 1).

  • "false" — a JSON false (value argument must be 0).

  • "true" — a JSON true (value argument must be 1).

  • "number" — convert value to a canonical numeric value

  • "string" — convert value to a text string

see also: %Get(), %Remove(), %Push(), Overriding a Default Datatype with %Set() or %Push(), Method Chaining

class reference: %DynamicObject.%Set()Opens in a new tab and %DynamicArray.%Set()Opens in a new tab

Returns an integer showing the size of a dynamic object or array. In the case of an array, the size includes unassigned entries within the array. In the case of an object, the size only includes elements that have assigned values. See “Sparse Array Iteration with %Size()” for details and examples.

see also: %GetNext()

class reference: %DynamicAbstractObject.%Size()Opens in a new tab

Converts an instance of %DynamicAbstractObject. into a JSON string. See “Converting Dynamic Entities to and from JSON” for details and examples.

parameters:

• outstrm — optional. There are a number of possibilities:

  • If outstrm is not specified and the method is called via DO, the JSON string is written to the current output device.

  • If outstrm is not specified and the method is called as an expression, the JSON string becomes the value of the expression.

  • If outstrm is specified as an instance of %Stream.ObjectOpens in a new tab, the JSON string will be written to the stream (see “Serializing Large Dynamic Entities to Streams” for details and examples).

  • If outstrm is an object but is not an instance of %Stream.ObjectOpens in a new tab then an exception will be thrown.

  • If outstrm is not an object and is not null then it is presumed to be a fully qualified file specification (the full path to the file must be defined). The file is linked to a newly created %Stream.FileCharacterOpens in a new tab stream, the JSON string is written to the stream, and the stream is saved to the file on completion.

see also: %FromJSON()

class reference: %DynamicAbstractObject.%ToJSON()Opens in a new tab