Portable parser for persistent series state payloads. More...

#include <limits.h>
#include <math.h>
#include <stdint.h>
#include <string.h>
#include "mdl_state.h"
#include "mdl_state_internal.h"
#include "ra8_attributes.h"

Include dependency graph for mdl_state_codec.c:

Data Structures
struct	mdl_state_reader_t
	Bounded reader over one exact payload extent. More...

Enumerations
enum	mdl_state_parse_t : uint16_t { k_state_max_flds = 10 , k_state_hex_base = 16 , k_state_dec_base = 10 , k_state_hex_alpha_base = 10 , k_state_decimal_digits_max = 17 , k_state_decimal_exp_max = 400 }
	Parser limits and radices. More...
enum	mdl_c_col_t : uint8_t { k_c_id = 1 , k_c_known = 2 , k_c_number = 3 , k_c_done = 4 , k_c_pages = 5 , k_c_ready = 6 , k_c_epoch = 7 , k_c_url = 8 , k_c_title = 9 , k_c_fields_v2 = 10 , k_c_v1_number = 2 , k_c_v1_done = 3 , k_c_v1_pages = 4 , k_c_v1_ready = 5 , k_c_v1_epoch = 6 , k_c_v1_url = 7 , k_c_fields_v1 = 8 }
	Field index of each column on a C (chapter) record line. More...
enum	mdl_p_col_t : uint8_t { k_p_urlhash = 1 , k_p_content = 2 , k_p_relpath = 3 , k_p_etag = 4 , k_p_lastmod = 5 , k_p_epoch = 6 , k_p_status = 7 , k_p_fields = 4 , k_p_fields_v4 = 8 }
	Field index of each column on a P (page) record line. More...

Functions
static size_t	internal_mdl_state_split_tabs (char line, char fld[], size_t max)
	Split one record in place at TAB delimiters.
static bool	internal_mdl_state_digit (char byte, int base, uint8_t *out)
	Convert one canonical lowercase ASCII digit.
static bool	internal_mdl_state_parse_u64_field (const char text, int base, uint64_t out)
	Parse one exact unsigned decimal or hexadecimal field.
static bool	internal_mdl_state_parse_i64_field (const char text, int64_t out)
	Parse one exact signed 64-bit decimal including INT64_MIN.
static bool	internal_mdl_state_parse_long_field (const char text, long out)
	Parse a target-width legacy signed long field exactly.
static bool	internal_mdl_state_parse_decimal_exp (const char *cursor, int32_t out_exp)
	Parse one bounded ASCII decimal exponent.
static bool	internal_mdl_state_scan_mantissa (const char *cursor, uint64_t out_mantissa, int32_t out_fractional, bool out_digit)
	Scan a canonical decimal mantissa: digits with at most one point.
static bool	internal_mdl_state_parse_double_field (const char text, double out)
	Parse one complete locale-free legacy decimal binary64 value.
static bool	internal_mdl_state_parse_binary64 (const char text, double out)
	Parse one exact-width canonical binary64 bit identity.
static bool	internal_mdl_state_apply_chapter_values (mdl_state_t st, char fld[], double number, bool number_known, uint64_t done, uint64_t pages, uint64_t ready, int64_t epoch, size_t url_col, const char *title)
	Apply validated common chapter fields.
static bool	internal_mdl_state_apply_chapter_v1 (mdl_state_t st, char fld[], size_t nf)
	Parse and apply one legacy v1 chapter record.
static bool	internal_mdl_state_apply_chapter_v2 (mdl_state_t st, char fld[], size_t nf)
	Parse and apply one current v2 chapter record.
static bool	internal_mdl_state_apply_chapter_v3 (mdl_state_t st, char fld[], size_t nf)
	Parse and apply one current-schema chapter record.
static bool	internal_mdl_state_apply_page (mdl_state_t st, char fld[], size_t nf, uint16_t schema_version)
	Parse and apply one page record.
static bool	internal_mdl_state_apply_kv (char dst, size_t cap, char fld[], size_t nf)
	Store one exact bounded key/value record.
static bool	internal_mdl_state_apply_metadata (mdl_state_t st, char type, char fld[], size_t nf)
	Apply one current-schema rich-metadata record.
static bool	internal_mdl_state_apply_version (char fld[], size_t nf, uint16_t schema_version)
	Accept one exact supported schema-version record.
static bool	internal_mdl_state_apply_line (mdl_state_t st, char fld[], size_t nf, uint16_t *schema_version)
	Apply one already-split state record.
