Struct Spanned 

pub struct Spanned<T> {
    pub value: T,
    pub span: Span,
    pub file_id: u16,
}

A value with an associated source location (span and file).

PartialEq / Eq / Hash are implemented manually to delegate to the inner value only — two Spanned<T> values are considered equal when their Ts are equal, regardless of where they came from in source. This matches the principle that “what” a value is should not depend on where it lives. Consumers that genuinely need location-sensitive equality compare .span and .file_id explicitly.

Note: the rkyv-archived form (ArchivedSpanned<T>, present under the rkyv feature) does not automatically receive PartialEq / Eq. The host doesn’t compare archived values today; if a future code path needs to, add rkyv(compare = (PartialEq)) to the derive attribute below or hand-roll a manual impl on the archived type.

#[non_exhaustive] policy

Deliberately NOT #[non_exhaustive], for the same reason as Span: it is constructed via struct literal in hundreds of call sites and the field set is intentionally minimal and stable. Add fields cautiously; if a new field is genuinely needed, prefer a sibling/wrapper type over modifying this one in place.

Fields

value: T

The value.

span: Span

The source span (byte offsets within the file).

file_id: u16

The source file ID (index into SourceMap). Uses u16 to minimize struct size (max 65,535 files).

Implementations

impl<T> Spanned<T>

pub const fn new(value: T, span: Span) -> Spanned<T>

Create a new spanned value with file_id defaulting to 0.

Use with_file_id to set the correct file ID after creation.

pub const fn synthesized(value: T) -> Spanned<T>

Wrap a value that was programmatically synthesized (no source representation). Uses Span::ZERO and SYNTHESIZED_FILE_ID so downstream consumers can detect “no source” without sentinel checks on the inner value’s fields.

Used by plugin-synthesized AST nodes, test fixtures, CLI commands that build directives in-memory, and any other producer that does not parse from source bytes.

pub fn with_file_id(self, file_id: usize) -> Spanned<T>

Set the file ID for this spanned value.

Accepts usize for API convenience but stores as u16 internally.

Panics

Debug builds will panic if file_id exceeds u16::MAX (65,535).

pub fn map<U, F>(self, f: F) -> Spanned<U>

where F: FnOnce(T) -> U,

Map the inner value, preserving span and file_id.

pub const fn inner(&self) -> &T

Get a reference to the inner value.

pub fn into_inner(self) -> T

Unwrap the spanned value, discarding the span and file_id.

Trait Implementations

impl<T> Archive for Spanned<T>

where T: Archive, Span: Archive, u16: Archive,

type Archived = ArchivedSpanned<T>

The archived representation of this type.

type Resolver = SpannedResolver<T>

The resolver for this type. It must contain all the additional information from serializing needed to make the archived type from the normal type.

fn resolve( &self, resolver: <Spanned<T> as Archive>::Resolver, out: Place<<Spanned<T> as Archive>::Archived>, )

Creates the archived version of this value at the given position and writes it to the given output.

const COPY_OPTIMIZATION: CopyOptimization<Self> = _

An optimization flag that allows the bytes of this type to be copied directly to a writer instead of calling serialize.

impl<T> Clone for Spanned<T>

where T: Clone,

fn clone(&self) -> Spanned<T>

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<T> Debug for Spanned<T>

where T: Debug,

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl<T> Deref for Spanned<T>

Spanned<T> is a transparent wrapper that adds source location to a value. Following the convention used by other transparent wrappers in the standard library (Box<T>, Rc<T>, Cow<'_, T>, MutexGuard<T>), it implements Deref so callers can read inner fields and call inner methods without spelling .value everywhere. Consumers that genuinely need to inspect the source location reach for .span, .file_id, or .value (for ownership) explicitly.

type Target = T

The resulting type after dereferencing.

fn deref(&self) -> &T

Dereferences the value.

impl<T> DerefMut for Spanned<T>

fn deref_mut(&mut self) -> &mut T

Mutably dereferences the value.

impl<'de, T> Deserialize<'de> for Spanned<T>

where T: Deserialize<'de>,

fn deserialize<__D>( __deserializer: __D, ) -> Result<Spanned<T>, <__D as Deserializer<'de>>::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl<__D, T> Deserialize<Spanned<T>, __D> for <Spanned<T> as Archive>::Archived

where __D: Fallible + ?Sized, T: Archive, <T as Archive>::Archived: Deserialize<T, __D>, Span: Archive, <Span as Archive>::Archived: Deserialize<Span, __D>, u16: Archive, <u16 as Archive>::Archived: Deserialize<u16, __D>,

fn deserialize( &self, deserializer: &mut __D, ) -> Result<Spanned<T>, <__D as Fallible>::Error>

Deserializes using the given deserializer

impl<T> Display for Spanned<T>

where T: Display,

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl<T> Eq for Spanned<T>

where T: Eq,

impl<T> Hash for Spanned<T>

where T: Hash,

fn hash<H>(&self, state: &mut H)

where H: Hasher,

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl<T> PartialEq for Spanned<T>

where T: PartialEq,

fn eq(&self, other: &Spanned<T>) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<T> Serialize for Spanned<T>

where T: Serialize,

fn serialize<__S>( &self, __serializer: __S, ) -> Result<<__S as Serializer>::Ok, <__S as Serializer>::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.

impl<__S, T> Serialize<__S> for Spanned<T>

where __S: Fallible + ?Sized, T: Serialize<__S>, Span: Serialize<__S>, u16: Serialize<__S>,

fn serialize( &self, serializer: &mut __S, ) -> Result<<Spanned<T> as Archive>::Resolver, <__S as Fallible>::Error>

Writes the dependencies for the object and returns a resolver that can create the archived type.

impl<T> ShiftSpans for Spanned<T>

where T: ShiftSpans,

fn shift_spans<F>(&mut self, shift: &F)

where F: Fn(&mut Span),

Apply shift to every Span reachable in self.