parcel::UnionCell< Ts > Class Template Reference

Closed-set polymorphic cell — exactly one of Ts at runtime. More...

#include <union.h>

Inheritance diagram for parcel::UnionCell< Ts >:

Collaboration diagram for parcel::UnionCell< Ts >:

Public Types
using	variant_storage_t = std::variant< typename Ts::storage_t... >
	Storage variant — one slot per alternative.
template<std::size_t I>
using	nth_wrapper_t = std::tuple_element_t< I, std::tuple< Ts... > >
	Wrapper type at the I -th alternative slot.

Public Member Functions
std::size_t	index () const noexcept
	Index of the currently active alternative.
template<std::size_t I>
auto &	get ()
	Access the value at alternative I (mutable).
template<std::size_t I>
auto const &	get () const
	Access the value at alternative I (const).
template<typename S >
S &	get ()
	Access the value held in storage type S (mutable).
template<typename S >
S const &	get () const
	Access the value held in storage type S (const).
std::string_view	active_kind () const
	Kind id of the currently active alternative.
std::string	to_string () const override
	Render the cell's value as a compact human-readable string.
json_t	to_json () const override
	Default JSON serialization for cells with JSON-convertible storage.
cell_t	clone () const override
	Deep-copy this cell.
std::partial_ordering	compare (ICell const &other) const override
	Three-way comparison: kind, then active alternative index, then the active alternative's wrapper-level compare.
template<typename F >
decltype(auto)	visit (F &&f)
	Visit the active alternative with f, called as f(storage).
template<typename F >
decltype(auto)	visit (F &&f) const
	Const overload of visit.
template<std::size_t I>
auto *	get_if () noexcept
	Returns a pointer to the active alternative if it lives at slot I, else nullptr — never throws.
template<std::size_t I>
auto const *	get_if () const noexcept
	Const overload of get_if<I>.
template<typename S >
S *	get_if () noexcept
	Returns a pointer to the active alternative if its storage is S, else nullptr — never throws.
template<typename S >
S const *	get_if () const noexcept
	Const overload of get_if<S>.
template<std::size_t I>
bool	holds_alternative () const noexcept
	true if the active alternative lives at slot I.
template<typename S >
bool	holds () const noexcept
	true if the active alternative's storage type is S.
template<typename U > requires std::assignable_from<Storage&, U&&>
Derived &	operator= (U &&v)
	Assign to the storage from v.
Public Member Functions inherited from parcel::BaseCell< UnionCell< Ts... >, std::variant< Ts::storage_t... > >
	explicit (false) BaseCell(U &&v)
	Construct by forwarding into the storage (v becomes Storage::value).
UnionCell< Ts... > &	operator= (U &&v)
	Assign to the storage from v.
std::variant< Ts::storage_t... > &	get ()
	Mutable access to the held storage.
std::variant< Ts::storage_t... > const &	get () const
	Read-only access to the held storage.
void	inject_display_info (json_t &j) const
	Copy this cell's display info (if any) into the JSON object under "d".
Public Member Functions inherited from parcel::ICell
virtual std::string	to_formatted_string () const
	Render the cell as a multi-line, indented string.
virtual std::size_t	hash_value () const noexcept
	Equality-consistent hash that mirrors compare's display-info-insensitivity.
cell_t	with_display_info (DisplayInfo m) const
	Return a deep copy with the entire display info block replaced.
cell_t	with_name (std::string v) const
	Return a deep copy with name set to v.
cell_t	with_description (std::string v) const
	Return a deep copy with description set to v.
cell_t	with_icon (comms::Icon icon) const
	Return a deep copy with icon set to the typed icon.
