xml_internal.h File Reference

Private lexical seams shared by the bounded XML reader. More...

#include <stddef.h>
#include <stdint.h>
#include "ra8_attributes.h"
#include "xml.h"

Include dependency graph for xml_internal.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Enumerations
enum	priv_xml_encoding_t : uint32_t {   k_priv_xml_tab = 0x09U ,   k_priv_xml_line_feed = 0x0AU ,   k_priv_xml_carriage_return = 0x0DU ,   k_priv_xml_printable_min = 0x20U ,   k_priv_xml_bmp_first_max = 0xD7FFU ,   k_priv_xml_bmp_second_min = 0xE000U ,   k_priv_xml_bmp_second_max = 0xFFFDU ,   k_priv_xml_supplementary_min = 0x10000U ,   k_priv_xml_scalar_max = 0x10FFFFU ,   k_priv_utf8_two_lead_min = 0xC2U ,   k_priv_utf8_two_lead_max = 0xDFU ,   k_priv_utf8_two_payload_mask = 0x1FU ,   k_priv_utf8_three_lead_min = 0xE0U ,   k_priv_utf8_three_lead_max = 0xEFU ,   k_priv_utf8_three_payload_mask = 0x0FU ,   k_priv_utf8_three_scalar_min = 0x800U ,   k_priv_utf8_four_lead_min = 0xF0U ,   k_priv_utf8_four_lead_max = 0xF4U ,   k_priv_utf8_four_payload_mask = 0x07U ,   k_priv_utf8_continuation_mask = 0xC0U ,   k_priv_utf8_continuation_tag = 0x80U ,   k_priv_utf8_scalar_mask = 0x3FU ,   k_priv_utf8_two_lead_tag = 0xC0U ,   k_priv_utf8_three_lead_tag = 0xE0U ,   k_priv_utf8_four_lead_tag = 0xF0U ,   k_priv_utf8_shift_second = 12U ,   k_priv_utf8_shift_third = 18U ,   k_priv_xml_decimal_base = 10U ,   k_priv_xml_encoding_bytes = 5U ,   k_priv_xml_cdata_open_bytes = 9U ,   k_priv_xml_doctype_open_bytes = 9U ,   k_priv_utf8_bom_first = 0xEFU ,   k_priv_utf8_bom_second = 0xBBU ,   k_priv_utf8_bom_third = 0xBFU }
	XML 1.0 scalar bounds and canonical UTF-8 bit geometry. More...

Functions
bool	priv_xml_span_valid (size_t source_len, xml_span_t span)
	Check that a source-relative span is in range.
bool	priv_xml_bytes_equal (const uint8_t *source, size_t offset, const char *literal, size_t length)
	Compare bounded source bytes with an ASCII character sequence.
ra8_err_t	priv_xml_qname (const uint8_t *source, size_t end, size_t start, size_t *out_end)
	Scan the supported QName subset over a bounded byte range.
ra8_err_t	priv_xml_raw (const uint8_t *source, size_t start, size_t end)
	Validate canonical UTF-8 XML 1.0 characters over a byte range.
ra8_err_t	priv_xml_doctype (xml_reader_t *reader)
	Validate and skip one supported pre-root external DOCTYPE.

Detailed Description

Private lexical seams shared by the bounded XML reader.

Exposes the scalar geometry plus the span, QName, raw UTF-8, and external-only DOCTYPE validators shared across the reader's implementation translation units.

[Ring 3 / LIB] {World: NS}

Copyright

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

Definition in file xml_internal.h.

Enumeration Type Documentation

priv_xml_encoding_t

enum priv_xml_encoding_t : uint32_t

XML 1.0 scalar bounds and canonical UTF-8 bit geometry.

