api_json.h File Reference

The one conversion policy between JSON and the templated API layer. More...

#include <cmath>
#include <cstdio>
#include <cstdlib>
#include <set>
#include <string>
#include <vector>
#include "json.hpp"
#include "line/num/number.h"
#include "line/util/error.h"
#include "line/util/matrix.h"

Include dependency graph for api_json.h:

Go to the source code of this file.

Classes
struct	line::reg::NumFromDecimal< double >
struct	line::reg::NumFromDecimal< Rational >
struct	line::reg::NumFromDecimal< Real< D > >
struct	line::reg::EncodeScalar< double >
struct	line::reg::EncodeScalar< Rational >
struct	line::reg::EncodeScalar< Real< D > >
class	line::reg::Args
	Named-argument reader over the parsed JSON object. More...

Namespaces
namespace	line
namespace	line::reg

Typedefs
using	line::reg::Json = nlohmann::json

Functions
std::string	line::reg::shortest_decimal (double v)
	The shortest decimal literal that round-trips to v.
BigInt	line::reg::pow10_bigint (unsigned e)
Rational	line::reg::rational_from_decimal (const std::string &text)
	Exact value of a decimal literal, with no rounding anywhere: sign, digits, optional fraction and optional exponent are read symbolically and assembled as numerator over a power of ten.
double	line::reg::double_from_decimal (const std::string &text)
	double value of a decimal literal, including the "a/b" fraction form.
std::string	line::reg::decimal_text (const Json &j, const std::string &where)
	The decimal literal behind a JSON scalar, per the policy in the file header.
template<class T>
T	line::reg::number_from_json (const Json &j, const std::string &where)
template<class T>
Matrix< T >	line::reg::matrix_from_json (const Json &j, const std::string &where)
	A matrix from a JSON value: 2-D array as rows, 1-D array as a row vector, scalar as 1x1, empty array as the empty matrix.
template<class T>
std::vector< T >	line::reg::vector_from_json (const Json &j, const std::string &where)
	A flat numeric vector: 1-D array, or a 1-row / 1-column 2-D array.
std::vector< int >	line::reg::int_vector_from_json (const Json &j, const std::string &where)
	An integer vector; a non-integral entry is an error, never a truncation.
template<class T>
Json	line::reg::encode_scalar (const T &v)
template<class T>
Json	line::reg::encode_vector (const std::vector< T > &v)
template<class T>
Json	line::reg::encode_matrix (const Matrix< T > &m)
Json	line::reg::encode_ints (const std::vector< int > &v)
template<class T>
Json	line::reg::encode_matrices (const std::vector< Matrix< T > > &v)
	A list of matrices, the shape the MMAP/BMAP families return as {D0,D1,...}.
template<class T>
Json	line::reg::encode_vectors (const std::vector< std::vector< T > > &v)
	A list of vectors, the shape a per-class or per-segment result returns.
Json	line::reg::encode_count (std::size_t n)
	A count.

Detailed Description

The one conversion policy between JSON and the templated API layer.

Every host boundary that carries API arguments and results as JSON goes through this header: the –api path of the CLI today, a pybind11 or MEX gateway later. Two gateways that each invent their own number conversion will disagree the first time a caller writes 0.6, so the policy is stated once, here, and both sides share it.

ARGUMENTS. The object's keys are the MATLAB parameter names verbatim ({"L": [[0.6,0.4]], "N": [2,1], "Z": [1,0.5]}). A 2-D array is a matrix, row-major with the outer index the row; a 1-D array is a row vector; a bare number is a 1x1 scalar. An unrecognised key is an error, never ignored: a misspelt argument that silently takes its default is a wrong answer.

NUMBERS. A JSON number is interpreted as the SHORTEST DECIMAL LITERAL that round-trips to it, and that decimal is what the arithmetic sees. So 0.6 becomes the rational 3/5 in exact arithmetic, not the dyadic 5404319552844595/9007199254740992 that double-to-rational conversion would give. This is the only reading under which "exact" means what a caller writing 0.6 intends, and it is deterministic because the shortest round-tripping decimal of a double is unique. A caller who wants a value that has no short decimal form passes a STRING: "1/3" and "0.3333" are both accepted, and the string is taken literally at every arithmetic.

RESULTS. A value of the algorithm's number type T encodes as double -> the bare JSON number exact -> {"double": <approx>, "num": "`<decimal>`", "den": "`<decimal>`"} real:<D> -> {"double": <approx>, "dec": "`<decimal string>`"} Exact numerators and denominators overflow every integer type, so they cross as decimal strings; the host rebuilds them with sym(num)/sym(den) or fractions.Fraction. A value that is a C++ double in the algorithm itself regardless of T – lG is the only one in the port – always encodes as a bare JSON number, because there is no exact value to report: lG is computed exponent-safely as log(num) - log(den) and is finite where G is not representable at all. Never exponentiate it back.

Definition in file api_json.h.