json.h File Reference

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

See also

fl::json

fl::optional

Definition in file json.h.

#include "fl/stl/json/types.h"
#include "fl/stl/bit_cast.h"
#include "fl/stl/noexcept.h"
#include "fl/stl/static_assert.h"

Include dependency graph for json.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Classes
struct	fl::detail::is_fl_fixed_point< T, typename >
struct	fl::detail::is_fl_fixed_point< T, decltype(static_cast< void >(T::INT_BITS), static_cast< void >(T::FRAC_BITS), static_cast< void >(fl::declval< const T & >().raw()), static_cast< void >(T::from_raw(fl::declval< const T & >().raw())), void())>
class	fl::json

Namespaces
namespace	fl
	Base definition for an LED controller.
namespace	fl::detail
	Compile-time linker keep-alive hook for a single fl::Bus.

Functions
template<typename FP>
float	fl::detail::fixed_point_to_float (FP value) FL_NO_EXCEPT
bool	fl::detail::fixed_raw_from_ieee754_bits (u32 bits, int frac_bits, i64 *out) FL_NO_EXCEPT
u32	fl::detail::ieee754_bits_from_fixed_raw (i64 raw, int frac_bits) FL_NO_EXCEPT
u32	fl::detail::ieee754_bits_from_scaled_u64 (u32 sign, u64 magnitude, int binary_exp) FL_NO_EXCEPT
u32	fl::detail::round_shift_right_u64 (u64 value, int shift) FL_NO_EXCEPT

Variables
volatile size_t	fl::g_json_max_stack_depth
volatile size_t	fl::g_json_stack_base