cell_t	with_icon (std::string const &v) const
	Return a deep copy with icon parsed from an Iconify set:name string (e.g.
cell_t	with_color (comms::Color color) const
	Return a deep copy with color set to the typed color.
cell_t	with_color (std::string const &v) const
	Return a deep copy with color parsed from a color string (hex like "#ffcc00", a CSS-functional form, or a CSS color name).

Static Public Member Functions
static cell_t	from_json (json_t const &j, ParcelRegistry const &reg)
	Deserialize a UnionCell<Ts...> from JSON.
static cell_type_descriptor_t	descriptor ()
	Cached descriptor for this union.
Static Public Member Functions inherited from parcel::BaseCell< UnionCell< Ts... >, std::variant< Ts::storage_t... > >
static std::shared_ptr< UnionCell< Ts... > >	of (Args &&... args)
	Construct a shared_ptr<Derived> forwarding the arguments.
static std::unique_ptr< UnionCell< Ts... > >	unique (Args &&... args)
	Construct a unique_ptr<Derived> forwarding the arguments.
static void	absorb_display_info (json_t const &j, Out &out)
	Read "d" (if present) from a JSON object and assign it onto a cell.
static cell_t	from_json_strict (json_t const &j)
	Strict shorthand for the recurring cell_from_json + make_shared.

Static Public Attributes
static constexpr std::size_t	alternative_count = sizeof...(Ts)
	Number of alternatives.
static constexpr std::array< std::string_view, sizeof...(Ts)>	alternatives {Ts::kind_id...}
	Kind id of each alternative in template order.
static constexpr std::string_view	kind_id {kind_id_buf.data(), kind_id_buf.size()}
	Wire kind id of this union ("u:" + alternatives joined by ",").
Static Public Attributes inherited from parcel::ICell
static constexpr std::string_view	KEY_KIND = "k"
	JSON key for the kind id ("k").
static constexpr std::string_view	KEY_VALUE = "v"
	JSON key for the value payload ("v").
static constexpr std::string_view	KEY_DESCRIPTION = "d"
	JSON key for the optional display info block ("d").

Additional Inherited Members
Public Attributes inherited from parcel::BaseCell< UnionCell< Ts... >, std::variant< Ts::storage_t... > >
std::variant< Ts::storage_t... >	value
	Held value of the cell.
Static Protected Member Functions inherited from parcel::BaseCell< UnionCell< Ts... >, std::variant< Ts::storage_t... > >
static T	cell_from_json (const json_t &j, const std::string_view expected_kind)
	Validate a wrapped {"k","v"} JSON object and extract its "v" as T.
Protected Attributes inherited from parcel::BaseCell< UnionCell< Ts... >, std::variant< Ts::storage_t... > >
std::optional< DisplayInfo >	display_info_
	Optional display info; omitted from JSON when empty.

Detailed Description

template<CellLike... Ts>
class parcel::UnionCell< Ts >

Closed-set polymorphic cell — exactly one of Ts at runtime.

Wire shape (example for UnionCell<I32Cell, StringCell>):

{"k": "u:i32,string", "v": {"k": "i32", "v": 42}}

The active alternative is recovered from the inner v.k. Storage is std::variant<typename Ts::storage_t...> so values are raw, not wrapped cells. Each unique parameter pack registers under its own kind:

UnionCell<I32Cell, StringCell>::kind_id            == "u:i32,string";
UnionCell<I32Cell, TypedListCell<I32Cell>>::kind_id == "u:i32,l:i32";

Template Parameters

Ts	One or more CellLike alternative types (at least one).

See also

UnionCellTypeDescriptor

Member Function Documentation

clone()

template<CellLike... Ts>

cell_t parcel::UnionCell< Ts >::clone ( ) const

inlineoverridevirtual

Deep-copy this cell.

Returns

A new cell_t whose state is independent of the original.

Reimplemented from parcel::BaseCell< UnionCell< Ts... >, std::variant< Ts::storage_t... > >.

compare()

template<CellLike... Ts>

std::partial_ordering parcel::UnionCell< Ts >::compare ( ICell const &  other ) const

inlineoverridevirtual

Three-way comparison: kind, then active alternative index, then the active alternative's wrapper-level compare.

Routes through the alternative's Wrapper::compare instead of the underlying std::variant::operator<=>, so storage types that lack three-way comparison still work as long as their cell type does.

Reimplemented from parcel::BaseCell< UnionCell< Ts... >, std::variant< Ts::storage_t... > >.

descriptor()

template<CellLike... Ts>

static cell_type_descriptor_t parcel::UnionCell< Ts >::descriptor ( )

inlinestatic

Cached descriptor for this union.

Returns

Shared UnionCellTypeDescriptor<Ts...> instance.

from_json()

template<CellLike... Ts>

static cell_t parcel::UnionCell< Ts >::from_json ( json_t const &  j, ParcelRegistry const &  reg  )

inlinestatic

Deserialize a UnionCell<Ts...> from JSON.

The active alternative is recovered from the inner v.k; that kind must equal one of Ts::kind_id.

Parameters

j	Input JSON object — must match {"k": kind_id, "v": {…}}.
reg	Registry passed through to the active alternative's from_json.

Returns

Newly built cell handle.

Exceptions

std::runtime_error

on shape or kind mismatch, or if the inner kind does not match any alternative.

get() [1/4]

template<CellLike... Ts>

template<std::size_t I>

auto & parcel::UnionCell< Ts >::get ( )

inline

Access the value at alternative I (mutable).

Template Parameters

I	Alternative index.

Returns

Reference to the held value at slot I.

get() [2/4]

template<CellLike... Ts>

template<typename S >

S & parcel::UnionCell< Ts >::get ( )

inline

Access the value held in storage type S (mutable).

Template Parameters

S	One of the storage types in the variant.

Returns

Reference to the held S value.

get() [3/4]

template<CellLike... Ts>

template<std::size_t I>

auto const & parcel::UnionCell< Ts >::get ( ) const

inline

Access the value at alternative I (const).

Template Parameters

I	Alternative index.

Returns

Const reference to the held value at slot I.

get() [4/4]

template<CellLike... Ts>

template<typename S >

S const & parcel::UnionCell< Ts >::get ( ) const

inline

Access the value held in storage type S (const).

Template Parameters

S	One of the storage types in the variant.

Returns

Const reference to the held S value.

operator=()

template<CellLike... Ts>

template<typename U >
requires std::assignable_from<Storage&, U&&>

Derived & parcel::BaseCell< Derived, Storage >::operator= ( U &&  v )

inline

Assign to the storage from v.

Template Parameters

U	Any type assignable to the storage.

Parameters

v	Replacement value.

Returns

Reference to the derived cell for chaining.

to_json()

template<CellLike... Ts>

json_t parcel::UnionCell< Ts >::to_json ( ) const

inlineoverridevirtual

Default JSON serialization for cells with JSON-convertible storage.

If Storage has a JSON adapter, emits {"k": kind_id, "v": value, optional "d": display info}. Otherwise the call throws — the derived cell must override to_json itself (ListCell, MapCell, etc.).

Returns

JSON object representation.

Exceptions

std::runtime_error

if Storage is not JSON-convertible.

Reimplemented from parcel::BaseCell< UnionCell< Ts... >, std::variant< Ts::storage_t... > >.

to_string()

template<CellLike... Ts>

std::string parcel::UnionCell< Ts >::to_string ( ) const

inlineoverridevirtual

Render the cell's value as a compact human-readable string.

Returns

String form — implementation-defined per cell type.

Implements parcel::ICell.

visit()

template<CellLike... Ts>

template<typename F >

decltype(auto) parcel::UnionCell< Ts >::visit ( F &&  f )

inline

Visit the active alternative with f, called as f(storage).

Mirrors std::visit over std::variant. The visitor sees the raw storage of the active alternative (e.g. std::int32_t for an I32Cell slot), so each overload should be written against the storage type, not the wrapper.

parcel::visit(parcel::Overload{
    [](std::int32_t i) { ... },
    [](std::string const& s) { ... },
}, my_union);

Member Data Documentation

kind_id

template<CellLike... Ts>

constexpr std::string_view parcel::UnionCell< Ts >::kind_id {kind_id_buf.data(), kind_id_buf.size()}

staticconstexpr

Wire kind id of this union ("u:" + alternatives joined by ",").

UnionCell<I32Cell, StringCell>::kind_id == "u:i32,string";

---

The documentation for this class was generated from the following file:

• include/parcel/union.h