Add( ) method (JsonArray)

Creates one or more new elements and adds them at a specified index or to the end of the JsonArray. On successful completion, this method returns the index of the last newly added element.

Return type:

INTEGER

Access:

PUBLIC

Applies to:

Progress.Json.ObjectModel.JsonArray class

 

Syntax 

Add( INPUT value AS CHARACTER )   Add( INPUT array-value AS CHARACTER EXTENT )   Add( INPUT value AS COM-HANDLE )   Add( INPUT array-value AS COM-HANDLE EXTENT )   Add( INPUT value AS DATE )   Add( INPUT array-value AS DATE EXTENT )   Add( INPUT value AS DATETIME )   Add( INPUT array-value AS DATETIME EXTENT )   Add( INPUT value AS DATETIME-TZ )   Add( INPUT array-value AS DATETIME-TZ EXTENT )   Add( INPUT value AS DECIMAL )   Add( INPUT array-value AS DECIMAL EXTENT )   Add( INPUT value AS HANDLE )   Add( INPUT array-value AS HANDLE EXTENT )   Add( INPUT value AS INT64 )   Add( INPUT array-value AS INT64 EXTENT )   Add( INPUT value AS INTEGER )   Add( INPUT array-value AS INTEGER EXTENT )   Add( INPUT value AS LOGICAL )   Add( INPUT array-value AS LOGICAL EXTENT )   Add( INPUT value AS LONGCHAR )   Add( INPUT array-value AS LONGCHAR EXTENT )   Add( INPUT value AS MEMPTR )   Add( INPUT value AS CHARACTER )   Add( INPUT array-value AS CHARACTER EXTENT )   Add( INPUT value AS COM-HANDLE )   Add( INPUT array-value AS COM-HANDLE EXTENT )   Add( INPUT value AS DATE )

Add( INPUT array-value AS DATE EXTENT )   Add( INPUT value AS DATETIME )   Add( INPUT array-value AS DATETIME EXTENT )   Add( INPUT value AS DATETIME-TZ )   Add( INPUT array-value AS DATETIME-TZ EXTENT )   Add( INPUT value AS DECIMAL )   Add( INPUT array-value AS DECIMAL EXTENT )   Add( INPUT value AS HANDLE )   Add( INPUT array-value AS HANDLE EXTENT )   Add( INPUT value AS INT64 )   Add( INPUT array-value AS INT64 EXTENT )   Add( INPUT value AS INTEGER )   Add( INPUT array-value AS INTEGER EXTENT )   Add( INPUT value AS LOGICAL )   Add( INPUT array-value AS LOGICAL EXTENT )   Add( INPUT value AS LONGCHAR )   Add( INPUT array-value AS LONGCHAR EXTENT )   Add( INPUT value AS MEMPTR )   Add( INPUT array-value AS MEMPTR EXTENT )   Add( INPUT value AS RAW )   Add( INPUT array-value AS RAW EXTENT )   Add( INPUT value AS RECID )   Add( INPUT array-value AS RECID EXTENT )   Add( INPUT value AS ROWID )   Add( INPUT array-value AS ROWID EXTENT )   Add( INPUT value AS CLASS JsonObject )   Add( INPUT array-value AS CLASS JsonObject EXTENT )   Add( INPUT value AS CLASS JsonArray )   Add( INPUT array-value AS CLASS JsonArray EXTENT )   Add( INPUT index AS INTEGER, INPUT value AS CHARACTER )

