FastLED Core Library (`src/fl`)

This document introduces the FastLED core library housed under src/fl/, first by listing its headers, then by progressively expanding into an educational guide for two audiences:

First‑time FastLED users who want to understand what lives below FastLED.h and how to use common utilities
Experienced C++ developers exploring the fl:: API as a cross‑platform, STL‑free foundation

FastLED avoids direct dependencies on the C++ standard library in embedded contexts and offers its own STL‑like building blocks in the fl:: namespace.

Overview and Quick Start
Header Groups (5 major areas)
Comprehensive Module Breakdown
Guidance for New Users
Guidance for C++ Developers

Overview and Quick Start

What is `fl::`?

fl:: is FastLED’s cross‑platform foundation layer. It provides containers, algorithms, memory utilities, math, graphics primitives, async/concurrency, I/O, and platform shims designed to work consistently across embedded targets and host builds. It replaces common std:: facilities with equivalents tailored for embedded constraints and portability.

Key properties:

Cross‑platform, embedded‑friendly primitives
Minimal dynamic allocation where possible; clear ownership semantics
Consistent naming and behavior across compilers/toolchains
Prefer composable, header‑driven utilities

Goals and design constraints

Avoid fragile dependencies on std:: in embedded builds; prefer fl:: types
Emphasize deterministic behavior and low overhead
Provide familiar concepts (vector, span, optional, variant, function) with embedded‑aware implementations
Offer safe RAII ownership types and moveable wrappers for resource management
Keep APIs flexible by preferring non‑owning views (fl::span) as function parameters

Naming and idioms

Names live in the fl:: namespace
Prefer fl::span<T> as input parameters over owning containers
Use fl::shared_ptr<T> / fl::unique_ptr<T> instead of raw pointers
Favor explicit ownership and lifetimes; avoid manual new/delete

Getting started: common building blocks

Include the top‑level header you need, or just include FastLED.h in sketches. When writing platform‑agnostic C++ within this repo, include the specific fl/ headers you use.

Common types to reach for:

Containers and views: fl::vector<T>, fl::deque<T>, fl::span<T>, fl::slice<T>
Strings and streams: fl::string, fl::ostream, fl::sstream, fl::printf
Optionals and variants: fl::optional<T>, fl::variant<...>
Memory/ownership: fl::unique_ptr<T>, fl::shared_ptr<T>, fl::weak_ptr<T>
Functional: fl::function<Signature>, fl::function_list<Signature>
Concurrency: fl::thread, fl::mutex, fl::thread_local
Async: fl::promise<T>, fl::task
Math: fl::math, fl::sin32, fl::random, fl::gamma, fl::gradient
Graphics: fl::raster, fl::screenmap, fl::rectangular_draw_buffer, fl::downscale, fl::supersample
Color: fl::hsv, fl::hsv16, fl::colorutils
JSON: fl::Json with safe defaults and ergonomic access

Example: using containers, views, and ownership

#include "fl/vector.h"
#include "fl/span.h"
#include "fl/memory.h"   // for fl::make_unique

void process(fl::span<const int> values) {
    // Non-owning view over contiguous data
}

void example() {
    fl::vector<int> data;
    data.push_back(1);
    data.push_back(2);
    data.push_back(3);

    process(fl::span<const int>(data));

    auto ptr = fl::make_unique<int>(42);
    // Exclusive ownership; automatically freed when leaving scope
}

Example: JSON with safe default access

#include "fl/json.h"

void json_example(const fl::string& jsonStr) {
    fl::Json json = fl::Json::parse(jsonStr);
    int brightness = json["config"]["brightness"] | 128;  // default if missing
    bool enabled = json["enabled"] | false;
}