Struct Span 

pub struct Span<'src> {
    source: &'src str,
    index: usize,
    length: usize,
}

A struct that spans over a &str, written as Span<'src>.

Consequently, index refers to a char index and NOT a u8 index.

---

We shall name this Span struct Spanley. Spanley is our child now.

Spanley knows where it is with index and Spanley knows when to stop with length.

If source dies, Spanley dies with it. Do not let source die, for Spanley’s sake.

Fields

source: &'src str

index: usize

length: usize

Implementations

impl<'src> Span<'src>

pub fn new( source: &'src str, index: usize, length: usize, ) -> Result<Self, SpanError>

Birth a new Spanley. The future is now.

Error Handling

If Span::start or Span::end for the constructed Span would end up out of bounds of source, this method will return SpanError::OutOfBounds.

pub fn new_encompassing(lhs: &Self, rhs: &Self) -> Result<Self, SpanError>

Birth a Spanley which encompasses two other Spanleys. You see, when two Spanleys love each other very much…

In more technical terms, it will construct a span with a start at the minimum start index of both spans, and end at the maximum end index of both spans.

The constructed Span will therefore also contain anything in the gap between the two input Spans, if there is one.

Example

Assuming there are two Spans, one contains the word span and the other contains the word another_span from the following string:

"Here is a span and yet another_span, yippe!"
           ^^^^         ^^^^^^^^^^^^

Then the constructed Span would contain the following:

"Here is a span and yet another_span, yippe!"
           ^^^^^^^^^^^^^^^^^^^^^^^^^

Error Handling

The two operands here are expected to share the same source, if that is not so, this method will return SpanError::MismatchedSource

Because the resulting Span is constructed from two Spans that have already validated their bounds, there is no chance of the Span::new call in this method to result in a SpanError::OutOfBounds

pub fn overlaps(lhs: &Self, rhs: &Self) -> bool

Checks for overlaps between two Spans.

This method does not validate that both operands share the same source like Span::new_encompassing does, and only compares indices to check for an overlap.

Friendly reminder that Span::end is exclusive.

pub fn get_start_location(&self) -> SpanLocation

Constructs a SpanLocation using SpanLocation::from_index_unchecked at Span::start.

This is done without the bounds check in SpanLocation because the Span bounds were already validated at construction.

pub fn get_end_location(&self) -> SpanLocation

Constructs a SpanLocation using SpanLocation::from_index_unchecked at Span::end.

This is done without the bounds check in SpanLocation because the Span bounds were already validated at construction.

pub fn start(&self) -> usize

Returns index, which corresponds to the start of the Span.

pub fn end(&self) -> usize

Returns the end index of the Span. The end index is the very next index after the latest contained index and is therefore exclusive.

Calculated by adding together index and length.

pub fn len(&self) -> usize

Returns length.

pub fn is_empty(&self) -> bool

Returns true when length is 0.

pub fn source(&self) -> &str

Returns the Span’s source field.

pub fn content(&self) -> &str

Returns a string slice over the contents of the Span.

pub fn get_context(&self, extra_lines: u8) -> Self

This method is meant for logging purposes, it will construct a new Span containing all the lines the current Span spans over, in addition to a varying amount of lines of extra margin at the start and end.

extra_lines is a u8 here because… realistically, we will never be working with a &str that has more than usize::MAX lines. For this reason, the maximum supported amount of extra_lines is of a little below usize::MAX / 2. Additionally, I do not believe you will ever need more than 255 lines of extra context, you freaks.

Examples

Assuming the current Span starts at the word span on line 3 and ends with the word span on line 4 in the following text:

1 | Here's a lines at the very very start!
2 | Here's a line right before the lines with the span.
3 | Here's the line where the span starts.
                              ^^^^^^^^^^^^
4 | Here's the line where the span ends.
    ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
5 | Here's a line right after the lines with the span.
6 | Here is the final line.

The resulting Span with a provided extra_lines of 1 will contain the following:

1 | Here's a lines at the very very start!
2 | Here's a line right before the lines with the span.
    ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
3 | Here's the line where the span starts.
    ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
4 | Here's the line where the span ends.
    ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
5 | Here's a line right after the lines with the span.
    ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
6 | Here is the final line.

And with extra_lines set to 0:

1 | Here's a lines at the very very start!
2 | Here's a line right before the lines with the span.
3 | Here's the line where the span starts.
    ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
4 | Here's the line where the span ends.
    ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
5 | Here's a line right after the lines with the span.
6 | Here is the final line.

Trait Implementations

impl<'src> Clone for Span<'src>

fn clone(&self) -> Span<'src>

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for Span<'_>

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

Formats the value using the given formatter.

impl Display for Span<'_>

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

Formats the value using the given formatter.

impl<'src> Ord for Span<'src>

fn cmp(&self, other: &Span<'src>) -> Ordering

This method returns an Ordering between self and other.

fn max(self, other: Self) -> Self

where Self: Sized,

Compares and returns the maximum of two values.

fn min(self, other: Self) -> Self

where Self: Sized,

Compares and returns the minimum of two values.

fn clamp(self, min: Self, max: Self) -> Self

where Self: Sized,

Restrict a value to a certain interval.

impl<'src> PartialEq for Span<'src>

fn eq(&self, other: &Span<'src>) -> 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<'src> PartialOrd for Span<'src>

fn partial_cmp(&self, other: &Span<'src>) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

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

Tests less than (for self and other) and is used by the < operator.

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

Tests less than or equal to (for self and other) and is used by the <= operator.

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

Tests greater than (for self and other) and is used by the > operator.

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

Tests greater than or equal to (for self and other) and is used by the >= operator.

impl<'src> Copy for Span<'src>

impl<'src> Eq for Span<'src>

impl<'src> StructuralPartialEq for Span<'src>

Layout

Note: Most layout information is completely unstable and may even differ between compilations. The only exception is types with certain repr(...) attributes. Please see the Rust Reference's “Type Layout” chapter for details on type layout guarantees.

Size: 32 bytes