static ra8_err_t	internal_mdl_state_reader_refill (mdl_state_reader_t *reader)
	Refill a payload reader without crossing its declared extent.
static ra8_err_t	internal_mdl_state_reader_byte (mdl_state_reader_t reader, uint8_t out, bool *out_eof)
	Deliver one byte from a bounded payload reader.
static ra8_err_t	internal_mdl_state_reader_line (mdl_state_reader_t reader, char line, size_t capacity, bool *out_has_line)
	Read one bounded text record.
static bool	internal_mdl_state_parse_record (mdl_state_t st, char line, uint16_t *schema_version)
	Apply one non-comment payload record.
ra8_err_t	priv_mdl_state_parse_file (mdl_storage_t storage, fw_fs_file_t file, uint64_t offset, uint64_t length, uint16_t max_schema_version, mdl_state_t *st)
	Parse one exact state payload from an open portable file.

Detailed Description

Portable parser for persistent series state payloads.

Streams exact schema-v1/v2/v3/v4 records through bounded fw_fs reads.

Copyright: Copyright (c) 2026 Brighton Sikarskie SPDX-License-Identifier: MIT

Definition in file mdl_state_codec.c.

Enumeration Type Documentation

◆ mdl_c_col_t

enum mdl_c_col_t : uint8_t

Field index of each column on a C (chapter) record line.

Enumerator
k_c_id	Chapter identifier.
k_c_known	Explicit parsed-number flag (v2).
k_c_number	Parsed chapter number (v2).
k_c_done	Complete flag (0/1).
k_c_pages	Total page count.
k_c_ready	Pages fetched + verified.
k_c_epoch	Fetch time (epoch s).
k_c_url	Source URL.
k_c_title	Display title (v2).
k_c_fields_v2	Fields a v2 C line needs.
k_c_v1_number	Integral parsed chapter number.
k_c_v1_done	Complete flag (0/1).
k_c_v1_pages	Total page count.
k_c_v1_ready	Pages fetched + verified.
k_c_v1_epoch	Fetch time (epoch s).
k_c_v1_url	Source URL.
k_c_fields_v1	Fields a legacy C line needs.

Definition at line 30 of file mdl_state_codec.c.

◆ mdl_p_col_t

enum mdl_p_col_t : uint8_t

Field index of each column on a P (page) record line.

Enumerator
k_p_urlhash	Source-URL hash (hex).
k_p_content	Content hash (hex).
k_p_relpath	Path under the series.
k_p_etag	Cached ETag (optional).
k_p_lastmod	Cached Last-Modified (optional).
k_p_epoch	Most recent fetch epoch (v4).
k_p_status	Most recent HTTP status (v4).
k_p_fields	Minimum legacy P fields.
k_p_fields_v4	Exact fields a v4 P needs.

Definition at line 51 of file mdl_state_codec.c.

◆ mdl_state_parse_t

enum mdl_state_parse_t : uint16_t

Parser limits and radices.

Enumerator
k_state_max_flds	Max TAB fields split from a line.
k_state_hex_base	Radix for the hex hash fields.
k_state_dec_base	Radix for the decimal fields.
k_state_hex_alpha_base	Value represented by ASCII a.
k_state_decimal_digits_max	Legacy writer precision bound.
k_state_decimal_exp_max	Bounded legacy decimal scale.

Definition at line 20 of file mdl_state_codec.c.

Function Documentation

◆ internal_mdl_state_apply_chapter_v1()

bool internal_mdl_state_apply_chapter_v1	(	mdl_state_t *	st,
		char *	fld[],
		size_t	nf )

static

Parse and apply one legacy v1 chapter record.

Migrates integral nonzero presence semantics into the v2 tuple.

Parameters

[in,out]	st	State receiving the record.
[in]	fld	Split TAB fields.
[in]	nf	Number of fields.

Returns: Whether the exact v1 record was accepted.

Return values

true	A valid migrated chapter was appended.
false	Field count, numeric syntax, invariants, or capacity failed.

Precondition: st and fld are non-NULL.; nf describes accessible entries in fld.

Postcondition: On true, the chapter is represented using v2 in-memory semantics.; On false, parsing stops without reporting success.

Note: Not thread-safe: mutates st.

Since: 0.1.0

Definition at line 415 of file mdl_state_codec.c.

