Part 1: Building JSON

Building JSON from scratch means firing up a new JSONItem and throwing data at it. Don’t build JSON by stitching strings together. It breaks easily, you’ll mess up the escaping, and JSONItem makes it completely unnecessary.

The Basic Payload

When you just need to fire a flat object at a web service:

Var apiPayload As New JSONItem
apiPayload.Value("endpoint") = "/users/create"
apiPayload.Value("timestamp") = 1715423000
apiPayload.Value("forceSync") = True

// Get the string back
Var jsonString As String = apiPayload.ToString
// {"endpoint":"/users/create","timestamp":1715423000,"forceSync":true}

Making Arrays

If you’re making a list of tags or IDs, use the .Add method. The moment you call .Add, Xojo treats that JSONItem as a JSON array under the hood.

Var tags As New JSONItem
tags.Add("xojo")
tags.Add("desktop")
tags.Add("api")

Var jsonString As String = tags.ToString
// ["xojo","desktop","api"]

Nesting Things

Most APIs want nested payloads. You map this out by making separate JSONItem objects and attaching them to each other.

Var payload As New JSONItem
payload.Value("status") = "active"

Var user As New JSONItem
user.Value("id") = 982
user.Value("username") = "johndoe"

Var roles As New JSONItem
roles.Add("admin")
roles.Add("editor")

user.Value("roles") = roles // Attach the array to the user object
payload.Value("data") = user // Attach the user object to the main payload

Var jsonString As String = payload.ToString
// {"status":"active","data":{"id":982,"username":"johndoe","roles":["admin","editor"]}}

Part 2: Parsing JSON

To go the other direction, pass a raw JSON string straight into the constructor.

Reading a Flat Response

When a server hands you back a flat config or auth token, just pull the values right out.

Var rawJSON As String = "{""token"":""abc123xyz"",""expiresIn"":3600,""active"":true}"
Var response As New JSONItem(rawJSON)

Var token As String = response.Value("token")
Var expiresIn As Integer = response.Value("expiresIn")
Var isActive As Boolean = response.Value("active")

Handling Optional Keys with Lookup

If you use .Value("key") and the key isn’t in the JSON, Xojo throws a KeyNotFoundException. Instead of writing boilerplate If response.HasKey("key") Then checks everywhere, use .Lookup(). It lets you define a fallback value in line.

Var rawJSON As String = "{""username"":""johndoe""}"
Var response As New JSONItem(rawJSON)

// Returns "johndoe" because the key is present
Var user As String = response.Lookup("username", "anonymous") 

// Returns False because "forceSync" is missing from the JSON
Var isSyncForced As Boolean = response.Lookup("forceSync", False) 

Looping Over an Array

If an API hands you a list of database records:

Var rawJSON As String = "[{""id"":1, ""name"":""Alice""}, {""id"":2, ""name"":""Bob""}]"
Var userList As New JSONItem(rawJSON)

For i As Integer = 0 To userList.Count - 1
  Var currentUser As JSONItem = userList.ValueAt(i)

  Var id As Integer = currentUser.Value("id")
  Var name As String = currentUser.Value("name")

  System.DebugLog(id.ToString + ": " + name)
Next

Digging out Nested Nodes

This is where .Child() comes in handy. While .Value() returns a generic Variant (which you can’t chain directly), .Child("key") explicitly returns the nested object as a JSONItem. This allows for perfectly clean chaining.

Var rawJSON As String = "{""weather"":{""current"":{""temp"":22, ""condition"":""Sunny""}}}"
Var forecast As New JSONItem(rawJSON)

// Use .Child() to tunnel down into objects, then .Value() to pull the final primitive data 
Var temperature As Double = forecast.Child("weather").Child("current").Value("temp")
Var condition As String = forecast.Child("weather").Child("current").Value("condition")

Part 3: Identifying the Structure

APIs are notoriously inconsistent. Check the .IsArray property to figure out what structure you’re dealing with before parsing it, so your loops don’t crash when passing something unexpected.

Var rawJSON As String = "[""apple"", ""banana"", ""orange""]"
Var parsedData As New JSONItem(rawJSON)

If parsedData.IsArray Then
  System.DebugLog("Looks like an array with " + parsedData.Count.ToString + " items.")

  For i As Integer = 0 To parsedData.Count - 1
    System.DebugLog(parsedData.ValueAt(i).StringValue)
  Next
Else
  System.DebugLog("It's a standard dictionary.")
  If parsedData.HasKey("data") Then
    System.DebugLog(parsedData.Value("data").StringValue)
  End If
End If

That’s it. For more info on JSONItem, don’t forget to check the online documentation at: https://documentation.xojo.com/api/text/json/jsonitem.html

Gabriel is a digital marketing enthusiast who loves coding with Xojo to create cool software tools for any platform. He is always eager to learn and share new ideas!

