Compile-time deduction of collectable containers — determining whether and how a container C can accept elements of a range R through incremental, value-preserving insertion. More...

#include <cstdint>
#include "jh/conceptual/closable_container.h"
#include "jh/conceptual/tuple_like.h"

Namespaces
namespace	jh::concepts
	Behavioral concept namespace of the JH Toolkit.

Concepts
concept	jh::concepts::collectable_container_for
	Concept verifying that a container `C` can collect elements from a range `R` via incremental insertion.

Detailed Description

Compile-time deduction of collectable containers — determining whether and how a container C can accept elements of a range R through incremental, value-preserving insertion.

Copyright: Copyright 2025 JeongHan-Bae <mastropseudo@gmail.com>
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.

Full license: GitHub

Author: JeongHan-Bae <mastropseudo@gmail.com>

This header defines the collectable container model, which forms the foundation of jh::ranges::collect. It classifies all containers that can materialize data from a range using well-defined insertion semantics, possibly including tuple-like structural unpacking.

Purpose

A container is collectable from a range when it can be incrementally populated with the elements of that range, without requiring any external constructor arguments. This mechanism powers jh::ranges::collect, which performs data materialization and normalization — converting a lazy or proxy-based pipeline into a concrete, value-semantic container.

In contrast, jh::ranges::to performs container adaptation: it builds the final target container, possibly with allocators, hashers, or custom constructor parameters. Therefore:

collect has no extra arguments; it only materializes and normalizes data.
to may take constructor arguments and performs the final adaptation step.
The combination collect + to forms a complete materialization → adaptation pipeline.

Classification

The collectable_status enumeration defines all supported behaviors:

closable — the container is directly constructible via jh::ranges::to.
emplace_back_direct — appends elements using emplace_back().
push_back_direct — appends using push_back().
emplace_direct — inserts at logical end using emplace().
insert_direct — inserts at logical end using insert().
emplace_back_unpack — performs tuple-like structural unpacking into emplace_back().
emplace_unpack — performs tuple-like structural unpacking into emplace().

Design rationale

Aligned semantics: The four direct forms (emplace_back, push_back, emplace, insert) exactly correspond to the element-wise insertion semantics defined for std::ranges::to, ensuring identical behavior in the incremental case.
Tuple-aware extension: The unpacking forms extend the capability beyond the standard proposal: collect can destructure tuple-like elements (with std::tuple_size, std::tuple_element, and ADL get()) and reconstruct real value objects directly in-place.
Non-destructive semantics: No operation may move-from or invalidate the source range; insertion is performed purely by reference traversal.

Unpack constraints

Unpacking requires the element type to be an explicitly tuple-like type, providing all of:

std::tuple_size<T>
std::tuple_element<I, T>
ADL-visible get<I>(T)

Arbitrary aggregates or user-defined proxies are not implicitly unpacked, ensuring deterministic behavior and preserving the element's semantic identity.

Relationship with other modules

jh::ranges::collect — uses this classification to materialize non-closable ranges into stable containers.
jh::ranges::to — skips this classification entirely, performing direct container construction when closable.
jh::concepts::closable_container_for — represents the complementary "construction-level" concept for to.

Semantic guarantee

The collectable_container_for concept ensures that collect can safely and deterministically construct a container C from a range R via incremental insertion, matching the observable semantics of std::ranges::to while supporting richer tuple-unpacking behaviors.

Note: collect is a materializer, not an adaptor: it normalizes and realizes data into value semantics, but never applies construction arguments. Configuration belongs exclusively to to, allowing collect + to to form a clean, composable, two-stage pipeline.

See also: jh::ranges::collect; jh::ranges::to; jh::concepts::closable_container_for

Version

1.3.x

Date

Namespaces