References internal_mdl_state_apply_chapter_values(), internal_mdl_state_parse_i64_field(), internal_mdl_state_parse_long_field(), internal_mdl_state_parse_u64_field(), k_c_fields_v1, k_c_v1_done, k_c_v1_epoch, k_c_v1_number, k_c_v1_pages, k_c_v1_ready, k_c_v1_url, and k_state_dec_base.

Referenced by internal_mdl_state_apply_line().

◆ internal_mdl_state_apply_chapter_v2()

bool internal_mdl_state_apply_chapter_v2	(	mdl_state_t *	st,
		char *	fld[],
		size_t	nf )

static

Parse and apply one current v2 chapter record.

Requires exact field count, Boolean flags, and a finite double.

Parameters

[in,out]	st	State receiving the record.
[in]	fld	Split TAB fields.
[in]	nf	Number of fields.

Returns: Whether the exact v2 record was accepted.

Return values

true	A valid chapter was appended.
false	Field count, syntax, invariants, or capacity failed.

Precondition: st and fld are non-NULL.; nf describes accessible entries in fld.

Postcondition: On true, explicit presence and fractional number are preserved.; On false, parsing stops without reporting success.

Note: Not thread-safe: mutates st.

Since: 0.1.0

Definition at line 461 of file mdl_state_codec.c.

References internal_mdl_state_apply_chapter_values(), internal_mdl_state_parse_double_field(), internal_mdl_state_parse_i64_field(), internal_mdl_state_parse_u64_field(), k_c_done, k_c_epoch, k_c_fields_v2, k_c_known, k_c_number, k_c_pages, k_c_ready, k_c_title, k_c_url, and k_state_dec_base.

Referenced by internal_mdl_state_apply_line().

◆ internal_mdl_state_apply_chapter_v3()

bool internal_mdl_state_apply_chapter_v3	(	mdl_state_t *	st,
		char *	fld[],
		size_t	nf )

static

Parse and apply one current-schema chapter record.

Parameters

[in,out]	st	Destination state.
[in,out]	fld	Split fields.
[in]	nf	Field count.

Returns: Application result.

Return values

false Any v3 field or invariant is invalid.

Precondition: st and fld are non-NULL.; The version record selected schema v3.

Postcondition: Success appends one complete chapter.; Failure appends no partial chapter.

Note: The chapter identity is canonical binary64 hex.

Since: 0.1.0

Definition at line 500 of file mdl_state_codec.c.

References internal_mdl_state_apply_chapter_values(), internal_mdl_state_parse_binary64(), internal_mdl_state_parse_i64_field(), internal_mdl_state_parse_u64_field(), k_c_done, k_c_epoch, k_c_fields_v2, k_c_known, k_c_number, k_c_pages, k_c_ready, k_c_title, k_c_url, and k_state_dec_base.

Referenced by internal_mdl_state_apply_line().

◆ internal_mdl_state_apply_chapter_values()

bool internal_mdl_state_apply_chapter_values	(	mdl_state_t *	st,
		char *	fld[],
		double	number,
		bool	number_known,
		uint64_t	done,
		uint64_t	pages,
		uint64_t	ready,
		int64_t	epoch,
		size_t	url_col,
		const char *	title )

static

Apply validated common chapter fields.

Enforces page/completion invariants and chapter-id uniqueness before appending a fully populated migrated/current record.

Parameters

[in,out]	st	State receiving the chapter.
[in]	fld	Split record fields.
[in]	number	Parsed chapter number.
[in]	number_known	Explicit number-presence flag.
[in]	done	Parsed completion flag.
[in]	pages	Parsed page count.
[in]	ready	Parsed completed-page count.
[in]	epoch	Parsed fetch epoch.
[in]	url_col	Source-URL column index.
[in]	title	Bounded display title.

Returns: Whether the complete record was accepted.

Return values

true	One valid chapter was appended.
false	A field/invariant failed or capacity was exhausted.

Precondition: st, fld, and title are non-NULL.; url_col addresses an element of fld.

Postcondition: On true, chapter count grows by one.; On false, no duplicate chapter is appended.

Note: Not thread-safe: mutates st.

Since: 0.1.0

Definition at line 370 of file mdl_state_codec.c.

References mdl_chapter_rec_t::complete, mdl_chapter_rec_t::fetched_at, k_c_id, mdl_state_add_chapter_numbered(), mdl_state_find_chapter(), mdl_state_set_chapter_metadata(), mdl_chapter_rec_t::page_count, mdl_chapter_rec_t::pages_done, and RA8_INTERNAL.

