Struct Span

pub struct Span<H: Haystack>
where
    H::Target: Hay,
{ /* private fields */ }

A span is a haystack coupled with the original range where the haystack is found.

It can be considered as a tuple (H, Range<H::Target::Index>) where the range is guaranteed to be valid for the haystack.

Examples

use pattern_3::Span;

let orig_str = "Hello世界";
let orig_span = Span::<&str>::from(orig_str);

// slice a span.
let span = unsafe { orig_span.slice_unchecked(3..8) };

// further slicing (note the range is relative to the original span)
let subspan = unsafe { span.slice_unchecked(4..8) };

// obtains the substring.
let substring = subspan.into();
assert_eq!(substring, "o世");

Visualizing the spans:

0   1   2   3   4   5   6   7   8   9  10  11
+---+---+---+---+---+---+---+---+---+---+---+
| H | e | l | l | o | U+4E16    | U+754C    |    orig_str
+---+---+---+---+---+---+---+---+---+---+---+

^___________________________________________^    orig_span = (orig_str, 0..11)

            ^___________________^                span = (orig_str, 3..8)

                ^_______________^                subspan = (orig_str, 4..8)

Implementations

impl<H: SharedHaystack> Span<H>

where H::Target: Hay,

pub fn into_parts(self) -> (H, Range<<H::Target as Hay>::Index>)

Decomposes this span into the original haystack, and the range it focuses on.

pub unsafe fn from_parts( haystack: H, range: Range<<H::Target as Hay>::Index>, ) -> Self

Creates a span from a haystack, and a range it should focus on.

Safety

The range must be a valid range relative to haystack.

impl<'h> Span<&'h str>

pub fn as_bytes(self) -> Span<&'h [u8]>

Reinterprets the string span as a byte-array span.

impl<H: Haystack> Span<H>

where H::Target: Hay,

pub fn original_range(&self) -> Range<<H::Target as Hay>::Index>

The range of the span, relative to the ultimate original haystack it was sliced from.

pub fn borrow(&self) -> Span<&H::Target>

Borrows a shared span.

pub fn is_empty(&self) -> bool

Checks whether this span is empty.

pub fn take(&mut self) -> Self

Returns this span by value, and replaces the original span by an empty span.

pub fn into(self) -> H

Slices the original haystack to the focused range.

pub unsafe fn split_around( self, subrange: Range<<H::Target as Hay>::Index>, ) -> [Self; 3]

Splits this span into 3 spans around the given range.

Safety

subrange must be a valid range relative to self.borrow(). A safe usage is like:

let range = searcher.search(span.borrow())?;
let [left, middle, right] = unsafe { span.split_around(range) };

pub unsafe fn slice_unchecked( self, subrange: Range<<H::Target as Hay>::Index>, ) -> Self

Slices this span to the given range.

Safety

subrange must be a valid range relative to self.borrow().

impl<'h> Span<&'h Wtf8>

pub fn as_bytes(self) -> Span<&'h [u8]>

Trait Implementations

impl<H: Clone + Haystack> Clone for Span<H>

where H::Target: Hay,

fn clone(&self) -> Span<H>

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl<H: Debug + Haystack> Debug for Span<H>

where H::Target: Hay,

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

Formats the value using the given formatter.

impl<H: Haystack> From<H> for Span<H>

where H::Target: Hay,

Creates a span which covers the entire haystack.

fn from(haystack: H) -> Self

Converts to this type from the input type.