mdl_stream.c File Reference

Private bounded text helpers over the portable byte-stream contract. More...

#include "mdl_stream_internal.h"

Include dependency graph for mdl_stream.c:

Go to the source code of this file.

Enumerations
enum	mdl_stream_limit_t : uint8_t { k_mdl_stream_repeat_max = 64 }
	Maximum repeated byte count accepted by one helper call. More...

Functions
ra8_err_t	priv_mdl_stream_text (ra8_err_t prior, ra8_io_stream_t *stream, const char *text)
	Append text unless an earlier operation already failed.
ra8_err_t	priv_mdl_stream_u64 (ra8_err_t prior, ra8_io_stream_t *stream, uint64_t value)
	Append one unsigned integer unless an earlier append failed.
ra8_err_t	priv_mdl_stream_hex (ra8_err_t prior, ra8_io_stream_t *stream, uint32_t value)
	Append one hexadecimal error/status value after prior success.
ra8_err_t	priv_mdl_stream_repeat (ra8_err_t prior, ra8_io_stream_t *stream, char byte, size_t count)
	Append a bounded repeated byte after prior success.
ra8_err_t	priv_mdl_stream_flush (ra8_err_t prior, ra8_io_stream_t *stream)
	Flush a stream only when every earlier append succeeded.

Detailed Description

Private bounded text helpers over the portable byte-stream contract.

Chains exact fragments and bounded numeric rendering while retaining the first sink error without allocation or variadic formatting.

Copyright

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

Definition in file mdl_stream.c.

Enumeration Type Documentation

mdl_stream_limit_t

enum mdl_stream_limit_t : uint8_t

Maximum repeated byte count accepted by one helper call.

Enumerator
k_mdl_stream_repeat_max	Fixed loop bound for presenter fragments.

Definition at line 12 of file mdl_stream.c.

Function Documentation

priv_mdl_stream_flush()

ra8_err_t priv_mdl_stream_flush	(	ra8_err_t	prior,
		ra8_io_stream_t *	stream )

Flush a stream only when every earlier append succeeded.

Parameters

[in]	prior	Status from the preceding append.
[in,out]	stream	Bound destination stream.

Returns

prior when failed, otherwise the flush status.

Precondition

stream remains bound and exclusively owned.

prior is a canonical status.

Postcondition

The first failure in an append chain is preserved.

Success commits all sink-side buffered bytes.

Note

Not thread-safe for concurrent use of one stream.

Since

0.1.0

Performs one synchronous operation against the injected stream. An earlier error is returned unchanged and prevents later stream access.

Return values

k_ra8_ok	The operation completed successfully.
other	The originating validation, storage, stream, or network error.

Definition at line 52 of file mdl_stream.c.

References k_ra8_ok, ra8_io_stream_flush(), and RA8_PRIV.

Referenced by mdl_report_progress_bar().

priv_mdl_stream_hex()

ra8_err_t priv_mdl_stream_hex	(	ra8_err_t	prior,
		ra8_io_stream_t *	stream,
		uint32_t	value )

Append one hexadecimal error/status value after prior success.

Parameters

[in]	prior	Status from the preceding append.
[in,out]	stream	Bound destination stream.
[in]	value	Unsigned value rendered without a prefix.

Returns

prior when failed, otherwise the current append status.

Precondition

stream remains bound and exclusively owned.

prior is a canonical status.

Postcondition

The first failure in an append chain is preserved.

Success appends at least one lowercase hexadecimal digit.

Note

Not thread-safe for concurrent use of one stream.

Since

0.1.0

Performs one synchronous operation against the injected stream. An earlier error is returned unchanged and prevents later stream access.

Return values

k_ra8_ok	The operation completed successfully.
other	The originating validation, storage, stream, or network error.

Definition at line 26 of file mdl_stream.c.

References k_ra8_ok, ra8_io_stream_put_hex(), and RA8_PRIV.

Referenced by internal_direct_pack_failure(), internal_pack_report_combine_failure(), internal_pack_report_failure(), internal_report_cover_failure(), and internal_run_series_paths().

priv_mdl_stream_repeat()

ra8_err_t priv_mdl_stream_repeat	(	ra8_err_t	prior,
		ra8_io_stream_t *	stream,
		char	byte,
		size_t	count )

Append a bounded repeated byte after prior success.

Parameters

[in]	prior	Status from the preceding append.
[in,out]	stream	Bound destination stream.
[in]	byte	Byte repeated in the destination.
[in]	count	Repetition count, at most 64.

Returns

prior when failed, otherwise the append status.

Return values

k_ra8_err_invalid_size

count exceeded the fixed bound.

Precondition

stream remains bound and exclusively owned.

prior is a canonical status.

Postcondition

The first failure in an append chain is preserved.

Success appends exactly count copies of byte.

Note

Not thread-safe for concurrent use of one stream.

Since

0.1.0

Performs one synchronous operation against the injected stream. An earlier error is returned unchanged and prevents later stream access.