Referenced by internal_mdl_state_apply_chapter_v1(), internal_mdl_state_apply_chapter_v2(), and internal_mdl_state_apply_chapter_v3().

◆ internal_mdl_state_apply_kv()

bool internal_mdl_state_apply_kv	(	char *	dst,
		size_t	cap,
		char *	fld[],
		size_t	nf )

static

Store one exact bounded key/value record.

Requires exactly two TAB fields and copies without truncation.

Parameters

[out]	dst	Destination fixed field.
[in]	cap	Destination capacity.
[in]	fld	Split record fields.
[in]	nf	Number of fields.

Returns: Whether the record was valid and copied.

Return values

true	The value was copied exactly.
false	Field count or bounded-field validation failed.

Precondition: dst and fld are non-NULL.; cap is greater than zero.

Postcondition: On true, dst equals fld[1].; On false, dst is unchanged.

Note: Not thread-safe: writes caller storage.

Since: 0.1.0

Definition at line 582 of file mdl_state_codec.c.

References priv_mdl_state_field_valid(), priv_mdl_state_set_opt(), and RA8_INTERNAL.

Referenced by internal_mdl_state_apply_line(), and internal_mdl_state_apply_metadata().

◆ internal_mdl_state_apply_line()

bool internal_mdl_state_apply_line	(	mdl_state_t *	st,
		char *	fld[],
		size_t	nf,
		uint16_t *	schema_version )

static

Apply one already-split state record.

Dispatches by record type and enforces schema-specific grammar.

Parameters

[in,out]	st	State receiving the record.
[in]	fld	Split TAB fields.
[in]	nf	Number of fields.
[in,out]	schema_version	Zero before V; accepted schema afterward.

Returns: Whether the record is valid in sequence and schema.

Return values

true	The version was accepted or the record was applied.
false	The record is malformed, unsupported, duplicated, or misplaced.

Precondition: All pointer arguments are non-NULL.; nf is nonzero and describes accessible fld entries.

Postcondition: On first success, schema_version becomes v1, v2, v3, or v4.; On false, the caller rejects the complete stream.

Note: Not thread-safe: mutates parser state.

Since: 0.1.0

Definition at line 670 of file mdl_state_codec.c.

References mdl_state_t::config_path, internal_mdl_state_apply_chapter_v1(), internal_mdl_state_apply_chapter_v2(), internal_mdl_state_apply_chapter_v3(), internal_mdl_state_apply_kv(), internal_mdl_state_apply_metadata(), internal_mdl_state_apply_page(), internal_mdl_state_apply_version(), internal_mdl_state_parse_u64_field(), k_mdl_state_read_rtl, k_mdl_state_version_v1, k_mdl_state_version_v2, k_state_dec_base, mdl_state_t::reading_direction, mdl_state_t::series_title, mdl_state_t::series_url, mdl_state_t::site_host, and mdl_state_t::site_name.

Referenced by internal_mdl_state_parse_record().

◆ internal_mdl_state_apply_metadata()

bool internal_mdl_state_apply_metadata	(	mdl_state_t *	st,
		char	type,
		char *	fld[],
		size_t	nf )

static

Apply one current-schema rich-metadata record.

Dispatches one metadata type to its exact bounded destination.

Parameters

[in,out]	st	State receiving the field.
[in]	type	One of D, W, A, O, K, or L.
[in]	fld	Split record fields.
[in]	nf	Number of accessible fields.

Returns: Whether the exact record was recognized and accepted.

Return values

false Unknown type, invalid path, field count, or field contents.

Precondition: st and fld are non-NULL.; nf describes every accessible field pointer.

Postcondition: Success updates exactly one bounded metadata field.; Failure leaves the selected field unchanged.

Note: Cover paths additionally enforce relative non-traversing syntax.

Since: 0.1.0

Definition at line 608 of file mdl_state_codec.c.

References mdl_state_t::artist, mdl_state_t::cover_path, mdl_state_t::cover_url, internal_mdl_state_apply_kv(), mdl_state_t::language, priv_mdl_state_relative_path_valid(), mdl_state_t::summary, and mdl_state_t::writer.

Referenced by internal_mdl_state_apply_line().

◆ internal_mdl_state_apply_page()

bool internal_mdl_state_apply_page	(	mdl_state_t *	st,
		char *	fld[],
		size_t	nf,
		uint16_t	schema_version )

