Owns XML source bytes and mutable source anchors. More...

#include "donner/base/xml/XMLSourceStore.h"

Classes
struct	ResourceLimits
	Resource limits for retained anchors and anchor-update work. More...
struct	ResourceStats
	Exact resource accounting for source anchors and edit work. More...

Public Member Functions
	XMLSourceStore ()=default
	Construct an empty source store.
	XMLSourceStore (std::string source, std::size_t maximumSourceSize=16 1024 1024)
	Construct a source store with initial source bytes.
	XMLSourceStore (std::string source, ResourceLimits limits)
	Construct a source store with explicit resource limits.
std::string_view	source () const UTILS_LIFETIME_BOUND
	Return the current source bytes.
std::uint64_t	sourceVersion () const
	Return the monotonically increasing source version.
const ResourceLimits &	resourceLimits () const
	Return the configured source-anchor resource limits.
ResourceStats	resourceStats () const
	Return exact source-anchor resource accounting.
bool	setResourceLimits (ResourceLimits limits)
	Replace the resource limits without changing source or anchors.
std::optional< SourceAnchorId >	createAnchor (std::size_t offset, SourceAnchorBias bias=SourceAnchorBias::Before)
	Create an anchor at `offset`.
std::optional< SourceAnchorSpan >	createSpan (std::size_t start, std::size_t end, SourceAnchorBias startBias=SourceAnchorBias::Before, SourceAnchorBias endBias=SourceAnchorBias::After)
	Create a span from two anchors.
std::optional< std::size_t >	resolveAnchor (SourceAnchorId id) const
	Resolve an anchor to its current byte offset.
std::optional< ResolvedSourceSpan >	resolveSpan (SourceAnchorSpan span) const
	Resolve a span to current byte offsets.
void	invalidateAnchor (SourceAnchorId id)
	Invalidate an anchor explicitly.
std::optional< XMLSourceDelta >	replace (std::size_t offset, std::size_t length, std::string_view replacement)
	Replace a byte range in the source.
FileOffset	resolveLineInfo (FileOffset offset) const
	Attach line and column information to a byte offset into the current source.

Detailed Description

Owns XML source bytes and mutable source anchors.

XMLSourceStore is the first primitive needed for structured editing. It keeps source ranges stable across edits by storing anchor ids instead of long-lived absolute offsets. Public callers may still resolve anchors to absolute byte offsets for diagnostics, tests, and source display.

Class Documentation

◆ donner::xml::XMLSourceStore::ResourceLimits

struct donner::xml::XMLSourceStore::ResourceLimits

Resource limits for retained anchors and anchor-update work.

Class Members
size_t	maximumAnchorUpdateWorkPerEdit = 1024 * 1024	Maximum live anchors visited by one source edit.
size_t	maximumLiveAnchorCount = 1024 * 1024	Maximum simultaneously live source anchors.
size_t	maximumSourceSize = 16 * 1024 * 1024	Maximum source bytes retained after an edit.

◆ donner::xml::XMLSourceStore::ResourceStats

struct donner::xml::XMLSourceStore::ResourceStats

Exact resource accounting for source anchors and edit work.

Class Members
uint64_t	anchorUpdateWorkRejections = 0	Edits rejected before an anchor scan.
size_t	lastAnchorUpdateWork = 0	Live anchors visited by the last accepted edit.
size_t	liveAnchorCount = 0	Anchors that can currently be resolved.
size_t	peakLiveAnchorCount = 0	Highest live-anchor count reached.
uint64_t	totalAnchorUpdateWork = 0	Live anchors visited by accepted edits.
uint64_t	totalCreatedAnchors = 0	Anchors created over this store's lifetime.
uint64_t	totalRetiredAnchors = 0	Anchors invalidated over this store's lifetime.

Constructor & Destructor Documentation

◆ XMLSourceStore() [1/2]

donner::xml::XMLSourceStore::XMLSourceStore	(	std::string	source,
		std::size_t	maximumSourceSize = 16 1024 1024 )

explicit

Construct a source store with initial source bytes.

Parameters

source Initial XML source text.

◆ XMLSourceStore() [2/2]

donner::xml::XMLSourceStore::XMLSourceStore	(	std::string	source,
		ResourceLimits	limits )

Construct a source store with explicit resource limits.

Parameters