Enumerator
k_priv_xml_tab	XML tab character.
k_priv_xml_line_feed	XML line-feed character.
k_priv_xml_carriage_return	XML carriage-return character.
k_priv_xml_printable_min	First ordinary XML character.
k_priv_xml_bmp_first_max	Last scalar before surrogates.
k_priv_xml_bmp_second_min	First scalar after surrogates.
k_priv_xml_bmp_second_max	Last permitted BMP scalar.
k_priv_xml_supplementary_min	First supplementary scalar.
k_priv_xml_scalar_max	Last Unicode scalar.
k_priv_utf8_two_lead_min	First canonical two-byte lead.
k_priv_utf8_two_lead_max	Last two-byte lead.
k_priv_utf8_two_payload_mask	Payload bits in a two-byte lead.
k_priv_utf8_three_lead_min	First three-byte lead.
k_priv_utf8_three_lead_max	Last three-byte lead.
k_priv_utf8_three_payload_mask	Payload bits in a three-byte lead.
k_priv_utf8_three_scalar_min	First scalar needing three bytes.
k_priv_utf8_four_lead_min	First four-byte lead.
k_priv_utf8_four_lead_max	Last canonical four-byte lead.
k_priv_utf8_four_payload_mask	Payload bits in a four-byte lead.
k_priv_utf8_continuation_mask	Continuation tag mask.
k_priv_utf8_continuation_tag	Continuation tag and ASCII ceiling.
k_priv_utf8_scalar_mask	Scalar bits per continuation byte.
k_priv_utf8_two_lead_tag	Encoded two-byte lead tag.
k_priv_utf8_three_lead_tag	Encoded three-byte lead tag.
k_priv_utf8_four_lead_tag	Encoded four-byte lead tag.
k_priv_utf8_shift_second	Shift for the second payload group.
k_priv_utf8_shift_third	Shift for the third payload group.
k_priv_xml_decimal_base	Numeric-entity decimal radix.
k_priv_xml_encoding_bytes	Bytes in the UTF-8 encoding label.
k_priv_xml_cdata_open_bytes	Bytes in the CDATA opener.
k_priv_xml_doctype_open_bytes	Bytes in the DOCTYPE opener.
k_priv_utf8_bom_first	First UTF-8 BOM byte.
k_priv_utf8_bom_second	Second UTF-8 BOM byte.
k_priv_utf8_bom_third	Third UTF-8 BOM byte.

Definition at line 24 of file xml_internal.h.

Function Documentation

priv_xml_bytes_equal()

bool priv_xml_bytes_equal	(	const uint8_t *	source,
		size_t	offset,
		const char *	literal,
		size_t	length )

Compare bounded source bytes with an ASCII character sequence.

Compares byte by byte so plain-character literals are never passed to memcmp() alongside essentially-unsigned source bytes.

Parameters

[in]	source	Immutable source bytes.
[in]	offset	First source byte to compare.
[in]	literal	Character sequence whose first length bytes are compared.
[in]	length	Number of bytes to compare.

Returns

True only when every byte matches.

Return values

true	The complete byte sequence matched.
false	At least one byte differed.

Precondition

source spans at least offset + length readable bytes.

literal spans at least length readable characters.

Postcondition

No memory is modified.

The result depends only on the supplied byte sequences.

Note

Pure and thread-safe.

Since

0.1.0

Compare bounded source bytes with an ASCII character sequence.

Walks both operands one byte at a time so the comparison never hands an essentially-character operand to memcmp(), whose ordering is implementation-defined for plain char (MISRA-C:2012 Rules 21.14, 21.16). Only equality is ever asked of this function, so the loop is the whole contract.

Parameters

[in]	source	Immutable source bytes.
[in]	offset	First source byte to compare.
[in]	literal	Literal whose first length bytes are compared.
[in]	length	Byte count to compare.

Returns

True exactly when the two byte runs are equal.

Return values

true	Every compared byte matched.
false	At least one byte differed.

Precondition

source spans at least offset + length readable bytes.

literal spans at least length readable bytes.

Postcondition

No memory is modified.

The result depends only on the arguments.

Note

Pure and thread-safe.

Since

0.1.0

Definition at line 260 of file xml_decode.c.

Referenced by internal_encoding(), internal_entity(), internal_external_id(), internal_keyword(), internal_pi(), internal_special(), internal_terminator(), priv_xml_doctype(), and xml_span_equal().

priv_xml_doctype()

ra8_err_t priv_xml_doctype

(

xml_reader_t *

reader

)

Validate and skip one supported pre-root external DOCTYPE.