static

Parse and apply one page record.

Parameters

[in,out]	st	Destination state.
[in,out]	fld	Split fields.
[in]	nf	Field count.
[in]	schema_version	Active payload schema.

Returns: Application result.

Return values

false The record is malformed or over capacity.

Precondition: st and fld are non-NULL.; A supported version was already parsed.

Postcondition: Success appends exactly one page.; Failure leaves no partial page.

Note: Optional cache validators default to empty.

Since: 0.1.0

Definition at line 539 of file mdl_state_codec.c.

References internal_mdl_state_parse_i64_field(), internal_mdl_state_parse_u64_field(), k_mdl_state_version, k_p_content, k_p_epoch, k_p_etag, k_p_fields, k_p_fields_v4, k_p_lastmod, k_p_relpath, k_p_status, k_p_urlhash, k_state_dec_base, k_state_hex_base, and mdl_state_add_page().

Referenced by internal_mdl_state_apply_line().

◆ internal_mdl_state_apply_version()

bool internal_mdl_state_apply_version	(	char *	fld[],
		size_t	nf,
		uint16_t *	schema_version )

static

Accept one exact supported schema-version record.

Parameters

[in,out]	fld	Split fields.
[in]	nf	Field count.
[out]	schema_version	Selected schema.

Returns: Parse result.

Return values

false Duplicate, unsupported, or malformed version.

Precondition: fld and schema_version are non-NULL.; The caller initialized the version to zero.

Postcondition: Success selects v1, v2, v3, or v4.; Failure does not accept a partial numeric token.

Note: Exactly one version record is permitted.

Since: 0.1.0

Definition at line 637 of file mdl_state_codec.c.

References internal_mdl_state_parse_u64_field(), k_mdl_state_version, k_mdl_state_version_v1, k_mdl_state_version_v2, k_mdl_state_version_v3, and k_state_dec_base.

Referenced by internal_mdl_state_apply_line().

◆ internal_mdl_state_digit()

bool internal_mdl_state_digit	(	char	byte,
		int	base,
		uint8_t *	out )

static

Convert one canonical lowercase ASCII digit.

Parameters

[in]	byte	Candidate byte.
[in]	base	Radix.
[out]	out	Digit value.

Returns: Whether the byte belongs to the radix.

Return values

false Locale/case variant or out-of-range digit.

Precondition: out is non-NULL.; base is decimal or hexadecimal.

Postcondition: Success initializes out.; Failure does not accept locale-dependent text.

Note: Uppercase hexadecimal is intentionally noncanonical.

Since: 0.1.0

Definition at line 97 of file mdl_state_codec.c.

References k_state_hex_alpha_base, and RA8_INTERNAL.

Referenced by internal_mdl_state_parse_u64_field().

◆ internal_mdl_state_parse_binary64()

bool internal_mdl_state_parse_binary64	(	const char *	text,
		double *	out )

static

Parse one exact-width canonical binary64 bit identity.

Parameters

[in]	text	Sixteen lowercase hexadecimal digits.
[out]	out	Decoded value.

Returns: Parse result.

Return values

false Width, case, syntax, or finiteness violation.

Precondition: text and out are non-NULL.; The target satisfies the binary64 assertions.

Postcondition: Success preserves every finite bit.; NaN and infinity remain rejected.

Note: Decoding uses memcpy rather than type punning.

Since: 0.1.0

Definition at line 326 of file mdl_state_codec.c.

References internal_mdl_state_parse_u64_field(), k_state_hex_base, memcpy(), RA8_INTERNAL, and strlen().

Referenced by internal_mdl_state_apply_chapter_v3().

◆ internal_mdl_state_parse_decimal_exp()

bool internal_mdl_state_parse_decimal_exp	(	const char **	cursor,
		int32_t *	out_exp )

static

Parse one bounded ASCII decimal exponent.

Parameters

[in,out]	cursor	Exponent cursor.
[out]	out_exp	Signed exponent.

Returns: Parse result.

Return values

false Missing, trailing, or oversized exponent text.

Precondition: Both pointers are non-NULL.; The cursor begins after e or E.

Postcondition: Success advances to the terminator.; Work is bounded by the configured exponent cap.

Note: A sign is allowed only within the exponent.

Since: 0.1.0

Definition at line 197 of file mdl_state_codec.c.

References k_state_dec_base, k_state_decimal_exp_max, and RA8_INTERNAL.

