cell.h File Reference

Core ICell interface, cell_t handle, BaseCell CRTP base, and CellLike concept. More...

#include <parcel/common.h>
#include <parcel/error.h>
#include <compare>
#include <concepts>
#include <cstddef>
#include <functional>
#include <memory>
#include <optional>
#include <stdexcept>
#include <string>
#include <string_view>
#include <type_traits>
#include <utility>
#include <variant>

Include dependency graph for cell.h:

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

Go to the source code of this file.

Classes
struct	parcel::ICell
	Polymorphic root of every parcel cell. More...
struct	parcel::BaseCell< Derived, Storage >
	CRTP base providing default to_json / clone / kind plumbing on top of a storage type. More...
struct	std::hash< parcel::ICell >
	std::hash<ICell> — equality-consistent with operator==. More...
struct	std::hash< parcel::cell_t >
	std::hash<cell_t> — null hashes to 0; otherwise routes to hash<ICell>. More...

Concepts
concept	parcel::CellLike
	Concept naming the static interface every cell type must expose.

Typedefs
using	parcel::cell_type_descriptor_t = std::shared_ptr< ICellTypeDescriptor >
	Shared handle to a runtime cell-type descriptor.
using	parcel::cell_t = std::shared_ptr< ICell >
	Shared handle to any ICell-derived value — the canonical cell pointer.

Functions
template<typename T > requires std::derived_from<T, ICell>
void	parcel::to_json (json_t &j, T const &v)
	ADL hook that lets nlohmann serialize any ICell-derived cell.
template<typename T > requires std::derived_from<T, ICell>
void	parcel::to_json (json_t &j, std::shared_ptr< T > const &v)
	ADL hook for serializing std::shared_ptr<T> of an ICell-derived type.
template<typename C > requires std::derived_from<C, ICell>
std::shared_ptr< C >	parcel::cell_cast (cell_t const &c)
	Type-safe dynamic_cast from cell_t to a concrete cell type.
template<typename C > requires std::derived_from<C, ICell>
std::shared_ptr< C >	parcel::cell_cast_or (cell_t const &c, std::shared_ptr< C > fallback)
	cell_cast that returns fallback on failure rather than throwing.
template<typename C > requires std::derived_from<C, ICell>
C::storage_t	parcel::cell_cast_value (cell_t const &c)
	Cast and unwrap to the inner storage value in one call.
template<typename C > requires std::derived_from<C, ICell>
std::optional< typename C::storage_t >	parcel::as (cell_t const &c) noexcept
	std::optional view over a cell's inner storage.
template<typename C > requires std::derived_from<C, ICell>
C::storage_t	parcel::value_or (cell_t const &c, typename C::storage_t fallback)
	Extract c's storage as C, falling back to fallback on failure.
json_t	parcel::to_json (cell_t const &c)
	Free to_json over cell_t; returns null for null handles.
std::string	parcel::to_string (cell_t const &c)
	Free to_string over cell_t; returns "<null>" for null handles.
std::string	parcel::to_string_pretty (cell_t const &c)
	Multi-line to_string over cell_t; returns "<null>" for null handles.
std::size_t	parcel::hash_cell (ICell const &c) noexcept
	Hash a cell value compatibly with operator==.

Detailed Description

Core ICell interface, cell_t handle, BaseCell CRTP base, and CellLike concept.

The ICell interface is the polymorphic root of every parcel cell. Concrete cells inherit from BaseCell<Derived, Storage> to get a ready implementation of to_json / clone / kind plumbing on top of a user-chosen storage type. The CellLike concept names the static interface (kind_id, from_json, descriptor) that registry-aware code relies on. See the README "Cell interface" section.

Function Documentation

as()

template<typename C >
requires std::derived_from<C, ICell>

std::optional< typename C::storage_t > parcel::as ( cell_t const &  c )

noexcept

std::optional view over a cell's inner storage.

Mirrors std::optional's "either present or not" shape — nullopt means either c is null or it isn't a C.

Template Parameters

C	Target cell type.

Parameters

c	Source cell handle.

Returns

optional<C::storage_t> with the value on success.

cell_cast()

template<typename C >
requires std::derived_from<C, ICell>

std::shared_ptr< C > parcel::cell_cast

(

cell_t const &

c

)

Type-safe dynamic_cast from cell_t to a concrete cell type.

Template Parameters

C	Target cell type (must satisfy CellLike).

Parameters

c	Source cell handle.

Returns

shared_ptr<C> aliasing the original ownership.

Exceptions

std::runtime_error

if c is null or not actually a C.

cell_cast_or()

template<typename C >
requires std::derived_from<C, ICell>

std::shared_ptr< C > parcel::cell_cast_or	(	cell_t const &	c,
		std::shared_ptr< C >	fallback
	)

cell_cast that returns fallback on failure rather than throwing.

Template Parameters

C	Target cell type.

Parameters

c	Source cell handle.
fallback	Returned when c is null or not a C.

Returns

Either the cast handle or fallback.

cell_cast_value()

template<typename C >
requires std::derived_from<C, ICell>

C::storage_t parcel::cell_cast_value

(

cell_t const &

c

)

Cast and unwrap to the inner storage value in one call.

Template Parameters

C	Target cell type.

Parameters

c	Source cell handle.

Returns

Copy of C::storage_t held by the cast cell.

Exceptions

std::runtime_error

if c is null or not a C.

hash_cell()

std::size_t parcel::hash_cell ( ICell const &  c )

inlinenoexcept

Hash a cell value compatibly with operator==.

Free helper that mirrors the std::hash<ICell> specialization for places where a function-call shape is more readable.

to_json() [1/2]

template<typename T >
requires std::derived_from<T, ICell>

void parcel::to_json ( json_t &  j, std::shared_ptr< T > const &  v  )

inline

ADL hook for serializing std::shared_ptr<T> of an ICell-derived type.

Needed for heterogeneous containers whose storage element is cell_t.

Template Parameters

T	Concrete cell type derived from ICell.

Parameters

j	Output JSON node.
v	Shared pointer to serialize. Null becomes JSON null.

to_json() [2/2]

template<typename T >
requires std::derived_from<T, ICell>

void parcel::to_json ( json_t &  j, T const &  v  )

inline

ADL hook that lets nlohmann serialize any ICell-derived cell.

Enables json_t j = some_cell; and lets containers of ICell subtypes (e.g. std::vector<T> in TypedListCell) be serialized without bespoke per-type adl_serializers.

Template Parameters

T	Concrete cell type derived from ICell.

Parameters

j	Output JSON node.
v	Cell to serialize.

value_or()

template<typename C >
requires std::derived_from<C, ICell>

C::storage_t parcel::value_or	(	cell_t const &	c,
		typename C::storage_t	fallback
	)

Extract c's storage as C, falling back to fallback on failure.

Template Parameters

C	Target cell type.

Parameters

c	Source cell handle.
fallback	Returned when c is null or not a C.

Returns

Storage value or fallback.