The forms engine's encoders and decoders: a field's draft text to its exact wire literal, a wire value back to the draft a control shows, exact unit conversion, and Choice option rows. More...

#include <algorithm>
#include <array>
#include <chrono>
#include <compare>
#include <cstddef>
#include <cstdint>
#include <expected>
#include <optional>
#include <string>
#include <string_view>
#include <utility>
#include <vector>
#include "../../render/i18n.hpp"
#include "../../render/locale_format.hpp"
#include "../../ui/value.hpp"
#include "../../util/datetime.hpp"
#include "../../util/rational.hpp"
#include "detail/text.hpp"
#include "field_model.hpp"
#include "rules.hpp"

Classes
struct	morph::forms::FieldError
	Why a draft does not encode: a stable code and the message shown beside the field. More...
struct	morph::forms::WireValue
	One field's encoded value. More...
struct	morph::forms::ValueContext
	The session options a value conversion reads. More...

Typedefs
using	morph::forms::Encoding = std::optional<std::expected<WireValue, FieldError>>
	A draft's encoding: std::nullopt when blank, else the value or why it does not encode.

Functions
FieldError	morph::forms::fieldError (std::string_view code, ValueContext const &context)
	The error for `code`, its message resolved through `context's` translations.
Encoding	morph::forms::encodeScalar (FieldSpec const &spec, std::string_view draft, std::size_t unit, ValueContext const &context)
	Encodes one scalar field's draft (every kind but Object and ObjectArray).
std::string	morph::forms::decodeScalar (FieldSpec const &spec, detail::engine::Json const &value, ValueContext const &context)
	The draft a control shows for the wire value `value` — the inverse of encodeScalar, so encoding the result re-encodes `value` (numbers in the display locale, without grouping; instants in the display zone).
std::optional< std::string >	morph::forms::convertDraft (std::string_view draft, UnitOption const &from, UnitOption const &target, render::NumericLocale const &locale)
	Converts a draft from one unit to another exactly, rounding half away from zero to the target unit's decimals.
std::vector< ChoiceOption >	morph::forms::parseOptions (std::string_view reply, ChoiceSpec const &spec)
	The options an options action's reply carries: the reply itself when it is an array, else its first array-valued member; rows without the value member are skipped.
std::string	morph::forms::defaultPlaceholder (FieldSpec const &spec)
	The placeholder a control shows when the schema declares none.

Detailed Description

The forms engine's encoders and decoders: a field's draft text to its exact wire literal, a wire value back to the draft a control shows, exact unit conversion, and Choice option rows.

Specified in docs/spec/forms/engine.md, "Values and exactness".

Definition in file values.hpp.

Typedef Documentation

◆ Encoding

using morph::forms::Encoding = std::optional<std::expected<WireValue, FieldError>>

A draft's encoding: std::nullopt when blank, else the value or why it does not encode.

Definition at line 65 of file values.hpp.

Function Documentation

◆ fieldError()

FieldError morph::forms::fieldError	(	std::string_view	code,
		ValueContext const &	context )

inlinenodiscard

The error for code, its message resolved through context's translations.

Parameters

code	A FieldError::code.
context	The session's value context.

Returns: The error.

Definition at line 83 of file values.hpp.

◆ encodeScalar()

Encoding morph::forms::encodeScalar	(	FieldSpec const &	spec,
		std::string_view	draft,
		std::size_t	unit,
		ValueContext const &	context )

inlinenodiscard

Encodes one scalar field's draft (every kind but Object and ObjectArray).

The draft is trimmed first. Blank is std::nullopt — except a required Boolean, which encodes false: an unchecked box is an answer, and a required box always shows one.

Parameters

spec	The field.
draft	What the user typed, or what a control holds (an option's valueJson, true/false).
unit	For a Decimal or Quantity, the index into spec.units the draft is typed in.
context	The locale, display zone and translations.

Returns: The encoding.

Definition at line 347 of file values.hpp.

◆ decodeScalar()

std::string morph::forms::decodeScalar	(	FieldSpec const &	spec,
		detail::engine::Json const &	value,
		ValueContext const &	context )

inlinenodiscard

The draft a control shows for the wire value value — the inverse of encodeScalar, so encoding the result re-encodes value (numbers in the display locale, without grouping; instants in the display zone).

Parameters

spec	The field.
value	The wire value (JSON null and a mismatched shape decode to blank).
context	The locale and display zone.

Returns: The draft text.

Definition at line 439 of file values.hpp.

◆ convertDraft()

std::optional< std::string > morph::forms::convertDraft	(	std::string_view	draft,
		UnitOption const &	from,
		UnitOption const &	target,
		render::NumericLocale const &	locale )

inlinenodiscard

Converts a draft from one unit to another exactly, rounding half away from zero to the target unit's decimals.

Parameters

draft	The draft, in `locale's` spelling.
from	The unit it is typed in.
target	The unit to convert to.
locale	The display locale (the result is grouped in it).

Returns: The converted draft, or std::nullopt when the draft is not a number or the conversion leaves the exact range.

Definition at line 535 of file values.hpp.

◆ parseOptions()

std::vector< ChoiceOption > morph::forms::parseOptions	(	std::string_view	reply,
		ChoiceSpec const &	spec )

inlinenodiscard

The options an options action's reply carries: the reply itself when it is an array, else its first array-valued member; rows without the value member are skipped.

Parameters

reply	The reply JSON.
spec	Which row members are value and label.

Returns: The options; empty for a reply that is not JSON or has no rows.

Definition at line 558 of file values.hpp.

◆ defaultPlaceholder()

std::string morph::forms::defaultPlaceholder ( FieldSpec const & spec )

inlinenodiscard

The placeholder a control shows when the schema declares none.

Parameters

spec	The field.

Returns: x-placeholder when declared; else 0.000… for a Decimal or Quantity (at least one place), 0 for an integer, the declared precision for a Number, a hint for an Array, and empty otherwise.

Definition at line 594 of file values.hpp.

Classes

Typedefs

Functions

Detailed Description

Typedef Documentation

◆ Encoding

Function Documentation

◆ fieldError()

◆ encodeScalar()

◆ decodeScalar()

◆ convertDraft()

◆ parseOptions()

◆ defaultPlaceholder()