Referenced by internal_mdl_state_parse_double_field().

◆ internal_mdl_state_parse_double_field()

bool internal_mdl_state_parse_double_field	(	const char *	text,
		double *	out )

static

Parse one complete locale-free legacy decimal binary64 value.

Parameters

[in]	text	Schema-v2 decimal.
[out]	out	Correctly rounded value.

Returns: Parse result.

Return values

false Noncanonical, overlong, overflowed, or underflowed input.

Precondition: text and out are non-NULL.; The target satisfies the binary64 assertions.

Postcondition: Success initializes the exact nearest-even result.; Failure accepts no trailing bytes.

Note: Conversion delegates to the fixed rational engine.

Since: 0.1.0

Definition at line 290 of file mdl_state_codec.c.

References internal_mdl_state_parse_decimal_exp(), internal_mdl_state_scan_mantissa(), k_state_decimal_exp_max, priv_mdl_state_decimal_to_binary64(), and RA8_INTERNAL.

Referenced by internal_mdl_state_apply_chapter_v2().

◆ internal_mdl_state_parse_i64_field()

bool internal_mdl_state_parse_i64_field	(	const char *	text,
		int64_t *	out )

static

Parse one exact signed 64-bit decimal including INT64_MIN.

Parameters

[in]	text	Canonical signed digits.
[out]	out	Parsed value.

Returns: Parse result.

Return values

false Invalid syntax or overflow.

Precondition: text and out are non-NULL.; A plus sign and whitespace are forbidden.

Postcondition: Success initializes the full int64 range.; Failure never invokes signed overflow.

Note: Accumulation uses an unsigned magnitude.

Since: 0.1.0

Definition at line 146 of file mdl_state_codec.c.

References internal_mdl_state_parse_u64_field(), k_state_dec_base, and RA8_INTERNAL.

Referenced by internal_mdl_state_apply_chapter_v1(), internal_mdl_state_apply_chapter_v2(), internal_mdl_state_apply_chapter_v3(), internal_mdl_state_apply_page(), and internal_mdl_state_parse_long_field().

◆ internal_mdl_state_parse_long_field()

bool internal_mdl_state_parse_long_field	(	const char *	text,
		long *	out )

static

Parse a target-width legacy signed long field exactly.

Parameters

[in]	text	Canonical signed digits.
[out]	out	Parsed target value.

Returns: Parse result.

Return values

false The value is outside long on this target.

Precondition: text and out are non-NULL.; The int64 parser contract applies.

Postcondition: Success initializes out.; Failure performs no narrowing conversion.

Note: Preserves v1 semantics on ILP32 and LP64.

Since: 0.1.0

Definition at line 179 of file mdl_state_codec.c.

References internal_mdl_state_parse_i64_field(), and RA8_INTERNAL.

Referenced by internal_mdl_state_apply_chapter_v1().

◆ internal_mdl_state_parse_record()

bool internal_mdl_state_parse_record	(	mdl_state_t *	st,
		char *	line,
		uint16_t *	schema_version )

static

Apply one non-comment payload record.

Parameters

[in,out]	st	Destination state.
[in,out]	line	Mutable record.
[in,out]	schema_version	Active schema.

Returns: Application result.

Return values

false Unknown or malformed record.

Precondition: All pointers are non-NULL.; line is NUL-terminated.

Postcondition: Success applies one whole record.; Failure never accepts excess fields.

Note: Comment and blank filtering occurs in the caller.

Since: 0.1.0

Definition at line 834 of file mdl_state_codec.c.

References internal_mdl_state_apply_line(), internal_mdl_state_split_tabs(), and k_state_max_flds.

Referenced by priv_mdl_state_parse_file().

◆ internal_mdl_state_parse_u64_field()

bool internal_mdl_state_parse_u64_field	(	const char *	text,
		int	base,
		uint64_t *	out )

static

Parse one exact unsigned decimal or hexadecimal field.

Parameters

[in]	text	Canonical digits.
[in]	base	Radix.
[out]	out	Parsed value.

Returns: Parse result.

Return values

false Empty, malformed, or overflowing input.

Precondition: out is non-NULL.; base is decimal or hexadecimal.

Postcondition: Success initializes out exactly.; Failure never wraps arithmetic.

Note: Parsing is locale and libc-width independent.

Since: 0.1.0

Definition at line 120 of file mdl_state_codec.c.

References internal_mdl_state_digit(), k_state_dec_base, and k_state_hex_base.

