qb-linq brings Enumerable-style method chains to modern C++: where, select, order_by, group_by, join, set algebra, percentiles / variance, zip / zip_fold, scan, chunk, materializers, and fused terminals — without std::ranges, without a runtime library. Views are lazy; work happens when you iterate or call a terminal.

• C++17 — GCC, Clang, MSVC
• CMake 3.22+ for the bundled config / presets
• Linux · macOS · Windows (verified in CI)

find_package(qb-linq 1.3 CONFIG REQUIRED)
target_link_libraries(your_target PRIVATE qb::linq)
target_compile_features(your_target PRIVATE cxx_std_17)

add_subdirectory(third_party/qb-linq)
target_link_libraries(your_target PRIVATE qb::linq)

#include <iostream>
#include <vector>
#include <qb/linq.h>

int main() {
    std::vector<int> v{1, 2, 3, 4, 5, 6};
    int s = qb::linq::from(v)
                .where([](int x) { return x % 2 == 0; })
                .select([](int x) { return x * x; })
                .sum();
    std::cout << s << '\n';   // 4 + 16 + 36 = 56
}

Include only <qb/linq.h>; other headers stay under qb/linq/.
Version macros (QB_LINQ_VERSION_STRING, qb::linq::version, …) come from qb/linq/version.h, generated by CMake — see docs/VERSIONING.md.

For a drop-in file (no qb/ include tree, no CMake-generated version.h on disk), add -I /path/to/qb-linq/single_header and:

#include <linq.h>

Same namespace qb::linq and API as <qb/linq.h>; the version is embedded from project(VERSION …) when the file is regenerated.

Regenerate after editing headers under include/qb/linq/ or bumping the project version:

• CMake: cmake --build <build> --target qb_linq_single_header
• Scripts (repo root — use whichever fits your machine):
  • python3 scripts/amalgamate_single_header.py — Python 3 (also python … on Windows if that is your launcher).
  • sh scripts/amalgamate_single_header.sh — POSIX sh; calls python3 internally.
  • pwsh -File scripts/amalgamate_single_header.ps1 — PowerShell (typical on Windows).

The qb_linq_single_header_test target (see tests/) keeps this file honest in CI.