• Facebook
• X
• LinkedIn
• GitHub
• YouTube

This article will cover the Pair class, highlight its strengths, compare it with Arrays and Dictionaries, and assist you in identifying the most suitable tool for your needs.

What is the Pair Class?

In Xojo, the Pair class is a basic structure that stores two associated values: Left and Right. These properties can be of any data type, allowing you to pair together any two pieces of data.

Var myPair As New Pair("Pie", 15)
// or
Var myPair As Pair = "Pie" : 15

In the example above, myPair.Left is "Pie" (a String), and myPair.Right is 15 (an Integer). The Pair class is especially handy when you need to associate two pieces of data without the overhead of creating a dedicated class or structure.

Advantages of Using the Pair Class

1. Returning Multiple Values from a Method

Sometimes, you need a method to return more than one value. While you could use ByRef parameters or create a custom class, using a Pair provides a quick and clean solution.

Example:

Public Function GetMinMax(values() As Integer) As Pair
  Var minValue As Integer = values(0)
  Var maxValue As Integer = values(0)
  
  For Each value As Integer In values
    If value < minValue Then minValue = value
    If value > maxValue Then maxValue = value
  Next
  
  Return New Pair(minValue, maxValue)
End Function

// Usage
Var numbers() As Integer = Array(5, 2, 8, 3, 9)
Var result As Pair = GetMinMax(numbers)
MessageBox("Min: " + result.Left.StringValue + ", Max: " + result.Right.StringValue)

2. Associating Related Data Temporarily

When processing data, you might need to temporarily associate two values without persisting them or creating a complex data structure.

Example:

Var people() As Pair
people.Append(New Pair("Alice", 30))
people.Append(New Pair("Bob", 25))
people.Append(New Pair("Charlie", 35))

For Each person As Pair In people
  MessageBox(person.Left.StringValue + " is " + person.Right.IntegerValue.ToString + " years old.")
Next

3. Representation of Key-Value Pairs

While Dictionaries are designed for key-value storage, sometimes you might need to represent key-value pairs explicitly, such as when iterating over a Dictionary’s entries.

Example:

Var dict As New Dictionary
dict.Value("Red") = "#FF0000"
dict.Value("Green") = "#00FF00"
dict.Value("Blue") = "#0000FF"

For Each key As Variant In dict.Keys
  Var entry As New Pair(key, dict.Value(key))
  MessageBox(entry.Left.StringValue + " color code is " + entry.Right.StringValue)
Next

Comparison: Pair vs. Arrays vs. Dictionaries

Understanding when to use the Pair class over Arrays or Dictionaries is crucial for writing efficient code.

Pair

• Structure: Holds exactly two related values (Left and Right).
• Type Safety: Both Left and Right can be any data type.
• Usage: Ideal for associating two pieces of data temporarily or for methods that need to return two values.
• Performance: Lightweight and minimal overhead.

Arrays

• Structure: Ordered collection of elements, accessible by index.
• Type Safety: Elements are of the same data type (unless you use Variant arrays).
• Usage: Best when dealing with lists of items where order matters.
• Performance: Efficient for iterating over large collections.

Dictionaries

• Structure: Collection of key-value pairs, with unique keys.
• Type Safety: Keys are typically String or Integer, values can be any data type.
• Usage: When you need fast lookup of values by keys.
• Performance: Optimized for key-based access; overhead of hash table management.

Considerations for Using Pair Instead of Arrays or Dictionaries

• Simplicity: When you need to associate two items without creating a complex structure.
• Temporary Associations: For short-lived pairings within methods or loops.
• Returning Multiple Values: When methods need to return two related results.

Best Practices with Pair

• Immutable Data: Since Pair is a class, be cautious when modifying Left or Right properties, especially if the Pair is shared among different parts of your code.
• Descriptive Code: Use comments or naming conventions to clarify what Left and Right represent, as they do not provide semantic meaning on their own.

Example:

// Pair: Left = Product Name, Right = Price
Var productPair As New Pair("Laptop", 999.99)

Drawbacks and Constraints of the Pair Class

• Lack of Clarity: Unlike custom classes or structures, Pair does not convey the meaning of its contents through property names.
• Fixed Size: Limited to exactly two items; for more complex data, consider using a class or structure.
• Reference Type: Being a class, Pair is a reference type, which can have implications for memory management and threading.

Conclusion

The Pair class is a handy tool that can simplify your code when you need to associate two related values. While it doesn’t replace Arrays or Dictionaries, the Pair class is valuable in particular situations that prioritize simplicity and efficiency.

Resources:

• Learn more about Pair
• Learn more about Arrays
• Learn more about Dictionary

Gabriel is a digital marketing enthusiast who loves coding with Xojo to create cool software tools for any platform. He is always eager to learn and share new ideas!

• Facebook
• X
• LinkedIn
• GitHub
• YouTube