Referenced by internal_mdl_state_apply_chapter_v1(), internal_mdl_state_apply_chapter_v2(), internal_mdl_state_apply_chapter_v3(), internal_mdl_state_apply_line(), internal_mdl_state_apply_page(), internal_mdl_state_apply_version(), internal_mdl_state_parse_binary64(), and internal_mdl_state_parse_i64_field().

◆ internal_mdl_state_reader_byte()

ra8_err_t internal_mdl_state_reader_byte	(	mdl_state_reader_t *	reader,
		uint8_t *	out,
		bool *	out_eof )

static

Deliver one byte from a bounded payload reader.

Parameters

[in,out]	reader	Bounded reader.
[out]	out	Byte.
[out]	out_eof	End marker.

Returns: Portable I/O status.

Return values

k_ra8_ok Byte or clean EOF delivered.

Precondition: All pointers are non-NULL.; Reader counters are internally consistent.

Postcondition: EOF initializes out_eof true.; A byte decrements the remaining extent once.

Note: Refill failures propagate unchanged.

Since: 0.1.0

Definition at line 772 of file mdl_state_codec.c.

References mdl_state_reader_t::available, mdl_state_reader_t::cursor, internal_mdl_state_reader_refill(), mdl_storage_t::io_buffer, k_ra8_ok, and mdl_state_reader_t::storage.

Referenced by internal_mdl_state_reader_line().

◆ internal_mdl_state_reader_line()

ra8_err_t internal_mdl_state_reader_line	(	mdl_state_reader_t *	reader,
		char *	line,
		size_t	capacity,
		bool *	out_has_line )

static

Read one bounded text record.

Parameters

[in,out]	reader	Bounded reader.
[out]	line	Record buffer.
[in]	capacity	Buffer size.
[out]	out_has_line	Presence flag.

Returns: Portable parse/I/O status.

Return values

k_ra8_err_invalid_state Record exceeds capacity.

Precondition: All pointers are non-NULL.; capacity permits a terminator.

Postcondition: A present line is NUL-terminated.; Final unterminated records remain accepted.

Note: Embedded NUL bytes are rejected later as malformed fields.

Since: 0.1.0

Definition at line 797 of file mdl_state_codec.c.

References internal_mdl_state_reader_byte(), k_ra8_err_invalid_state, k_ra8_ok, and RA8_INTERNAL.

Referenced by priv_mdl_state_parse_file().

◆ internal_mdl_state_reader_refill()

ra8_err_t internal_mdl_state_reader_refill ( mdl_state_reader_t * reader )

static

Refill a payload reader without crossing its declared extent.

Parameters

[in,out] reader Bounded reader.

Returns: Portable I/O status.

Return values

k_ra8_err_invalid_state Zero progress before the declared end.

Precondition: reader and its storage/file are valid.; Remaining length is authoritative.

Postcondition: Success exposes at least one byte when bytes remain.; No read crosses the payload extent.

Note: Read attempts are globally bounded.

Since: 0.1.0

Definition at line 740 of file mdl_state_codec.c.

References mdl_state_reader_t::available, mdl_state_reader_t::cursor, mdl_state_reader_t::file, fw_fs_read(), mdl_storage_t::io_buffer, mdl_storage_t::io_buffer_bytes, k_ra8_err_invalid_state, k_ra8_ok, RA8_INTERNAL, mdl_state_reader_t::remaining, and mdl_state_reader_t::storage.

Referenced by internal_mdl_state_reader_byte().

◆ internal_mdl_state_scan_mantissa()

bool internal_mdl_state_scan_mantissa	(	const char **	cursor,
		uint64_t *	out_mantissa,
		int32_t *	out_fractional,
		bool *	out_digit )

static

Scan a canonical decimal mantissa: digits with at most one point.

Accumulates the unsigned magnitude and the fractional-digit count while advancing the cursor past every consumed digit and the optional decimal point, rejecting a mantissa that exceeds the configured significant- or fractional-digit caps.

Parameters

[in,out]	cursor	Scan cursor; advanced past the last consumed byte.
[out]	out_mantissa	Accumulated unsigned magnitude.
[out]	out_fractional	Count of digits consumed after the point.
[out]	out_digit	Whether at least one digit was consumed.

Returns: Whether the mantissa stayed within the configured digit caps.

Return values

true	The mantissa was consumed and every cap was respected.
false	A significant- or fractional-digit cap was exceeded.