Accepts bare, SYSTEM, or PUBLIC external-only forms and fetches nothing.

Parameters

[in,out]

reader

Active reader positioned at <!DOCTYPE.

Returns

Repository error code.

Return values

k_ra8_ok	Supported declaration consumed.
k_ra8_err_validation_failed	Placement, subset, or grammar was invalid.

Precondition

Reader source/position describe a complete bounded document.

No root or prior DOCTYPE has been consumed.

Postcondition

Success advances after > and marks one DOCTYPE seen.

Failure leaves immutable source bytes unchanged.

Note

Internal subsets and entity declarations fail closed.

Since

0.1.0

Definition at line 196 of file xml_doctype.c.

References xml_reader_t::doctype_seen, internal_external_id(), internal_skip_space(), k_ra8_err_validation_failed, k_ra8_ok, xml_reader_t::position, priv_xml_bytes_equal(), priv_xml_qname(), xml_reader_t::root_count, xml_reader_t::source, and xml_reader_t::source_len.

Referenced by internal_special().

priv_xml_qname()

ra8_err_t priv_xml_qname	(	const uint8_t *	source,
		size_t	end,
		size_t	start,
		size_t *	out_end )

Scan the supported QName subset over a bounded byte range.

Accepts one or two ASCII NCName components separated by one colon.

Parameters

[in]	source	Immutable XML source.
[in]	end	One-past-last readable lexical byte.
[in]	start	Candidate QName start offset.
[out]	out_end	One-past-last accepted QName byte.

Returns

Repository error code.

Return values

k_ra8_ok	At least one valid QName component was consumed.
k_ra8_err_validation_failed	Start or namespace spelling was invalid.

Precondition

source spans at least end readable bytes.

out_end is writable and does not overlap source.

Postcondition

Success sets an offset in [start + 1, end].

Failure leaves source unchanged and output unspecified.

Note

This is the documented ASCII QName subset, not full XML NameStartChar.

Since

0.1.0

Definition at line 47 of file xml.c.

References internal_name_continue(), internal_name_start(), k_ra8_err_validation_failed, and k_ra8_ok.

Referenced by internal_attr_parse(), internal_end(), internal_pi(), internal_start(), and priv_xml_doctype().

priv_xml_raw()

ra8_err_t priv_xml_raw	(	const uint8_t *	source,
		size_t	start,
		size_t	end )

Validate canonical UTF-8 XML 1.0 characters over a byte range.

Rejects overlong encoding, invalid continuations, controls, and surrogates.

Parameters

[in]	source	Immutable XML source.
[in]	start	First byte to validate.
[in]	end	One-past-last byte to validate.

Returns

Repository error code.

Return values

k_ra8_ok	Every byte belongs to a permitted canonical scalar.
k_ra8_err_validation_failed	Encoding or XML character was invalid.

Precondition

source spans at least end readable bytes.

start <= end describes a half-open range.

Postcondition

Source bytes remain unchanged.

Success validates the complete range, not a prefix.

Note

Allocation-free and thread-safe.

Since

0.1.0

Definition at line 610 of file xml_decode.c.

References internal_utf8_next(), and k_ra8_ok.

Referenced by internal_cdata(), internal_comment(), internal_literal(), and internal_pi().

priv_xml_span_valid()

bool priv_xml_span_valid	(	size_t	source_len,
		xml_span_t	span )

Check that a source-relative span is in range.

Uses subtraction after checking the offset to avoid overflow.

Parameters

[in]	source_len	Exact source byte extent.
[in]	span	Candidate source-relative span.

Returns

True only when the complete span lies in the extent.

Return values

true	Offset and length are bounded.
false	The span is forged, stale, or out of range.

Precondition

source_len is the true readable extent.

span uses the same source-relative coordinate system.

Postcondition

No memory is modified.

The result is overflow-safe.

Note

Pure and thread-safe.

Since

0.1.0

Definition at line 161 of file xml_decode.c.

References xml_span_t::length, and xml_span_t::offset.

Referenced by xml_attr_next(), xml_decode(), xml_decode_prefix(), xml_decoded_size(), xml_span_equal(), and xml_span_local_equal().