Add( INPUT index AS INTEGER,      INPUT array-value AS CHARACTER EXTENT )   Add( INPUT index AS INTEGER, INPUT value AS COM-HANDLE )   Add( INPUT index AS INTEGER,      INPUT array-value AS COM-HANDLE EXTENT )   Add( INPUT index AS INTEGER, INPUT value AS DATE )   Add( INPUT index AS INTEGER,      INPUT array-value AS DATE EXTENT )   Add( INPUT index AS INTEGER, INPUT value AS DATETIME )   Add( INPUT index AS INTEGER,      INPUT array-value AS DATETIME EXTENT )   Add( INPUT index AS INTEGER, INPUT value AS DATETIME-TZ )   Add( INPUT index AS INTEGER,      INPUT array-value AS DATETIME-TZ EXTENT )   Add( INPUT index AS INTEGER, INPUT value AS DECIMAL )   Add( INPUT index AS INTEGER,      INPUT array-value AS DECIMAL EXTENT )   Add( INPUT index AS INTEGER, INPUT value AS HANDLE )   Add( INPUT index AS INTEGER,      INPUT array-value AS HANDLE EXTENT )   Add( INPUT index AS INTEGER, INPUT value AS INT64 )   Add( INPUT index AS INTEGER,      INPUT array-value AS INT64 EXTENT )   Add( INPUT index AS INTEGER, INPUT value AS INTEGER )   Add( INPUT index AS INTEGER,      INPUT array-value AS INTEGER EXTENT )   Add( INPUT index AS INTEGER, INPUT value AS LOGICAL )   Add( INPUT index AS INTEGER,      INPUT array-value AS LOGICAL EXTENT )   Add( INPUT index AS INTEGER, INPUT value AS LONGCHAR )   Add( INPUT index AS INTEGER,      INPUT array-value AS LONGCHAR EXTENT )   Add( INPUT index AS INTEGER, INPUT value AS MEMPTR )   Add( INPUT index AS INTEGER,      INPUT array-value AS MEMPTR EXTENT )   Add( INPUT index AS INTEGER, INPUT value AS RAW )   Add( INPUT index AS INTEGER,      INPUT array-value AS RAW EXTENT )

Add( INPUT index AS INTEGER, INPUT value AS RECID )   Add( INPUT index AS INTEGER,      INPUT array-value AS RECID EXTENT )   Add( INPUT index AS INTEGER, INPUT value AS ROWID )   Add( INPUT index AS INTEGER,      INPUT array-value AS ROWID EXTENT )   Add( INPUT index AS INTEGER,      INPUT value AS CLASS JsonObject )   Add( INPUT index AS INTEGER,      INPUT array-value AS CLASS JsonObject EXTENT )   Add( INPUT index AS INTEGER,      INPUT value AS CLASS JsonArray )   Add( INPUT index AS INTEGER,      INPUT array-value AS CLASS JsonArray EXTENT )

value

The value to which the new element is to be set. If value is the Unknown value (?), the element is set to the JSON null value.

If value is a simple type, the JsonArray:Length property is incremented by one. If value is an ABL array, JsonArray:Length is incremented by the length of the ABL array.

array-value

ABL array containing values used to initialize a set of new elements. Each element of the ABL array is used to initialize one new element in the JsonArray. Any Unknown value (?) within the ABL array will result in a JSON null value in the JsonArray. If array-value itself is the Unknown value (?) or indeterminate, a JsonError is raised.

index

An INTEGER identifying the element after which the new element or elements are added. Indexing into JsonArrays is 1-based. For example, myArray:Add(5, “custnum”) inserts a String value “custnum” as element 6 into the JsonArray. All elements starting with the original sixth element are shifted by one position.

If index is 0, the new element is inserted at the beginning of the array making that new element’s index 1. If index is not provided, the default behavior is to add new elements to the end of the array. If index is the Unknown value (?), less than 0, or is greater than the length of the array, a JsonError is raised.

The data type of the added JSON value set by this method call depends upon the ABL data type of the value parameter.

Table 126:

Value parameter

A value parameter of data type	Data type of JSON value
CHARACTER, LONGCHAR	string
INTEGER, INT64, DECIMAL	number
LOGICAL	boolean
MEMPTR, RAW, ROWID	string with a value as if you had called BASE64-ENCODE( ) on value
DATE, DATETIME, DATETIME-TZ	string with a value as if you had called ISO-DATE( ) on value
COM-HANDLE, HANDLE, RECID	number with a value as if you had called INTEGER( ) on value

The following example demonstrates how the Add( ) overloaded methods affect a JsonArray:

DEFINE VARIABLE a AS INTEGER EXTENT 3 INITIAL [3, 2, 1]. DEFINE VARIABLE b AS CHARACTER EXTENT 2 INITIAL [“Hello”, “world”]. DEFINE VARIABLE c AS DATE EXTENT 2 INITIAL [“9/20/10”, “10/10/10”].   myArr = NEW JsonArray(a) /* myArr is now [3, 2, 1] */   myArr:Add(TRUE). /* myArr is now [3, 2, 1, true] */ myArr:Add(b). /* myArr is now [3, 2, 1, true, “Hello”, “world”] */   myArr:Add(2, c). /* myArr is now [3, 2, “2010-09-20”, “2010-10-10”, 1, true, “Hello”, “world”] */