Struct Span 

pub struct Span<'src> {
    source: &'src str,
    byte_index: usize,
    byte_length: usize,
}

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

byte_index and byte_length both refer to the bytes of the &str, not the utf8 characters of the &str.

---

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

Spanley knows where it is with byte_index and Spanley knows when to stop with byte_length.

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

Fields

source: &'src str

byte_index: usize

byte_length: usize

Implementations

impl<'src> Span<'src>

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

Birth a new Spanley. The future is now.

This method takes in a char_index and a char_length over the utf8 characters of the &str whilst the Span stores a byte_index and a byte_length internally over the bytes of the &str.

Error Handling

This method will return SpanError::Empty if char_length is 0. Empty spans are considered purely invalid.

This method will return SpanError::OutOfBounds if char_index is out of bounds for source or if char_index + char_length would not result in a value above usize::MAX and the last valid indice, at char_index + char_length - 1usize, is out of bounds for source.

This method will return SpanError::Overflow if char_index + char_length would be above usize::MAX, or if byte_index, byte_length or both added together would be above usize::MAX.

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

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

Available on crate feature location only.

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

Available on crate feature location only.

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 byte_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 byte_index and byte_length.

pub fn len(&self) -> usize

Returns byte_length.

This is a length in bytes and not in utf8 characters and thus may not be what a human considers the length of the span.

pub fn is_empty(&self) -> bool

Returns true when byte_length is 0.

pub fn source(&self) -> &str

Returns the Span’s internal private 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 possible 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> 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> 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