source	Initial XML source text.
limits	Source, live-anchor, and per-edit anchor-work limits.

Member Function Documentation

◆ createAnchor()

std::optional< SourceAnchorId > donner::xml::XMLSourceStore::createAnchor	(	std::size_t	offset,
		SourceAnchorBias	bias = SourceAnchorBias::Before )

nodiscard

Create an anchor at offset.

Parameters

offset	Current source byte offset.
bias	Insertion behavior when an edit inserts exactly at `offset`.

Returns: The new anchor id, or std::nullopt if offset is out of bounds or not a UTF-8 boundary.

◆ createSpan()

std::optional< SourceAnchorSpan > donner::xml::XMLSourceStore::createSpan	(	std::size_t	start,
		std::size_t	end,
		SourceAnchorBias	startBias = SourceAnchorBias::Before,
		SourceAnchorBias	endBias = SourceAnchorBias::After )

nodiscard

Create a span from two anchors.

Parameters

start	Inclusive current source byte offset.
end	Exclusive current source byte offset.
startBias	Insertion behavior when an edit inserts exactly at `start`.
endBias	Insertion behavior when an edit inserts exactly at `end`.

Returns: The new span, or std::nullopt if either offset is invalid.

◆ invalidateAnchor()

void donner::xml::XMLSourceStore::invalidateAnchor ( SourceAnchorId id )

Invalidate an anchor explicitly.

Parameters

id	Anchor id to invalidate.

◆ replace()

std::optional< XMLSourceDelta > donner::xml::XMLSourceStore::replace	(	std::size_t	offset,
		std::size_t	length,
		std::string_view	replacement )

nodiscard

Replace a byte range in the source.

Anchors before the edit remain fixed, anchors after the edit move by the byte delta, boundary anchors honor their insertion bias, and anchors strictly inside the removed range are invalidated.

Parameters

offset	Start byte offset of the edit.
length	Number of bytes to remove.
replacement	Replacement source bytes.

Returns: Edit delta, or std::nullopt if the range or replacement is invalid.

◆ resolveAnchor()

std::optional< std::size_t > donner::xml::XMLSourceStore::resolveAnchor ( SourceAnchorId id ) const

nodiscard

Resolve an anchor to its current byte offset.

Parameters

id	Anchor id to resolve.

Returns: Current offset, or std::nullopt if the anchor was invalidated.

◆ resolveLineInfo()

FileOffset donner::xml::XMLSourceStore::resolveLineInfo ( FileOffset offset ) const

nodiscard

Attach line and column information to a byte offset into the current source.

The line table is scanned on first use and reused until the source changes, so parsing a document that never needs a line number never pays for it. Building it mutates state behind a const method, so this must not run concurrently with another access to the same store: the document access lock admits any number of simultaneous readers, and nothing today resolves line numbers from more than one of them at a time.

Parameters

offset Byte offset, or an unresolved offset which is returned unchanged.

◆ resolveSpan()

std::optional< ResolvedSourceSpan > donner::xml::XMLSourceStore::resolveSpan ( SourceAnchorSpan span ) const

nodiscard

Resolve a span to current byte offsets.

Parameters

span	Span to resolve.

Returns: Current span, or std::nullopt if either anchor was invalidated or inverted.

◆ setResourceLimits()

bool donner::xml::XMLSourceStore::setResourceLimits ( ResourceLimits limits )

nodiscard

Replace the resource limits without changing source or anchors.

The source and live-anchor limits cannot be lowered below current retained state. The per-edit work limit may be lower than the current live-anchor count, in which case later edits fail transactionally until the limit is raised or anchors are retired.

Returns: True if the new limits were installed.

The documentation for this class was generated from the following file:

donner/base/xml/XMLSourceStore.h

Classes

Public Member Functions

Detailed Description

Class Documentation

◆ donner::xml::XMLSourceStore::ResourceLimits

◆ donner::xml::XMLSourceStore::ResourceStats

Constructor & Destructor Documentation

◆ XMLSourceStore() [1/2]

◆ XMLSourceStore() [2/2]

Member Function Documentation

◆ createAnchor()

◆ createSpan()

◆ invalidateAnchor()

◆ replace()

◆ resolveAnchor()

◆ resolveLineInfo()

◆ resolveSpan()

◆ setResourceLimits()