Class

JSONItem


Description

Used for parsing and creating Javascript Object Notation (JSON) strings. A JSONItem can use either named keys or indexed values (like an array), but not both. See the Notes section for more information.

Properties

Name

Type

Read-Only

Shared

Compact

Boolean

ToString

String

Methods

Name

Parameters

Returns

Shared

Add

Value As Variant

AddAt

Index As Integer, Value As Variant

Child

name As String

JSONItem

ChildAt

Index As Integer

JSONItem

Constructor

Constructor

JSONString As String

Constructor

d As Dictionary

Count

Integer

HasKey

Key As String

Boolean

IsArray

Boolean

KeyAt

Index As Integer

String

Keys

String()

LastRowIndex

Integer

Load

JSONString As String

Lookup

Name As String, DefaultValue As Variant

Variant

Remove

Name As String

RemoveAll

RemoveAt

Index As Integer

Value

Name As String

Variant

Name As String, Assigns value As Variant

ValueAt

index As Integer

Variant

index As Integer, Assigns value As Variant

Property descriptions


JSONItem.Compact

Compact As Boolean

When getting the String representation of a JSONItem using the ToString method, setting this property to True (the default) will remove unnecessary whitespace from the resulting string. A value of False will result in a string with SPACEs and EndOfLines embedded to make the string more readable.

This example sets Compact to True before calling ToString.

Var person As New JSONItem
// This object is manipulated like a dictionary
person.Value("Name") = "John Doe"
person.Value("Age") = 32
person.Value("Married") = True
person.Value("Spouse") = "Jane Doe"

Var kids As New JSONItem
// This object is manipulated like an array
kids.Add("John Jr")
kids.Add("Jamie")
kids.Add("Jack")
kids.Add("Josie")
kids.AddAt(0,"Jonah")
kids.RemoveAt(2)
person.Value("Kids") = kids

Person.Compact = True
Var s As String = person.ToString

JSONItem.ToString

ToString As String

Returns a JSON String representing the current object.

Method descriptions


JSONItem.Add

Add(Value As Variant)

Adds the passed value to the end of a JSONItem array.


JSONItem.AddAt

AddAt(Index As Integer, Value As Variant)

Adds the passed value into a JSONItem array at the position specified by Index.


JSONItem.Child

Child(name As String) As JSONItem

Sets a named child to a JSONItem.

Var myChild As New JSONItem

myChild.Value("Name") = "Fred"
myChild.Value("Age") = 12
myChild.Value("Married") = False

myChild.ChildAt(2) = person

JSONItem.ChildAt

ChildAt(Index As Integer) As JSONItem

Sets a child to a JSONItem by index. Index is zero-based.

Var myChild As New JSONItem
myChild.ChildAt(2) = person

JSONItem.Constructor

Constructor

Note

Constructors are special methods called when you create an object with the New keyword and pass in the parameters above.

Creates an empty JSON object.


JSONItem.Constructor

Constructor(JSONString as String)

Note

Constructors are special methods called when you create an object with the New keyword and pass in the parameters above.

Parses the passed JSON string into the document. If any parsing errors occur, a JSONException will be thrown.

Var js As String = "{""Name"":""John Doe"",""Age"":32,""Kids"":[""Jonah"",""John Jr""],""Married"":true,""Spouse"":""Jane Doe""}"
Var j As New JSONItem(js)

JSONItem.Constructor

Constructor(d as Dictionary)

Note

Constructors are special methods called when you create an object with the New keyword and pass in the parameters above.

Parses the passed Dictionary string into the document. If any parsing errors occur, a JSONException will be thrown.


JSONItem.Count

Count As Integer

Returns the number of children.

Var person As New JSONItem
Var i As Integer
person.DecimalFormat = "###,###.##"

//This object is manipulated like a dictionary
person.Value("Name") = "John Doe"
person.Value("Age") = 32
person.Value("Married") = True
person.Value("Spouse") = "Jane Doe"

i = person.Count

JSONItem.HasKey

HasKey(Key As String) As Boolean

Returns True if the child key exists.

The following example calls HasKey to check if the passed key exists.

If myUncle.HasKey("Name") Then
  MessageBox("myUncle.Name has a name.")
End If

JSONItem.IsArray

IsArray As Boolean

Returns True if the JSONItem is being treated as an array and False if it acts as a Dictionary.


JSONItem.KeyAt

KeyAt(Index As Integer) As String

Returns the name of a child key by index. Array items will return an empty string.

Var person As New JSONItem

// This object is manipulated like a dictionary
person.Value("Name") = "John Doe"
person.Value("Age") = 32
person.Value("Married") = True
person.Value("Spouse") = "Jane Doe"

Var s2 As String
s2 = person.KeyAt(1) // returns "Age"

JSONItem.Keys

Keys As String()

Returns the keys of the children. Array items will not be included.

This example populates a String array with the keys of the person JSONItem.

Var person As New JSONItem

