containers.hpp File Reference

The reference-semantic container table: which STL containers welder can bind opaquely* (by reference) rather than by the frameworks' copy casters. More...

#include <array>
#include <map>
#include <meta>
#include <unordered_map>
#include <vector>

Include dependency graph for containers.hpp:

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

Go to the source code of this file.

Classes
struct	welder::detail::container_spec
	One row of the reference-container table: a container template paired with the opaque binder kind it uses. More...

Namespaces
namespace	welder
namespace	welder::detail
	The stored forms of the annotation vocabulary.

Concepts
concept	welder::rod_binds_containers
	Does rod B implement the optional bind_container hook (i.e.

Enumerations
enum class	welder::container_kind : unsigned char { welder::sequence , welder::map }
	Which opaque binder a reference-bound container uses. More...

Functions
consteval std::array< container_spec, 3 >	welder::detail::reference_containers ()
	The containers welder binds opaquely — exactly those the frameworks' bind_vector / bind_map support.
consteval bool	welder::is_reference_container (std::meta::info type)
	Is type one of the containers welder can bind by reference (opaquely)?
consteval container_kind	welder::container_kind_of (std::meta::info type)
	The opaque-binder kind of type.
consteval bool	welder::container_is_contiguous (std::meta::info type)
	Is type a contiguous sequence — one whose elements live in a single block reachable via .data(), so a scalar element type can be exposed zero-copy through the buffer protocol / an nb::ndarray view?

Detailed Description

The reference-semantic container table: which STL containers welder can bind opaquely* (by reference) rather than by the frameworks' copy casters.

By default a std::vector<T> / std::map<K,V> crosses into Python through pybind11's <pybind11/stl.h> (nanobind's <nanobind/stl/…>) as a copy — reading it snapshots to a list/dict, and mutating that snapshot never reaches the C++ object. For a dynamic container that is rarely wanted. Both frameworks offer the alternative — an opaque, reference-semantic binding via bind_vector / bind_map (mutation writes through, append/slicing, and — for scalar elements — a zero-copy numpy view) — which the user opts into by welding a namespace-scope alias** to the specialization (the same mechanism that welds any template instantiation), paired with the framework's opaque declaration (PYBIND11_MAKE_OPAQUE / NB_MAKE_OPAQUE, exposed as WELDER_OPAQUE by each Python rod).

This header records which containers have a ready opaque binder in the frameworks — the scope is deliberately exactly that set: bind_vector covers std::vector (pybind11's bind_vector needs .reserve()/.data(), so the segmented std::deque does not qualify); bind_map covers std::map / std::unordered_map. std::deque, std::list, the sets and the multi* containers have no cross-framework opaque binder and are not listed. The carriage consults welder::is_reference_container at the alias-dispatch site to route a welded container alias to the rod's bind_container hook instead of the generic class sweep; the rod reads welder::container_kind_of to pick bind_vector vs bind_map.

Like bindable.hpp this is a reflection-layer header (it names the container templates, so it is not std-include-free — that constraint is only on the vocabulary headers lang.hpp / annotations.hpp).

Definition in file containers.hpp.