Definition at line 31 of file mdl_stream.c.

References k_mdl_stream_repeat_max, k_ra8_err_invalid_size, k_ra8_ok, ra8_io_stream_putc(), RA8_LOOP_BOUND, and RA8_PRIV.

Referenced by mdl_report_progress_bar().

priv_mdl_stream_text()

ra8_err_t priv_mdl_stream_text	(	ra8_err_t	prior,
		ra8_io_stream_t *	stream,
		const char *	text )

Append text unless an earlier operation already failed.

Parameters

[in]	prior	Status from the preceding append.
[in,out]	stream	Bound destination stream.
[in]	text	NUL-terminated text fragment.

Returns

prior when failed, otherwise the current append status.

Precondition

text is NUL-terminated and stream remains bound.

prior is a canonical status.

Postcondition

The first failure in an append chain is preserved.

Success appends exactly the text bytes without a terminator.

Note

Not thread-safe for concurrent use of one stream.

Since

0.1.0

Performs one synchronous operation against the injected stream. An earlier error is returned unchanged and prevents later stream access.

Return values

k_ra8_ok	The operation completed successfully.
other	The originating validation, storage, stream, or network error.

Definition at line 16 of file mdl_stream.c.

References k_ra8_ok, ra8_io_stream_puts(), and RA8_PRIV.

Referenced by internal_admin_text3(), internal_apply_order(), internal_cover_finish(), internal_credential_capacity_error(), internal_direct_pack_failure(), internal_direct_text3(), internal_discover_text3(), internal_download_page_image(), internal_download_page_images(), internal_export_after(), internal_extract_cover(), internal_extract_optional_metadata(), internal_extract_page_images(), internal_extract_series_metadata(), internal_fetch_artifact(), internal_finish_artifact_fetch(), internal_init_site_identity(), internal_library_report(), internal_library_text3(), internal_list_cb(), internal_mdl_fetch_diag3(), internal_mdl_fetch_select_chapter_number(), internal_mdl_fetch_select_chapter_title(), internal_pack_combined_dir(), internal_pack_combined_dir_output(), internal_pack_dir_output(), internal_pack_directory_output(), internal_pack_file_output(), internal_pack_report_combine_failure(), internal_pack_report_failure(), internal_pack_text3(), internal_prepare_diag3(), internal_present_and_pick(), internal_print_header(), internal_print_hits(), internal_print_zero(), internal_publish_page_image(), internal_reconcile_series_state(), internal_report_cover_failure(), internal_report_position(), internal_report_robots_disallow(), internal_report_robots_unavailable(), internal_report_stats(), internal_run_series_network(), internal_run_series_paths(), internal_select_hit(), internal_select_run_window(), internal_series_text3(), internal_verify_artifact_entry(), internal_verify_print_summary(), internal_warn_no_contact(), mdl_app_run_artifact(), mdl_app_run_discover(), mdl_app_run_init_site(), mdl_app_run_pack(), mdl_app_run_page(), mdl_app_run_series(), mdl_app_run_update_all(), mdl_discover_run(), mdl_pack_combined_meta(), mdl_pack_one_meta(), mdl_report_failures(), mdl_report_progress(), mdl_report_progress_bar(), mdl_session_url_allowed(), and priv_mdl_app_report_cache().

priv_mdl_stream_u64()

ra8_err_t priv_mdl_stream_u64	(	ra8_err_t	prior,
		ra8_io_stream_t *	stream,
		uint64_t	value )

Append one unsigned integer unless an earlier append failed.

Parameters

[in]	prior	Status from the preceding append.
[in,out]	stream	Bound destination stream.
[in]	value	Unsigned value rendered in decimal.

Returns

prior when failed, otherwise the current append status.

Precondition

stream remains bound and exclusively owned.

prior is a canonical status.

Postcondition

The first failure in an append chain is preserved.

Success appends the exact locale-independent decimal identity.

Note

Not thread-safe for concurrent use of one stream.

Since

0.1.0

Performs one synchronous operation against the injected stream. An earlier error is returned unchanged and prevents later stream access.

Return values

k_ra8_ok	The operation completed successfully.
other	The originating validation, storage, stream, or network error.

Definition at line 21 of file mdl_stream.c.

References k_ra8_ok, ra8_io_stream_put_u64(), and RA8_PRIV.

Referenced by internal_cover_finish(), internal_credential_capacity_error(), internal_download_page_image(), internal_download_page_images(), internal_library_report(), internal_present_and_pick(), internal_print_header(), internal_print_hits(), internal_print_zero(), internal_publish_page_image(), internal_report_position(), internal_report_stats(), internal_run_series_network(), internal_select_hit(), internal_verify_artifact_entry(), internal_verify_print_summary(), mdl_app_run_artifact(), mdl_app_run_page(), mdl_app_run_update_all(), mdl_pack_combined_meta(), mdl_report_failures(), mdl_report_progress_bar(), and priv_mdl_app_report_cache().