1. enumerable<Handle> — fluent façade; each lazy step returns a new enumerable.
2. query_range_algorithms (CRTP) — algorithms use derived().begin() / end().
3. Terminals — sum, to_vector, first, order_by, group_by, … trigger real work (many materialize via shared_ptr).
4. Caveats — select_many = tuple per row (not C# flatten); except/intersect follow .NET distinct set semantics and need hashable value_type; zip/concat inner pipelines may need copy-assignable functors (+[](){}); to_vector() / materialize() return an enumerable wrapping materialized_range (not a raw std::vector); scan iterators must not outlive the scan_view. Full notes in qb/linq.h.

All operations below live in namespace qb::linq. Method names use snake_case.
Unless noted, methods are const and return a new enumerable for lazy ops, or a value / materialized range for terminals.

Coverage: the table above lists every forwarding entry point on enumerable plus all documented free factories in enumerable.h. Internal iterator adaptors (select_iterator, …) live in iterators.h; combinators (concat_view, zip_view, …) in detail/extra_views.h.

std::vector<int> data{3, 1, 4, 1, 5, 9, 2, 6};
auto v = qb::linq::from(data)
             .where([](int x) { return x > 2; })
             .select([](int x) { return x * x; })
             .take(3)
             .to_vector();

std::vector<int> xs{1, 2, 3, 4, 5, 6};
auto n = qb::linq::from(xs).count_if([](int x) { return x % 2 == 0; });
auto s = qb::linq::from(xs).sum_if([](int x) { return x % 2 == 0; });

struct Row { int dept; int id; };
std::vector<Row> rows{{2, 10}, {1, 5}, {1, 3}, {2, 7}};
auto sorted = qb::linq::from(rows)
                  .order_by(qb::linq::asc([](Row const& r) { return r.dept; }),
                            qb::linq::desc([](Row const& r) { return r.id; }))
                  .to_vector();

struct Person { int id; std::string name; };
struct Score { int person_id; int points; };
std::vector<Person> people{{1, "Ann"}, {2, "Bob"}};
std::vector<Score> scores{{1, 10}, {1, 11}, {2, 20}};

auto joined = qb::linq::from(people).join(scores,
    [](Person const& p) { return p.id; },
    [](Score const& s) { return s.person_id; },
    [](Person const& p, Score const& s) {
        return p.name + ":" + std::to_string(s.points);
    });

auto grouped = qb::linq::from(people).group_join(scores,
    [](Person const& p) { return p.id; },
    [](Score const& s) { return s.person_id; });

std::vector<int> a{1, 2, 3, 4}, b{3, 4, 5};
auto u = qb::linq::from(a).union_with(b).to_vector();
std::vector<double> xs{1, 2, 3, 4, 5};
double m = qb::linq::from(xs).median();
double p = qb::linq::from(xs).percentile(75.0);

std::vector<int> a{1, 2, 3}, b{10, 20, 30};
for (auto const& pr : qb::linq::from(a).zip(b)) { /* pr.first, pr.second */ }

for (int x : qb::linq::from(a).scan(0, [](int acc, int v) { return acc + v; })) { }

for (auto const& pr : qb::linq::from(std::string("abc")).enumerate()) { }

auto xs = qb::linq::iota(0, 10);
auto one = qb::linq::once(42);
auto pat = qb::linq::repeat(std::string("x"), 3);
auto none = qb::linq::empty<int>();

std::vector<int> data{1, 2, 3};
qb::linq::from(data).each([](int& x) { x *= 2; });

Full detail (presets, install, FetchContent versions, flags): docs/BUILDING.md.

cmake -B build -DCMAKE_BUILD_TYPE=Release \
  -DQB_BUILD_TESTS=ON -DQB_BUILD_BENCHMARKS=ON
cmake --build build --parallel
ctest --test-dir build --output-on-failure
./build/benchmarks/qb_linq_benchmark

Presets: cmake --preset dev · cmake --build build/dev · ctest --preset dev
(release, ci, docs — see CMakePresets.json.)

The benchmarks/ suite (Google Benchmark) compares many qb-linq paths against small hand-written loops in the same translation unit. Enable it with QB_BUILD_BENCHMARKS=ON (see above), then run the qb_linq_benchmark executable. All timings are machine-, compiler-, and flag-specific; use them for local regression checks, not as absolute promises. For scan iterator copies vs a straight range-for, and select with an empty class functor vs a large callable object, see benchmarks/bench_scan_contract.cpp.

What to expect

• Simple terminals on a plain range (e.g. sum on from(vector)) are usually close to a naive loop: the hot path is still a forward iteration with little extra logic.
• Lazy stacks (select, where, concat, stride, scan, …) add real work: wrapped iterators, stored callables, and sometimes downgraded iterator categories versus raw pointers or index loops. A noticeable gap versus a single fused loop is normal, especially on MSVC, where heavy template layering does not always optimize away completely.
• scan stores the fold functor in the scan_view; iterators hold a non-owning pointer to it (no shared_ptr / atomic refcount). Treat it like a standard range: do not keep scan_iterators past the lifetime of the view that produced them.
• select / where / take_while store callables with empty-base optimization when F is an empty class type (C++17), shrinking iterator objects for stateless function objects. On MSVC, iterator adaptors use __declspec(empty_bases) so an empty F does not double the iterator size under multiple inheritance.
• Materializers such as to_vector() build a materialized_range backed by std::shared_ptr. You pay for that ownership model, not just element copying—expect a higher cost than reserve + push_back into a bare std::vector with no shared handle.
• Views that allocate per step (e.g. chunk, which fills a std::vector per chunk) are inherently more expensive than one pass over scalars.
• Some benchmarks compare different algorithms (e.g. one-pass Welford variance vs a two-pass sum-of-squares formulation). A gap there reflects numerics and work per element, not a broken sum.

Takeaway: qb-linq prioritizes a LINQ-like API, lazy composition, and safe materialization (shared ownership where needed). It is not a guarantee of matching hand-tuned assembly on every pipeline. For hot spots, measure with qb_linq_benchmark (or your own harness) on your target toolchain.

single_header/linq.h   # amalgamated drop-in (regenerate: target qb_linq_single_header)
scripts/               # amalgamate_single_header.{py,ps1,sh}
include/qb/linq.h
include/qb/linq/
  enumerable.h
  query.h
  iterators.h
  detail/
    query_range.h
    extra_views.h
    group_by.h
    order.h
    type_traits.h
tests/                 # GoogleTest — includes randomized reference checks (`linq_property_fuzz_test.cpp`) and edge-case suites (`linq_robustness_parity_test.cpp`, …); see `tests/CMakeLists.txt`
benchmarks/            # Google Benchmark (see benchmarks/CMakeLists.txt)
cmake/                 # qb-linq-config.cmake.in, version.h.in → generated qb/linq/version.h
docs/                  # README (hub), BUILDING, VERSIONING, LLM_CONTEXT, Doxyfile.in, doxygen/
.github/               # CI, issue/PR templates, copilot-instructions

• AGENTS.md — checklist for coding agents (file map, verification, pointers to build + implementation docs).
• docs/BUILDING.md — CMake targets, options, presets (same facts as CMakeLists.txt).
• docs/LLM_CONTEXT.md — dense implementation reference for LLMs.
• Cursor: .cursor/rules/ · skill .cursor/skills/qb-linq-development/

• Docs hub (index): docs/README.md
• Module docs + caveats: qb/linq.h — Doxygen groups qb (framework) and linq (qb/linq; see ingroup tags in the headers).
• Build / install: docs/BUILDING.md
• Versioning (SemVer, macros, CMake): docs/VERSIONING.md
• LLM / agent (architecture, file map): docs/LLM_CONTEXT.md
• Changelog: CHANGELOG.md
• Contributing: CONTRIBUTING.md
• Code of Conduct: CODE_OF_CONDUCT.md
• Security: SECURITY.md
• HTML (Doxygen): QB_LINQ_BUILD_DOCS=ON → target qb_linq_docs (output under the build tree, see docs/BUILDING.md)

MIT License — Copyright (c) 2026 ISNDEV

See CONTRIBUTING.md and CODE_OF_CONDUCT.md for expectations. Short version: behaviour changes need tests in tests/; keep benchmark builds green when you touch hot paths. Build help: docs/BUILDING.md. Agents: AGENTS.md, docs/LLM_CONTEXT.md.