Container compatibility

Catalyst containers extend familiar C++23 container interfaces with convenience methods, checked operations, and a consistent exception policy. Use .std() when an API requires the underlying standard type. This page describes the available interfaces and the differences to account for when adapting C++ code. See the SDK reference for individual methods.

Implemented APIs

Catalyst type	Standard counterpart	Supported facilities
CVector, CDeque, CList	vector, deque, list	Aliases, allocator constructors, constrained iterator/range APIs, correct insertion/emplacement/removal returns, move-only elements, deduction guides, and ADL helpers. Vector also supports constexpr operations and the bool-specific API.
CMap, CMultimap, CSet	map, multimap, set	Allocator and range construction, node handles, cross-policy merges, transparent lookup/erase/extract, insertion overloads, comparisons, deduction, and ADL helpers.
CHashMap, CHashSet	unordered_map, unordered_set	Allocator/bucket/hash constructor variants, ranges, transparent operations, node insertion and merges, deduction guides, and ADL helpers.
CFlatMap	flat_map	Separate key/value sequences, sorted-input and range APIs, transparent access/insertion, extraction/replacement, deduction guides, and ADL helpers.
CFlatSet	flat_set	Standard flat-set storage and reference access, allocator/container/range/sorted-input construction, transparent insertion/lookup, extraction/replacement, comparisons, deduction, and ADL helpers.
CArray	array	Checked initialization, move-only elements, constexpr operations, correct swap, tuple access, deduction, and structural template arguments. Explicit constructors remain necessary for the exception policy.
CArrayBuf	span	Construction and rebinding assignment, mutable elements through a const view, static extents, constexpr subviews, reverse/const iterators, and borrowed-range/view support.
cstr	string	Allocator/substring constructors, string-view conversion and overloads, range modifiers, comparison/search/modifier overloads, constexpr operations, concatenation, stream helpers, and guarded resize_and_overwrite.

Name clashes and compatible overloads

Name	Existing Catalyst meaning	Standard comparison
CVectorSet::erase(const T&)	Removes a matching value and returns void.	set::erase(key) returns the number removed. A different return type alone cannot form another overload.
CVectorSet::insert(const T&)	Returns {end(), false} for a duplicate.	set::insert(value) returns {existingIterator, false}. This is a behavioral clash for the same call.
CSVector::erase(uint32_t)	Erases by numeric index and returns void.	vector::erase takes iterators and returns the next iterator. The existing index overload must retain its meaning if iterator overloads are added.
CPVector::size()	Static, returns int.	array::size() is a nonstatic const member returning size_type. These zero-argument member forms cannot coexist as overloads.
CVector::insert(index, value) and erase(index); CDeque::insert(index, value)	Accept a numeric position.	Standard sequence insertion/erasure takes an iterator. The iterator overloads already coexist with these conveniences; this is an overload overlap, not a blocking clash.
CFlatSet::replace(oldKey, newKey)	Replaces one key and returns whether the old key existed.	flat_set::replace(container) replaces all storage. Both overloads coexist; argument lists distinguish them.

CFlatMap::keys() follows the standard reference-returning contract, and the copying convenience is keysCopy(). CFlatSet::std() returns a live standard flat-set reference and its default container_type is std::vector.

Set iterators and first() protect keys against mutation. Container operations translate failures from allocation, elements, comparators, and other user code as described in the exception policy below.

CFlatMap accepts the standard key/mapped container template arguments and continues accepting the old fourth-argument allocator. Legacy instantiations retain the same underlying std::flat_map type. keys() now returns the standard storage reference; the copying convenience is named keysCopy(). The convenience merge supports differing policies and move-only mapped values; it requires copyable keys because flat maps have no node handles.

Flat-container erase_if runs in linear time with exactly one predicate call per original element. It supports move-only values and keeps the container valid when predicates or moves throw. If nothing is removed, existing elements remain in place.

