The rows a table engine reads, and the services it is given. More...

#include <algorithm>
#include <array>
#include <chrono>
#include <compare>
#include <cstddef>
#include <cstdint>
#include <expected>
#include <format>
#include <functional>
#include <limits>
#include <map>
#include <memory>
#include <morph/core/callback_scope.hpp>
#include <morph/util/datetime.hpp>
#include <morph/util/quantity.hpp>
#include <morph/util/rational.hpp>
#include <optional>
#include <span>
#include <string>
#include <string_view>
#include <unordered_map>
#include <utility>
#include <variant>
#include <vector>

Classes
struct	morph::table::QuantityCell
	A quantity in its own unit, with the factor that converts it to the column's canonical unit. More...
struct	morph::table::ColumnInfo
	A column's identity and kind. More...
struct	morph::table::TableError
	The error every fallible table call returns. More...
class	morph::table::TextCollator
	Orders and matches text. The renderer injects the toolkit's collator for the user's locale; CodePointCollator is the default. More...
class	morph::table::CodePointCollator
	The default collator: code-point order, with ASCII and Latin-1 letters case-folded. It does not fold accents. More...
class	morph::table::DateParser
	Parses text to dates and date-times for Date and DateTime columns that hold text, and for filter values on those columns. More...
class	morph::table::IsoDateParser
	The default date parser: ISO 8601 only, whatever the format. More...
class	morph::table::ProgressSink
	Receives progress of a long sort or filter, on the owner thread. More...
struct	morph::table::Services
	The services an engine sorts and filters with. A null member is replaced by its default. More...
class	morph::table::ColumnSink
	Receives a run of one column's cells. More...
class	morph::table::RowSnapshot
	An immutable view of a table's rows at one moment. More...
class	morph::table::TableSnapshot
	A RowSnapshot that stores rows in shared, immutable chunks. More...
struct	morph::table::RowChange
	One change notification. More...
class	morph::table::ChangeListener
	Receives a DataSource's change notifications, on the owner thread. More...
class	morph::table::DataSource
	The rows of a table, as the engine reads them. More...
class	morph::table::detail::Listeners
	A source's listeners, notified so that a listener may unsubscribe itself or another, or destroy the source, from inside a notification. More...
class	morph::table::RowPatcher
	Replaces a row by key; what a committed cell edit patches. More...
class	morph::table::VectorSource
	A DataSource over rows held in memory, for tests, servers and sources that cannot share their own storage. More...

Typedefs
using	morph::table::RowId = std::variant<std::int64_t, std::string>
	A row's identity: the table's key, stable across reloads.
using	morph::table::Cell = std::variant<std::monostate, std::int64_t, math::Rational, double, std::string, bool, QuantityCell>
	One cell as a data source hands it out.
using	morph::table::CellComparator = std::function<std::strong_ordering(Cell const&, Cell const&)>
	Orders two cells of a Custom column. Called from the worker, so it must be safe to call concurrently.

Enumerations
enum class	morph::table::ColumnKind : std::uint8_t { Integer , Decimal , Quantity , Number , Text , Date , DateTime , Bool , Key , Custom }
	What a column holds, which decides how its keys are built and compared. More...
enum class	morph::table::TableErrorCode : std::uint8_t { UnknownColumn , UnsupportedOperator , InvalidValue , InvalidSpec , LimitExceeded , ColumnNotReadable , Unavailable , ServiceFailed }
	What went wrong in a fallible table call. More...
enum class	morph::table::ChangeKind : std::uint8_t { Updated , Inserted , Removed , Reset }
	How rows changed. More...

Functions
std::expected< math::Rational, TableError >	morph::table::parseDecimal (std::string_view text)
	Parses exact decimal text ("-12.50") into a Rational.
std::string	morph::table::displayText (Cell const &cell)
	The text a cell shows when it has to be ordered or matched as text.

Detailed Description

The rows a table engine reads, and the services it is given.

A DataSource publishes a table's columns, an immutable RowSnapshot of its rows, and notifications when rows change. The engine reads cells only through a snapshot, never through the source, so a snapshot can be handed to a worker thread while the owner keeps changing the source.

