Module

Xojo.Data


Warning

This item was deprecated in version 2020r2. There is no replacement.

Description

This namespace contains methods and classes used for handling data.

Methods

Name

Parameters

Returns

Shared

GenerateJSON

value As Variant

String

ParseJSON

json As String

Variant

Method descriptions


Xojo.Data.GenerateJSON

GenerateJSON(value As Variant) As String

Generates JSON text from the supplied value, which is typically a Dictionary, an array of Dictionaries or an array of primitive data types (Integer, Text, etc.).

The order of data in a Dictionary is not guaranteed to match the order in the generated JSON. Order is retained for arrays. You can actually supply a single value that is not a Dictionary or an array and get it back as a single valid JSON object (it will encode quotes in text, for example), but those are not valid JSON by themselves.

Currency is not a valid type that can be converted to JSON.

Warning

An InvalidArgumentException will be raised if one of the types in value cannot be converted to a JSON data type.

Convert a simple array of Text to JSON data:

Dim values() As Text = Array("Red Sox", "Yankees", "Orioles", "Blue Jays", "Rays")
Dim json As Text = Xojo.Data.GenerateJSON(values)
// ["Red Sox","Yankees","Orioles","Blue Jays","Rays"]

Convert a Dictionary of values to JSON data:

Dim d As New Xojo.Core.Dictionary
d.Value("Team") = "Red Sox"
d.Value("City") = "Boston"

Dim json As Text
json = Xojo.Data.GenerateJSON(d)
// {"City":"Boston","Team":"Red Sox"}

If you want to store an array of information, create an array of Dictionaries and use that to generate the JSON:

Dim dictArray() As Xojo.Core.Dictionary
Dim d As Xojo.Core.Dictionary

d = New Xojo.Core.Dictionary
d.Value("Team") = "Red Sox"
d.Value("City") = "Boston"
dictArray.Append(d)

d = New Xojo.Core.Dictionary
d.Value("Team") = "Yankees"
d.Value("City") = "New York"
dictArray.Append(d)

Dim json As Text
json = Xojo.Data.GenerateJSON(dictArray)
// [{"City":"Boston","Team":"Red Sox"},{"City":"New York","Team":"Yankees"}]

Xojo.Data.ParseJSON

ParseJSON(json As String) As Variant

Parses JSON text and returns it as an Auto, which will typically contain a Dictionary, an array of Dictionaries or an array of primitive data types (Integer, Text, etc.) depending on the JSON text. If the returned value contains a Dictionary, it is case-sensitive.

The order of information in the JSON text is not guaranteed to match the order of the information in the resulting Dictionary. Order is retained for arrays. When looking at JSON, arrays are denoted by the use of square brackets ([]) to identify the array. Curly braces identify objects.

JSON data types map to corresponding Xojo types as follows:

JSON Data Type

Xojo.Data Type

Number

Auto containing a numeric type such as Integer or Double.

String

Auto containing a Text.

Boolean

Auto containing a Boolean.

Array, noted by []

Auto containing array: Auto()

Value

Auto containing the value.

Object, noted by {}

Auto containing a Dictionary.

Whitespace

n/a

Null

Auto is Nil.

Warning

An InvalidJSONException will be raised if the supplied json Text is not valid JSON data.

Convert JSON data (in array form) back to an array (note the user of the square bracket surrounding the JSON text elements):

// json contains actual JSON data:
// ["Red Sox","Yankees","Orioles","Blue Jays","Rays"]
Dim names() As Auto
names = Xojo.Data.ParseJSON(json)

Dim teamNames() As Text
For Each name As Text In names
  teamNames.Append(name)
Next

Convert JSON data to a Dictionary:

// jsonText contains actual JSON data:
// {"City":"Boston","Team":"Red Sox"}
Dim dict As Xojo.Core.Dictionary
dict = Xojo.Data.ParseJSON(jsonText)

To load a JSON data array into an array of Dictionaries:

// kJsonData contains the actual JSON data in a Constant:
// [{"City":"Boston","Team":"Red Sox"},{"City":"New York","Team":"Yankees"}]
Dim jsonArray() As Auto
jsonArray = Xojo.Data.ParseJSON(kJsonData)

Dim nyTeam As Text = Xojo.Core.Dictionary(jsonArray(1)).Value("Team")
// nyTeam = "Yankees"

// Now loop through the array
Dim dict As Xojo.Core.Dictionary
Dim value As Text
For Each d As Xojo.Core.Dictionary In jsonArray
  value = d.Value("Team")
Next

To get a value that is within an object in the JSON data, you assign the object to a Dictionary and then reference the value it contains:

// jsonData contains the actual JSON data:
// {"team":"Red Sox","topplayer":{"name":"David Ortiz", "position":"DH", "uniform number":34}}

Dim d As Xojo.Core.Dictionary
d = Xojo.Data.ParseJSON(jsonData)
Dim topPlayer As Xojo.Core.Dictionary = d.Value("topplayer")
Dim playerName As Text = topPlayer.Value("name")

Compatibility

All project types on all supported operating systems.

See also

Dictionary