The specialized CSVector, CVectorSet, and CPVector also translate failures in their existing element, comparison, conversion, serialization, and stream operations. Fixed and packed vectors report capacity failures with CLengthError; fixed-vector indexing uses COutOfRangeError. Oversized packed-vector initializer lists are checked before writing, and partial construction initializes the omitted elements to zero.

Standard-type boundaries and remaining differences

For standard-container templates and qualified standard helpers, pass the underlying member explicitly. For example:

mc::CVector<int> values{1, 2, 3};
void consume(std::vector<int>&);
consume(values.std());

// ADL helpers keep the Catalyst exception boundary.
using mc::erase_if;
erase_if(values, [](int value){ return value == 2; });

// Wrap a qualified standard operation when its exceptions need translation.
mc::cContainerCall([&]{ std::erase_if(values.std(), predicate); });

No arbitrary function overloads were added to namespace std. Permitted trait specializations support array tuple access, allocator awareness, vector-bool/string hashing, and span range integration. Use .std() with qualified std::get, std::apply, std::getline, and standard templates whose deduction requires the concrete standard type.

CFlatSet migration

CFlatSet now stores C++23 std::flat_set directly. The selected Xcode libc++ provides this facility. The third template argument still accepts an allocator or a compatible sequence container; the default backing sequence is std::vector. .std() and the implicit reference conversions expose the live standard container. stdCopy() creates an independent copy and follows the backing sequence's standard copy-allocator selection.

Rebuild C++ consumers when upgrading from the Boost-backed implementation: the member type and comparator location change. The standard interface does not provide container() or get_allocator(). Use iteration for observation, or std::move(set).extract() to take ownership of the backing sequence and access its allocator. replace() adopts a sorted, unique sequence. Allocator-taking constructors remain available. Serialized values are unchanged.

Remaining differences

Three representation or policy differences remain explicit:

• CArray initialization: it is nonaggregate so constructors can translate element failures. The std::array member is public to support structural template arguments, with its type and location unchanged. Excess braced initializer-list elements are rejected safely with CLengthError at runtime, whereas std::array rejects them during compilation. Nonthrowing special members retain trivial copying when the elements permit it.
• CArrayBuf representation: .std() returns a standard span by value, preserving the wrapper's pointer and length members. Use a named span for an API requiring a standard span lvalue reference. Static extents also retain these two fields. The existing view() const convenience continues to expose const elements.
• Specialized types: C++23 has no exact counterpart for the bounded CSVector, arithmetic CPVector, uniqueness-oriented CVectorSet, or serialization-oriented CBuffer. They are not advertised as replacements for std::vector or std::array. cstr targets std::string, not arbitrary basic_string character/traits/allocator combinations. Its pre-existing nonstandard unescapeUTF8() declaration remains unimplemented.

Catalyst does not provide counterparts for forward_list, multiset, unordered_multiset, unordered_multimap, flat_multimap, flat_multiset, or the standard container adapters. Standard adapters can use compatible Catalyst storage, for example std::stack<int, mc::CVector<int>>.

Exception policy

COutOfRangeError, CLengthError, CAllocationError, and CExternalError retain translated causes through cause(), a std::exception_ptr. An existing CError is rethrown with its dynamic type intact. Unknown exceptions from user code are translated too. CAllocationError::what() returns a fixed message without allocating string storage; its inherited str() is empty. Errors raised directly for checked bounds can have an empty cause.

Translation covers exceptions escaping wrapper operations. Explicit argument construction, initializer-list element construction, direct iterator or element operations, calls on a reference returned by .std(), and violations of the underlying nonthrowing contracts are outside that boundary. Wrap the whole expression with cContainerCall when those operations also require translation. The helper preserves return references and move-only values.

cstr::resize_and_overwrite catches callback failures inside the standard callback, restores a valid empty string, then translates the exception outside the standard call. Invalid callback lengths produce CLengthError. Error diagnostics use the underlying string directly, avoiding recursive error construction if the configured diagnostic stream fails.