jsValueAdd

Adds or modifies a JSON key/value pair.

Syntax:

jsValueAdd ( container-handle , key-name, key-value, json-type [, key-delimiter] )

Parameters:

(s) container-handle: extender JSON container handle.

(s) key-name: name of an existing or new key including the full JSON path to the key. Can include JSON array indices.

(s) key-value: string representation of a value to associate with the key.

(i) value-type: a JSON data type indicating the type to convert key-value text to. See below

(s) key-delimiter: [optional] single character used between key names in any path included in the key-name parameter (defaults to a dot character(".")).

Returns:

(i) 1 on success.

This function adds a key/value pair or array element to the passed in JSON container, one of its child containers, or array contained within the container or sub-container.. JsValueAdd can also be used to modify the value of an existing pair or index by placing an existing key name with optional index in the key-name parameter.

Container-Handle

The unique identifier returned from a call to the jsParse, jsObjNew, jsValueGet functions, or by accessing WIL map element returned by the jsConMap function.

Key-Name

The name to associate with the value of a JSON key/value pair or an array index. The key name can be a new name or index to add a new key/value pair or index/value to the JSON container, or the name of an existing key/index to change the value of the existing item. The name must include JSON path information when adding an item to a child object and a bracketed index number when adding an element of an array. See the About JSON Paths topic for more information about the extender's JSON paths.

Important:

• JSON key names are case sensitive, so make sure the key-name is spelled correctly and matches the case of the key stored in the JSON data.

• A key-name and any path container names must always be surrounded by square brackets when the name contains embedded square brackets or the current key-name delimiter.

Key-Value

The value to associate with the key-name of the new or existing item. This parameter must either be a text string or a value that WIL can convert to a string. The extender converts the parameter to the JSON type indicated in the value-type parameter.

Note: a container handle cannot be added to itself. This means that the same handle to a JSON container cannot be used in both the Container-Handle parameter and the Key-value parameter in a single function call.

Value-Type

The  JSON type of the contents of the Key-Value parameter. The function performs a conversion of the text in the Key-Value parameter to the indicated type.  

  Possible Value-Type and Key-Value Parameter Contents

Key-Delimiter

An optional parameter that must be a single character used between key names. The default value is a dot (".")). The space(' '), backslash('\'), single-quote("'"), double-quote('"'), dollar-sign("$"), left-bracket("["), right-bracket("]") and grave-accent("`") cannot be used as delimiters.   

Example:

  AddExtender('ilcjs44i.dll', 0, 'ilcjs64i.dll')
  
  ; Build the extender JSON data example from scratch.
  
  ; Good to start at the beginning
  Obj = jsConNew()
  jsValueAdd(Obj, 'pi', 3.121, @JsonNum)
  ; For @jsTypeBool third parameter can be 'true or 'false' or a
  ; number with zero meaning false and any other number meaning true.
  jsValueAdd(Obj, 'happy', 'true', @JsonBool)
  ; For @jsTypeNull third parameter is ignored.
  jsValueAdd(Obj, 'nothing', '', @JsonNull)
  jsValueAdd(Obj, 'name', 'WinBatch', @JsonStr)
  ; Can add pairs to child object before or after
  ; adding the child object to the parent.
  ChildObj = jsConNew()
  jsValueAdd(Obj, 'answer', ChildObj, @JsonObj)
  jsValueAdd(Obj, 'answer.everything', 42, @JsonNum)
  ; Arrays are added one element at a time.
  jsValueAdd(Obj, 'list', '', @JsonArr)
  jsValueAdd(Obj, 'list[0]', 1, @JsonNum)
  jsValueAdd(Obj, 'list[1]', 0, @JsonNum)
  jsValueAdd(Obj, 'list[2]', 2, @JsonNum)
  ; This time build the child object with pairs
  ; before adding to the parent object.
  ChildObj2 = jsConNew()
  jsValueAdd(ChildObj2, 'currency', 'USD', @JsonStr)
  jsValueAdd(ChildObj2, 'value', 42.99, @JsonNum)
  jsValueAdd(Obj, 'object', ChildObj2, @JsonObj)
  ; Get the result as text.
  JsonText = jsSerialize(Obj, @true)
  jsConClose()
  
  Message('Look Familiar?', JsonText)
  

See Also:

jsParse, jsConNew,jsValueType,jsValueGet