Precondition: cursor addresses a non-NULL, NUL-terminated cursor.; out_mantissa, out_fractional, and out_digit are non-NULL.

Postcondition: Success advances *cursor to the first byte after the mantissa and writes all three out-parameters.; Failure leaves *cursor at the offending digit; the out-parameters are not written and must not be read.

Note: Not thread-safe; operates purely on caller-owned bytes.

Since: 0.1.0

Definition at line 246 of file mdl_state_codec.c.

References k_state_dec_base, k_state_decimal_digits_max, k_state_decimal_exp_max, and RA8_INTERNAL.

Referenced by internal_mdl_state_parse_double_field().

◆ internal_mdl_state_split_tabs()

size_t internal_mdl_state_split_tabs	(	char *	line,
		char *	fld[],
		size_t	max )

static

Split one record in place at TAB delimiters.

Parameters

[in,out]	line	Mutable record.
[out]	fld	Field pointers.
[in]	max	Pointer capacity.

Returns: Field count.

Return values

`max	+ 1` Too many fields.

Precondition: All pointers are non-NULL.; max is positive.

Postcondition: Returned fields alias line.; Excess fields are reported, not truncated silently.

Note: Does not allocate.

Since: 0.1.0

Definition at line 72 of file mdl_state_codec.c.

References RA8_INTERNAL, and strchr().

Referenced by internal_mdl_state_parse_record().

◆ priv_mdl_state_parse_file()

ra8_err_t priv_mdl_state_parse_file	(	mdl_storage_t *	storage,
		fw_fs_file_t *	file,
		uint64_t	offset,
		uint64_t	length,
		uint16_t	max_schema_version,
		mdl_state_t *	st )

Parse one exact state payload from an open portable file.

Streams a declared payload extent and migrates supported schemas transactionally.

Parameters

[in,out]	storage	Initialized storage scratch binding.
[in,out]	file	Open file containing the payload.
[in]	offset	First payload byte.
[in]	length	Exact payload byte count.
[in]	max_schema_version	Highest schema authorized by the containing format.
[out]	st	State model receiving the parsed and migrated payload.

Returns: Canonical parse/read status.

Return values

k_ra8_err_invalid_state Malformed, truncated, trailing, or unsupported payload.

Precondition: All pointers are non-NULL and file is open for reading.; Offset and length identify the authenticated payload extent.; max_schema_version is a supported nonzero schema version.

Postcondition: Success replaces st with the complete migrated/current state.; Failure leaves st initialized empty.

Note: Parsing uses bounded caller-owned scratch.

Since: 0.1.0

Definition at line 845 of file mdl_state_codec.c.

References fw_fs_seek(), internal_mdl_state_parse_record(), internal_mdl_state_reader_line(), mdl_storage_t::io_buffer, mdl_storage_t::io_buffer_bytes, k_mdl_state_line_max, k_mdl_state_version, k_ra8_err_invalid_arg, k_ra8_err_invalid_state, k_ra8_ok, mdl_state_init(), priv_mdl_state_valid(), and RA8_PRIV.

Referenced by internal_mdl_state_load_slot().

Data Structures

Enumerations

Functions

Detailed Description

Enumeration Type Documentation

◆ mdl_c_col_t

◆ mdl_p_col_t

◆ mdl_state_parse_t

Function Documentation

◆ internal_mdl_state_apply_chapter_v1()

◆ internal_mdl_state_apply_chapter_v2()

◆ internal_mdl_state_apply_chapter_v3()

◆ internal_mdl_state_apply_chapter_values()

◆ internal_mdl_state_apply_kv()

◆ internal_mdl_state_apply_line()

◆ internal_mdl_state_apply_metadata()

◆ internal_mdl_state_apply_page()

◆ internal_mdl_state_apply_version()

◆ internal_mdl_state_digit()

◆ internal_mdl_state_parse_binary64()

◆ internal_mdl_state_parse_decimal_exp()

◆ internal_mdl_state_parse_double_field()

◆ internal_mdl_state_parse_i64_field()

◆ internal_mdl_state_parse_long_field()

◆ internal_mdl_state_parse_record()

◆ internal_mdl_state_parse_u64_field()

◆ internal_mdl_state_reader_byte()

◆ internal_mdl_state_reader_line()

◆ internal_mdl_state_reader_refill()

◆ internal_mdl_state_scan_mantissa()

◆ internal_mdl_state_split_tabs()

◆ priv_mdl_state_parse_file()