Polymorphic root of every parcel cell. More...

#include <cell.h>

Inheritance diagram for parcel::ICell:

[legend]

Public Member Functions
virtual std::string_view	kind () const =0
	Wire-stable kind identifier for this cell.

virtual std::optional< DisplayInfo > const &	overridden_display_info () const =0
	Read-only access to this cell's optional display info.

virtual json_t	to_json () const =0
	Serialize this cell to its canonical JSON representation.

virtual std::string	to_string () const =0
	Render the cell's value as a compact human-readable string.

virtual std::string	to_formatted_string () const
	Render the cell as a multi-line, indented string.

virtual cell_t	clone () const =0
	Deep-copy this cell.

virtual std::partial_ordering	compare (ICell const &other) const =0
	Three-way compare against another cell.

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 Attributes
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"`).

Protected Member Functions
virtual void	set_display_info (std::optional< DisplayInfo > m)=0
	Replace this cell's display info in place.

Friends
bool	operator== (ICell const &a, ICell const &b)
	Equality through `compare`; ignores display info.

std::partial_ordering	operator<=> (ICell const &a, ICell const &b)
	Three-way comparison through `compare`; ignores display info.

Detailed Description

Polymorphic root of every parcel cell.

Wire shape: {"k": <kind>, "v": <value>, "d": <display info>} where the "d" block is omitted when no display info is set. Every concrete cell exposes its kind via kind(), can serialize through to_json(), render via to_string(), and clone deeply via clone().

Display info is read-only on the public surface: callers retrieve it via overridden_display_info() and only the immutable with_* builders may change it.

See also: BaseCell — CRTP base providing default implementations.; CellLike — concept naming the static side of a cell type.

Member Function Documentation

◆ clone()

virtual cell_t parcel::ICell::clone ( ) const

pure virtual

Deep-copy this cell.

Returns: A new cell_t whose state is independent of the original.

◆ compare()

virtual std::partial_ordering parcel::ICell::compare ( ICell const & other ) const

pure virtual

Three-way compare against another cell.

Compares by kind id first (lexicographic on the string view); within the same kind, compares the held value. Display info is intentionally ignored — two cells with the same kind/value but different DisplayInfo are equivalent under this relation.

Parameters

other Cell to compare with.

Returns: std::partial_ordering — unordered whenever the storage type only supports equality (or contains incomparable values such as floating-point NaN).

◆ hash_value()

virtual std::size_t parcel::ICell::hash_value ( ) const

inlinevirtualnoexcept

Equality-consistent hash that mirrors compare's display-info-insensitivity.

Default implementation hashes the kind id and the JSON dump of "v", which works for every cell whose to_json() payload omits nested DisplayInfo. Heterogeneous container cells (ListCell, MapCell, HashMapCell) override this to recurse through hash_value() on their children — that is what keeps the hash display-info-insensitive when children carry display info of their own.

Reimplemented in parcel::ListCell, parcel::MapCell, and parcel::HashMapCell.

◆ kind()

virtual std::string_view parcel::ICell::kind ( ) const

pure virtual

Wire-stable kind identifier for this cell.

Returns: The same value as the static kind_id on the concrete type.

◆ overridden_display_info()

virtual std::optional< DisplayInfo > const & parcel::ICell::overridden_display_info ( ) const

pure virtual

Read-only access to this cell's optional display info.

Returns: Reference to the held optional; empty when no display info is set.

◆ set_display_info()

virtual void parcel::ICell::set_display_info ( std::optional< DisplayInfo > m )

protectedpure virtual

Replace this cell's display info in place.

Used by with_* builders on freshly cloned receivers and by JSON deserializers; no other public path mutates display info.

Parameters

m	New display info value (may be empty to clear).

◆ to_formatted_string()

virtual std::string parcel::ICell::to_formatted_string ( ) const

inlinevirtual

Render the cell as a multi-line, indented string.

Returns: Defaults to to_string(); concrete cells may override.

◆ to_json()

virtual json_t parcel::ICell::to_json ( ) const

pure virtual

Serialize this cell to its canonical JSON representation.

Returns: JSON object of shape {"k", "v", optional "d"}.

◆ to_string()

virtual std::string parcel::ICell::to_string ( ) const

pure virtual

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

Returns: String form — implementation-defined per cell type.

Implemented in parcel::ColorCell, parcel::IconCell, parcel::DisplayInfoCell, parcel::FlagCell, parcel::FlagSetCell, parcel::SemVerCell, parcel::VersionConstraintCell, parcel::OriginCell, parcel::SystemTimePointCell, parcel::UnixMillisCell, parcel::DurationMsCell, parcel::YmdCell, parcel::PathCell, parcel::TypedListCell< T >, parcel::ListCell, parcel::TypedMapCell< T >, parcel::MapCell, parcel::PrimitiveCell< T >, parcel::StructCell< Derived, Payload, StructId >, parcel::SelfStructCell< Derived >, parcel::UnionCell< Ts >, parcel::TypedHashMapCell< T >, and parcel::HashMapCell.

◆ with_color() [1/2]

cell_t parcel::ICell::with_color ( comms::Color color ) const

inline

Return a deep copy with color set to the typed color.

Parameters

color New color.

Returns: Fresh cell_t; this cell is unmodified.

◆ with_color() [2/2]

cell_t parcel::ICell::with_color ( std::string const & v ) const

inline

Return a deep copy with color parsed from a color string (hex like "#ffcc00", a CSS-functional form, or a CSS color name).

Parameters

v	Color string accepted by `comms::Color::parse`.

Returns: Fresh cell_t; this cell is unmodified.

Exceptions

InvalidJsonException if v does not parse to a color.

◆ with_description()

cell_t parcel::ICell::with_description ( std::string v ) const

inline

Return a deep copy with description set to v.

Parameters

v	New description.

Returns: Fresh cell_t; this cell is unmodified.

◆ with_display_info()

cell_t parcel::ICell::with_display_info ( DisplayInfo m ) const

inline

Return a deep copy with the entire display info block replaced.

Parameters

m	New display info to attach.

Returns: Fresh cell_t; this cell is unmodified.

◆ with_icon() [1/2]

cell_t parcel::ICell::with_icon ( comms::Icon icon ) const

inline

Return a deep copy with icon set to the typed icon.

Parameters

icon New icon.

Returns: Fresh cell_t; this cell is unmodified.

◆ with_icon() [2/2]

cell_t parcel::ICell::with_icon ( std::string const & v ) const

inline

Return a deep copy with icon parsed from an Iconify set:name string (e.g.

"mdi:account").

Parameters

v	Iconify `set:name` identifier.

Returns: Fresh cell_t; this cell is unmodified.

Exceptions

std::invalid_argument if v is not a valid set:name icon.

◆ with_name()

cell_t parcel::ICell::with_name ( std::string v ) const

inline

Return a deep copy with name set to v.

Parameters

v New name.

Returns: Fresh cell_t; this cell is unmodified.

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

include/parcel/cell.h

Public Member Functions

Static Public Attributes

Protected Member Functions

Friends

Detailed Description

Member Function Documentation

◆ clone()

◆ compare()

◆ hash_value()

◆ kind()

◆ overridden_display_info()

◆ set_display_info()

◆ to_formatted_string()

◆ to_json()

◆ to_string()

◆ with_color() [1/2]

◆ with_color() [2/2]

◆ with_description()

◆ with_display_info()

◆ with_icon() [1/2]

◆ with_icon() [2/2]

◆ with_name()