#[non_exhaustive]pub struct Span {
pub start: Marker,
pub end: Marker,
pub indent: Option<usize>,
pub tag_start: Option<Marker>,
/* private fields */
}Expand description
A range of locations in a YAML document.
Construct spans with Self::new, Self::empty, or Self::default, then use
Self::with_indent to attach optional indentation metadata. Public fields remain
readable and writable, but the type is non-exhaustive so future releases can add metadata.
Destructuring patterns must include ...
use granit_parser::{Marker, Span};
let start = Marker::new(0, 1, 0);
let end = Marker::new(3, 1, 3);
let span = Span::new(start, end).with_indent(Some(0));
let Span { start: actual_start, end: actual_end, .. } = span;
assert_eq!(actual_start, start);
assert_eq!(actual_end, end);
assert_eq!(span.indent, Some(0));Direct struct construction outside this crate is not supported:
use granit_parser::{Marker, Span};
let marker = Marker::new(0, 1, 0);
let span = Span { start: marker, end: marker, indent: None, tag_start: None };Struct-update syntax is likewise unavailable; use the builders or assign individual fields:
use granit_parser::{Marker, Span};
let span = Span { indent: Some(2), ..Span::empty(Marker::new(0, 1, 0)) };Fields (Non-exhaustive)§
This struct is marked as non-exhaustive
Struct { .. } syntax; cannot be matched against without a wildcard ..; and struct update syntax will not work.start: MarkerThe start (inclusive) of the range.
end: MarkerThe end (exclusive) of the range.
indent: Option<usize>Optional indentation hint associated with this span.
This is only meaningful for certain parser-emitted events (notably: block mapping keys).
When indentation is not meaningful or cannot be provided, it must be None.
tag_start: Option<Marker>Optional source marker for the explicit tag token attached to this node.
This is only meaningful for parser-emitted node events that carry a resolved tag, such as
Event::Scalar,
Event::SequenceStart, or
Event::MappingStart. The normal Span::start and
Span::end continue to cover the node value or collection; tag_start points to the
tag token when that token appears at a different source location.
Implementations§
Source§impl Span
impl Span
Sourcepub fn empty(mark: Marker) -> Span
pub fn empty(mark: Marker) -> Span
Create an empty Span at a given location.
An empty span doesn’t contain any characters, but its position may still be meaningful.
For example, for an indented sequence SequenceEnd has a location but an empty span.
Sourcepub fn with_indent(self, indent: Option<usize>) -> Span
pub fn with_indent(self, indent: Option<usize>) -> Span
Return a copy of this Span with the given indentation hint.
Sourcepub fn with_tag_start(self, tag_start: Option<Marker>) -> Span
👎Deprecated since 2.1.0: Only sets a tag start (.tag_span() then returns None). Use with_tag_span.
pub fn with_tag_start(self, tag_start: Option<Marker>) -> Span
Only sets a tag start (.tag_span() then returns None). Use with_tag_span.
Return a copy of this Span with the given explicit tag-token start marker.
Clears any stored tag length, so Self::tag_span returns None on the returned span.
Retained for compatibility. Parser-emitted spans provide complete tag-token ranges through
Self::tag_span.
Sourcepub fn with_tag_span(self, tag_span: Option<(Marker, u32)>) -> Span
pub fn with_tag_span(self, tag_span: Option<(Marker, u32)>) -> Span
Attach the start and raw source length of a single-line ASCII tag token.
Sourcepub fn tag_start(&self) -> Option<Marker>
pub fn tag_start(&self) -> Option<Marker>
Return the source marker of the explicit tag token attached to this node, if any.
The regular span still covers the node value or collection. This accessor is useful for diagnostics that should point at the tag itself, especially when a tagged block collection begins on a later line than the tag token.
Sourcepub fn tag_span(&self) -> Option<Span>
pub fn tag_span(&self) -> Option<Span>
Return the complete source span of the explicit tag attached to this node, if available.
Includes the leading !, any verbatim-tag delimiters, and URI escapes exactly as written.
The node’s own Self::start and Self::end are unchanged. The returned span carries no
indentation or tag metadata. With byte offsets, use Self::slice on it to obtain the raw
tag spelling; streaming inputs retain character positions without requiring byte offsets.
Returns None for untagged nodes and tag tokens longer than u32::MAX source characters,
or coordinates that would overflow. Oversized tags still parse normally and retain their
start marker.
use granit_parser::Parser;
let source = "key: !note%20here value";
let tag_span = Parser::new_from_str(source)
.filter_map(Result::ok)
.find_map(|(_, span)| span.tag_span())
.unwrap();
assert_eq!(tag_span.slice(source), Some("!note%20here"));Sourcepub fn len(&self) -> usize
pub fn len(&self) -> usize
Return the length of the span (in characters).
§Panics
Panics in debug builds if the end marker precedes the start marker.
Sourcepub fn byte_range(&self) -> Option<Range<usize>>
pub fn byte_range(&self) -> Option<Range<usize>>
Return the half-open UTF-8 byte range of the span, if both markers have byte offsets.
Spans emitted by Parser::new_from_str and its
options variant always return Some, including empty ranges. Iterator inputs and
manually constructed markers may lack offsets, so the return type is optional.
A missing range is not the same as an empty range; do not substitute 0..0 for None.
Unlike Self::len and Marker::index, this range counts bytes, not characters.
For manually constructed or modified spans, this method does not validate ordering,
bounds, or UTF-8 boundaries. Use Self::slice for checked access to source text.
Sourcepub fn slice<'source>(&self, source: &'source str) -> Option<&'source str>
pub fn slice<'source>(&self, source: &'source str) -> Option<&'source str>
Return the source text covered by this span, if byte offsets are available and the range is valid for the provided input.
Pass the same, unchanged source that produced the span. Bounds and UTF-8 boundaries are checked, but a span does not record source identity. The returned text is the raw event source, which can differ from a decoded scalar value or be empty for implicit events.