feature: stateful visitors for BFS

[Becheler]

Important

New algorithms and API additions need a design issue first. Such a PR is not reviewed until an issue has settled the API and frozen the scope. PRs whose scope grows under review go stale. See How To Contribute an Algorithm.

Motivation

Extends #614 to BFS

What this PR does

Make the breadth-first family accept a visitor wrapped in std::ref, so state held in
plain data members survives the traversal instead of landing on the algorithm's copy.

Reuses the existing boost::graph::detail visitor helpers, converts the BFS doc examples
and the FAQ's by-value answer to show it, and covers it with a positional test in test/bfs.cpp.

Before submitting

• I searched for an existing PR or issue covering the same change.
• This PR targets the develop branch.
• My contribution is licensed under the Boost Software License 1.0.

Kind of change

Tick exactly one. Each kind is reviewed differently, so mixing them in one PR makes the diff difficult to review (why).

• Reformat (layout only, no token added or removed)
• Refactor (no observable behavior change)
• Behavior change (observable to users of the library)
• No code change (documentation, build, CI, or tooling)

Change category

• Bug fix
• New algorithm or API addition
• Deprecation or removal
• Performance
• Tests
• Documentation
• Build, CI, or tooling
• Other (specify below)

[cppalliance-bot]

An automated preview of the documentation is available at https://634.graph.prtest3.cppalliance.org/libs/graph/doc/html/index.html

If more commits are pushed to the pull request, the docs will rebuild at the same URL.

2026-10-08 12:34:33 UTC

[github-actions]

Boost dependency footprint vs develop (auto-generated).
PR run 37777453397 vs develop run 37771790744 (34bdd0adda).

Header-inclusion weights (graph files pulling each direct dependency in):

No header-inclusion-weight changes.

Transitive Boost modules: 47 → 47 (0)

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[github-actions]

Compiler-warning counts vs develop (auto-generated).
PR run 37777453077 vs develop run 37771790517 (34bdd0adda).

Job	Baseline	After	Delta
macos (clang, 14)	392	392	0
macos (clang, 17)	391	391	0
macos (clang, 20)	391	391	0
ubuntu (clang-19, 14)	392	392	0
ubuntu (clang-19, 17)	391	391	0
ubuntu (clang-19, 20)	391	391	0
ubuntu (clang-19, 23)	391	391	0
ubuntu (gcc-14, 14)	345	345	0
ubuntu (gcc-14, 17)	341	341	0
ubuntu (gcc-14, 20)	341	341	0
ubuntu (gcc-14, 23)	341	341	0
windows_msvc_14_3 (msvc-14.3)	931	931	0