//This object is manipulated like a dictionary
person.Value("Name") = "John Doe"
person.Value("Age") = 32
person.Value("Married") = True
person.Value("Spouse") = "Jane Doe"

Var people() As String
people() = person.Keys // the array will now contain the keys as used above

JSONItem.LastRowIndex

LastRowIndex As Integer

The number of the last row of the JSONItem.


JSONItem.Load

Load(JSONString As String)

Loads and parses a JSON String. If any parsing errors occur, a JSONException will be thrown.

This example loads a JSON string, s, into a JSONItem.

Var r As New JSONItem
r.Load(s)

JSONItem.Lookup

Lookup(Name As String, DefaultValue As Variant) As Variant

Looks up the passed value of Name. Returns a Variant.

If Name is found, it returns the corresponding value. If Name is not found, it returns the passed DefaultValue.

Var myChild As New JSONItem

myChild.Value("Name") = "Fred"
myChild.value("Age") = 12
myChild.value("Married") = False

Var v As Variant
v = myChild.Lookup("Age", "Data not found")
MessageBox(v) // displays the value for Age

JSONItem.Remove

Remove(Name As String)

Removes the child with the passed Name.

This example removes a value using its name:

Var person As New JSONItem
// This object is manipulated like a dictionary
person.Value("Name") = "John Doe"
person.Value("Age") = 32
person.Value("Married") = True
person.Value("Spouse") = "Jane Doe"
person.Remove("Age")

JSONItem.RemoveAll

RemoveAll

Removes all children and resets the JSONItem type (object or array).

Var person As New JSONItem
.
.
person.RemoveAll

JSONItem.RemoveAt

RemoveAt(Index As Integer)

Removes the child with the passed Index.

This example removes a value using its index:

Var kids As New JSONItem
// This object is manipulated like an array
kids.Add("John Jr")
kids.Add("Jamie")
kids.Add("Jack")
kids.Add("Josie")
kids.AddAt(0, "Jonah")
kids.RemoveAt(2)

person.Value("Kids") = kids

JSONItem.Value

Value(name As String) As Variant)

Returns a named child's value.


Value(name As String, Assigns As Variant)

Sets a named child's value.


JSONItem.ValueAt

ValueAt(index As Integer) As Variant

Returns a named child's value by index.

ValueAt(index As Integer, Assigns As Variant)

Sets a named child's value by index.

Notes

JSON is a lightweight data exchange format. It is described at here. It is based on the Javascript language and uses two structures.

JSON Objects can contain named data a collection of name-value pairs (like a Dictionary) as well as indexed data (like an array). To facilitate this, JSONItems can manipulate data in either way with the following restrictions:

  • The first element that you add to a JSONItem determines its type.

  • Array objects can be accessed only by index.

  • A JSONItem's type cannot be changed without resetting the object with the Clear method.

Names must be Strings, must be unique within an object and are case-sensitive.

Values can be any of the following types: Strings, numbers, JSONItems, arrays (string, number or boolean), Booleans, or Nil.

Per the JSON spec, strings must be UTF8-encoded. Unless you are specifically encoding them differently, they will be UTF8 by default.

Sample code

This code populates a JSONItem with data and then displays it in its raw form in a TextArea:

Var person As New JSONItem
// This object is manipulated like a dictionary
person.Value("Name") = "John Doe"
person.Value("Age") = 32
person.Value("Married") = True
person.Value("Spouse") = "Jane Doe"

Var kids As New JSONItem
// This object is manipulated like an array
kids.Add("John Jr")
kids.Add("Jamie")
kids.Add("Jack")
kids.Add("Josie")
kids.AddAt(0,"Jonah")
kids.RemoveAt(2)
person.Value("Kids") = kids

Person.Compact = True
Var s As String = person.ToString

TextArea1.Text = s

Create a JSONItem from a JSON String:

Var js As String = "{""Name"":""John Doe"",""Age"":32,""Kids"":[""Jonah"",""John Jr""],""Married"":true,""Spouse"":""Jane Doe""}"
Var j As New JSONItem(js)

Convert a Dictionary into a JSONItem:

Var d As New Dictionary
d.Value("Name") = "John Doe"
d.Value("Age") = 32
d.Value("Married") = True
d.Value("Spouse") = "Jane Doe"

Var j As JSONItem
j = d

Create a JSONItem with code and convert to a JSON String:

Var person As New JSONItem
// This object is manipulated like a dictionary
person.Value("Name") = "John Doe"
person.Value("Age") = 32
person.Value("Married") = True
person.Value("Spouse") = "Jane Doe"

Var kids As New JSONItem
// This object is manipulated like an array
kids.Add("John Jr")
kids.Add("Jamie")
kids.AddAt(0, "Jonah")
kids.RemoveAt(2)

// Add the Kids object to the Person object
person.Value("Kids") = kids

// Convert to a JSON String
Var s As String = person.ToString

Compatibility

All project types on all supported operating systems.

See also

Object parent class; Dictionary class; GenerateJSON, ParseJSON methods; JSONException.