--- title: "std::rebind - Generalized Type Rebinding for Containers and Uniform-Element Types" document: P3971R1 date: 2026-02-20 audience: LEWG Library Evolution reply-to: - "Daniel Towner" paper-type: proposal --- --- ## Revision History R0 - Initial revision ## Motivation Modern C++ provides powerful facilities for generic programming, but lacks a uniform way to change the element type of containers and container-like types. Consider a simple requirement: convert a container of `float` values to `double` for higher precision computation. For `std::vector`, this is straightforward using constructor-based conversion: ``` std::vector widen(const std::vector& data) { return std::vector(data.begin(), data.end()); } ``` However, making this work for `std::array` requires completely different code: ``` template std::array widen(const std::array& data) { std::array result; std::copy(data.begin(), data.end(), result.begin()); return result; } ``` For `std::complex`, yet another approach is needed: ``` std::complex widen(const std::complex& data) { return std::complex(data); } ``` Each type requires specialised knowledge of its conversion mechanisms. Attempting to write a single generic function fails: ``` template auto widen_to_double(const Container& data) { using T = typename Container::value_type; // Some container types may not even have this member. // How do we create Container from Container? // - vector: range constructor // - array: manual copy with known size // - complex: direct construction // - user types: ??? // No uniform solution exists } ``` ### Precedent in std::simd The `std::simd` proposal [P1928R15] recognised this problem and introduced `rebind_t` as a type trait to convert the type `basic_simd` to `basic_simd`. This works well for `simd`, but the mechanism is not generalised to other types. The `simd` proposal provides both a type trait for compile-time type computation and suitable conversion constructors which make using that type to change the underlying type easy. No other current container can do the same. Recent discussion of simd casting utilities [P3445R0] raised questions about whether such facilities should be generalised beyond simd to support other types like containers and units. This proposal explores that generalisation. ### Proposed Solution We propose two complementary facilities: 1. `rebind_t` - A type trait that computes the result type of rebinding the structure from elements of type `T` to use elements of type `U` `std::rebind(obj)` - A customisation point object that performs the actual conversion These work together to enable uniform generic code: ``` template auto widen_to_double(const Container& data) { using T = typename Container:: value_type; return std::rebind(data); } // Works uniformly for all supported types: std::vector v = {1.0f, 2.0f, 3.0f}; auto vd = widen_to_double(v); // vector std::array a = {1.0f, 2.0f, 3.0f}; auto ad = widen_to_double(a); // array ``` The facilities are extensible via ADL, allowing user-defined types to participate in generic algorithms using the same interface. ## Supported Types ### Specification Principle `std::rebind` is provided for types where rebinding the element type produces a meaningful corresponding type. The presence of a `value_type` member typedef is a strong indicator that a type has a uniform element type suitable for rebinding, but is neither necessary nor sufficient: - Types like `std::complex` are clearly rebindable despite lacking `value_type`. Types like `std::stack` have `value_type` but cannot be rebound without additional complexity (rebinding the underlying container). Associative containers have `value_type` but require also rebinding their comparator. The determination of whether a type is rebindable depends on whether the rebinding operation is well-defined and produces a semantically equivalent structure with a different element type. Standard library support is provided for: 1. **Sequence containers**: Types with `value_type` representing a sequence of uniform elements **Scalar types with uniform components**: Types like `std::complex` that represent a single value composed of uniform components **User-defined types**: Via ADL customisation for types where rebinding is appropriate ### Standard Library Support The following table shows the standard library types for which `std::rebind` and `rebind_t` would be defined: | Input type Has `value_type`? Result of rebinding to `double` `std::array` Yes `std::array` `std::vector` Yes `std::vector>` `std::deque` Yes `std::deque>` `std::list` Yes `std::list>` `std::forward_list` Yes `std::forward_list>` `std::complex` No (special case) `std::complex` | Has `value_type`? Result of rebinding to `double` `std::array` Yes `std::array` `std::vector` Yes `std::vector>` `std::deque` Yes `std::deque>` `std::list` Yes `std::list>` `std::forward_list` Yes `std::forward_list>` `std::complex` No (special case) `std::complex` | Result of rebinding to `double` `std::array` Yes `std::array` `std::vector` Yes `std::vector>` `std::deque` Yes `std::deque>` `std::list` Yes `std::list>` `std::forward_list` Yes `std::forward_list>` `std::complex` No (special case) `std::complex` | `std::array` Yes `std::array` `std::vector` Yes `std::vector>` `std::deque` Yes `std::deque>` `std::list` Yes `std::list>` `std::forward_list` Yes `std::forward_list>` `std::complex` No (special case) `std::complex` | Yes `std::array` `std::vector` Yes `std::vector>` `std::deque` Yes `std::deque>` `std::list` Yes `std::list>` `std::forward_list` Yes `std::forward_list>` `std::complex` No (special case) `std::complex` | `std::array` `std::vector` Yes `std::vector>` `std::deque` Yes `std::deque>` `std::list` Yes `std::list>` `std::forward_list` Yes `std::forward_list>` `std::complex` No (special case) `std::complex` | `std::vector` Yes `std::vector>` `std::deque` Yes `std::deque>` `std::list` Yes `std::list>` `std::forward_list` Yes `std::forward_list>` `std::complex` No (special case) `std::complex` | Yes `std::vector>` `std::deque` Yes `std::deque>` `std::list` Yes `std::list>` `std::forward_list` Yes `std::forward_list>` `std::complex` No (special case) `std::complex` | `std::vector>` `std::deque` Yes `std::deque>` `std::list` Yes `std::list>` `std::forward_list` Yes `std::forward_list>` `std::complex` No (special case) `std::complex` | `std::deque` Yes `std::deque>` `std::list` Yes `std::list>` `std::forward_list` Yes `std::forward_list>` `std::complex` No (special case) `std::complex` | Yes `std::deque>` `std::list` Yes `std::list>` `std::forward_list` Yes `std::forward_list>` `std::complex` No (special case) `std::complex` | `std::deque>` `std::list` Yes `std::list>` `std::forward_list` Yes `std::forward_list>` `std::complex` No (special case) `std::complex` | `std::list` Yes `std::list>` `std::forward_list` Yes `std::forward_list>` `std::complex` No (special case) `std::complex` | Yes `std::list>` `std::forward_list` Yes `std::forward_list>` `std::complex` No (special case) `std::complex` | `std::list>` `std::forward_list` Yes `std::forward_list>` `std::complex` No (special case) `std::complex` | `std::forward_list` Yes `std::forward_list>` `std::complex` No (special case) `std::complex` | Yes `std::forward_list>` `std::complex` No (special case) `std::complex` | `std::forward_list>` `std::complex` No (special case) `std::complex` | `std::complex` No (special case) `std::complex` | No (special case) `std::complex` | `std::complex` | | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | | `std::array` Yes `std::array` `std::vector` Yes `std::vector>` `std::deque` Yes `std::deque>` `std::list` Yes `std::list>` `std::forward_list` Yes `std::forward_list>` `std::complex` No (special case) `std::complex` | Yes `std::array` `std::vector` Yes `std::vector>` `std::deque` Yes `std::deque>` `std::list` Yes `std::list>` `std::forward_list` Yes `std::forward_list>` `std::complex` No (special case) `std::complex` | `std::array` `std::vector` Yes `std::vector>` `std::deque` Yes `std::deque>` `std::list` Yes `std::list>` `std::forward_list` Yes `std::forward_list>` `std::complex` No (special case) `std::complex` | `std::vector` Yes `std::vector>` `std::deque` Yes `std::deque>` `std::list` Yes `std::list>` `std::forward_list` Yes `std::forward_list>` `std::complex` No (special case) `std::complex` | Yes `std::vector>` `std::deque` Yes `std::deque>` `std::list` Yes `std::list>` `std::forward_list` Yes `std::forward_list>` `std::complex` No (special case) `std::complex` | `std::vector>` `std::deque` Yes `std::deque>` `std::list` Yes `std::list>` `std::forward_list` Yes `std::forward_list>` `std::complex` No (special case) `std::complex` | `std::deque` Yes `std::deque>` `std::list` Yes `std::list>` `std::forward_list` Yes `std::forward_list>` `std::complex` No (special case) `std::complex` | Yes `std::deque>` `std::list` Yes `std::list>` `std::forward_list` Yes `std::forward_list>` `std::complex` No (special case) `std::complex` | `std::deque>` `std::list` Yes `std::list>` `std::forward_list` Yes `std::forward_list>` `std::complex` No (special case) `std::complex` | `std::list` Yes `std::list>` `std::forward_list` Yes `std::forward_list>` `std::complex` No (special case) `std::complex` | Yes `std::list>` `std::forward_list` Yes `std::forward_list>` `std::complex` No (special case) `std::complex` | `std::list>` `std::forward_list` Yes `std::forward_list>` `std::complex` No (special case) `std::complex` | `std::forward_list` Yes `std::forward_list>` `std::complex` No (special case) `std::complex` | Yes `std::forward_list>` `std::complex` No (special case) `std::complex` | `std::forward_list>` `std::complex` No (special case) `std::complex` | `std::complex` No (special case) `std::complex` | No (special case) `std::complex` | `std::complex` | | | | | `std::vector` Yes `std::vector>` `std::deque` Yes `std::deque>` `std::list` Yes `std::list>` `std::forward_list` Yes `std::forward_list>` `std::complex` No (special case) `std::complex` | Yes `std::vector>` `std::deque` Yes `std::deque>` `std::list` Yes `std::list>` `std::forward_list` Yes `std::forward_list>` `std::complex` No (special case) `std::complex` | `std::vector>` `std::deque` Yes `std::deque>` `std::list` Yes `std::list>` `std::forward_list` Yes `std::forward_list>` `std::complex` No (special case) `std::complex` | `std::deque` Yes `std::deque>` `std::list` Yes `std::list>` `std::forward_list` Yes `std::forward_list>` `std::complex` No (special case) `std::complex` | Yes `std::deque>` `std::list` Yes `std::list>` `std::forward_list` Yes `std::forward_list>` `std::complex` No (special case) `std::complex` | `std::deque>` `std::list` Yes `std::list>` `std::forward_list` Yes `std::forward_list>` `std::complex` No (special case) `std::complex` | `std::list` Yes `std::list>` `std::forward_list` Yes `std::forward_list>` `std::complex` No (special case) `std::complex` | Yes `std::list>` `std::forward_list` Yes `std::forward_list>` `std::complex` No (special case) `std::complex` | `std::list>` `std::forward_list` Yes `std::forward_list>` `std::complex` No (special case) `std::complex` | `std::forward_list` Yes `std::forward_list>` `std::complex` No (special case) `std::complex` | Yes `std::forward_list>` `std::complex` No (special case) `std::complex` | `std::forward_list>` `std::complex` No (special case) `std::complex` | `std::complex` No (special case) `std::complex` | No (special case) `std::complex` | `std::complex` | | | | | | | | `std::deque` Yes `std::deque>` `std::list` Yes `std::list>` `std::forward_list` Yes `std::forward_list>` `std::complex` No (special case) `std::complex` | Yes `std::deque>` `std::list` Yes `std::list>` `std::forward_list` Yes `std::forward_list>` `std::complex` No (special case) `std::complex` | `std::deque>` `std::list` Yes `std::list>` `std::forward_list` Yes `std::forward_list>` `std::complex` No (special case) `std::complex` | `std::list` Yes `std::list>` `std::forward_list` Yes `std::forward_list>` `std::complex` No (special case) `std::complex` | Yes `std::list>` `std::forward_list` Yes `std::forward_list>` `std::complex