Detailed Description

FastLED's Elegant JSON Library: fl::json

The fl::json library provides a lightweight, type-safe, and highly ergonomic interface for both parsing and generating JSON data within the FastLED ecosystem.

Key Features & Design Principles:

Fluid Chaining: Effortlessly navigate nested JSON structures using json["key"]["nested_key"] or json["array_key"][index].
Default Values (operator|): The cornerstone of robust parsing. Safely extract values with a fallback, preventing crashes from missing keys or type mismatches: int value = json["path"]["to"]["key"] | 123;
Type Safety: Methods return fl::optional<T> for explicit handling of potential absence or type errors, ensuring predictable behavior.
Unified API: A consistent and intuitive interface for both reading and writing JSON data.
Explicit Creation: Clearly define JSON objects and arrays using fl::json::object() and fl::json::array().

Parsing JSON Data - The Clean Way:

Parse a JSON string and extract values with graceful defaults.

#include "fl/stl/json.h"
#include "fl/log/log.h" // For FL_WARN
 
const char* jsonStr = R"({
  "config": {
    "brightness": 128,
    "enabled": true,
    "name": "my_device"
  },
  "status": "active"
})";
 
fl::json jsonDoc = fl::json::parse(jsonStr);
 
// Accessing an integer with a default value
int brightness = jsonDoc["config"]["brightness"] | 255; // Result: 128
FL_WARN("Brightness: " << brightness);
 
// Accessing a boolean with a default value
bool enabled = jsonDoc["config"]["enabled"] | false;    // Result: true
FL_WARN("Enabled: " << enabled);
 
// Accessing a string with a default value
fl::string deviceName = jsonDoc["config"]["name"] | fl::string("unknown"); // Result: "my_device"
FL_WARN("Device Name: " << deviceName);
 
// Accessing a non-existent key with a default value
int nonExistent = jsonDoc["config"]["non_existent_key"] | 0; // Result: 0
FL_WARN("Non-existent: " << nonExistent);

Generating JSON Data - Build with Ease:

Construct complex JSON objects and arrays programmatically.

#include "fl/stl/json.h"
#include "fl/stl/string.h"
#include "fl/stl/vector.h"
#include "fl/log/log.h"
 
// Create a root JSON object
fl::json newJson = fl::json::object();
 
// Set primitive values
newJson.set("version", 1.0);
newJson.set("isActive", true);
newJson.set("message", "Hello, FastLED!");
 
// Create and set a nested object
fl::json settings = fl::json::object();
settings.set("mode", "dynamic");
settings.set("speed", 50);
newJson.set("settings", settings);
 
// Create and set a nested array
fl::json colors = fl::json::array();
colors.push_back(fl::json("red"));
colors.push_back(fl::json("green"));
colors.push_back(fl::json("blue"));
newJson.set("colors", colors);
 
// Convert the entire JSON object to a string
fl::string jsonString = newJson.to_string();
FL_WARN("Generated JSON:\n" << jsonString);
// Expected output (formatting may vary):
// {"version":1.0,"isActive":true,"message":"Hello, FastLED!","settings":{"mode":"dynamic","speed":50},"colors":["red","green","blue"]}

Important Considerations:

Null Values: A json object can represent JSON null or be completely uninitialized. Use is_null() to explicitly check for JSON null values.
Memory Management: fl::json uses fl::shared_ptr internally, enabling efficient copying and avoiding manual memory management pitfalls.
Error Handling: Missing keys or type mismatches result in fl::optional values that can be safely queried or defaulted using operator|.

Thread Safety:

fl::json is not inherently thread-safe. If you need to share JSON data across threads, ensure proper synchronization using mutexes or similar mechanisms.

Performance Notes:

Parsing: Native parser is 1.62x faster than ArduinoJson with 62.5% higher throughput
Memory: 45% fewer allocations and 24% lower peak memory than ArduinoJson
Validation: Zero heap allocations during validation phase