The injected services (TextCollator, DateParser, ProgressSink, named comparators) are the only locale- and toolkit-dependent parts of sorting and filtering; each has a deterministic default here.

See docs/spec/table/engine.md.

Definition in file data_source.hpp.

Typedef Documentation

◆ RowId

using morph::table::RowId = std::variant<std::int64_t, std::string>

A row's identity: the table's key, stable across reloads.

Definition at line 63 of file data_source.hpp.

◆ Cell

using morph::table::Cell = std::variant<std::monostate, std::int64_t, math::Rational, double, std::string, bool, QuantityCell>

One cell as a data source hands it out.

std::monostate is an empty cell. A std::string in a non-text column is parsed for the column's kind when its key is built; text that does not parse is an invalid cell.

Definition at line 83 of file data_source.hpp.

◆ CellComparator

using morph::table::CellComparator = std::function<std::strong_ordering(Cell const&, Cell const&)>

Orders two cells of a Custom column. Called from the worker, so it must be safe to call concurrently.

Definition at line 392 of file data_source.hpp.

Enumeration Type Documentation

◆ ColumnKind

enum class morph::table::ColumnKind : std::uint8_t

strong

What a column holds, which decides how its keys are built and compared.

Enumerator
Integer	int64, compared numerically.
Decimal	An exact Rational.
Quantity	An exact Rational in the column's canonical unit.
Number	A double; the only kind that holds one.
Text	Text, ordered and matched through the TextCollator.
Date	Days since 1970-01-01.
DateTime	UTC seconds since 1970-01-01T00:00:00Z.
Bool	false before true.
Key	An int64 key, compared numerically.
Custom	Ordered by a named comparator from Services::comparators.

Definition at line 49 of file data_source.hpp.

◆ TableErrorCode

enum class morph::table::TableErrorCode : std::uint8_t

strong

What went wrong in a fallible table call.

Enumerator
UnknownColumn	A sort or filter names a column the table does not have.
UnsupportedOperator	A filter operator the column's kind does not define.
InvalidValue	A filter value that does not parse for its column's kind.
InvalidSpec	A filter entry with no operator or more than one.
LimitExceeded	A TableQuery over one of the server's bounds.
ColumnNotReadable	A sort or filter on a column the principal may not read.
Unavailable	An operation the table's mode does not offer.
ServiceFailed	An injected service (collator, date parser, comparator) threw.

Definition at line 103 of file data_source.hpp.

◆ ChangeKind

enum class morph::table::ChangeKind : std::uint8_t

strong

How rows changed.

Enumerator
Updated	rows changed their cells; row indices are unchanged.
Inserted	rows are the new rows' indices in the new snapshot.
Removed	rows are the removed rows' indices in the old snapshot.
Reset	Everything may have changed, the columns included.

Definition at line 700 of file data_source.hpp.

Function Documentation

◆ parseDecimal()

std::expected< math::Rational, TableError > morph::table::parseDecimal ( std::string_view text )

inlinenodiscard

Parses exact decimal text ("-12.50") into a Rational.

Accepts an optional sign, digits, and an optional fraction of at most 18 digits; nothing else (no exponent, no grouping, no surrounding space). The result carries as many decimal places as the text had.

Parameters

text	The decimal text.

Returns: The exact value, or InvalidValue when the text is not a decimal or does not fit an int64 numerator.

Definition at line 132 of file data_source.hpp.

◆ displayText()

std::string morph::table::displayText ( Cell const & cell )

inlinenodiscard

The text a cell shows when it has to be ordered or matched as text.

Parameters

cell The cell.

Returns: Its text: the string itself, a number in decimal form (a decimal to its own places, "12.5"), true or false, or empty for an empty cell.

Definition at line 196 of file data_source.hpp.

Classes

Typedefs

Enumerations

Functions

Detailed Description

Typedef Documentation

◆ RowId

◆ Cell

◆ CellComparator

Enumeration Type Documentation

◆ ColumnKind

◆ TableErrorCode

◆ ChangeKind

Function Documentation

◆ parseDecimal()

◆ displayText()