Crate line_span

This crate features utilities for finding the start, end, and range of lines from a byte index. Further also being able to find the next and previous line, from an arbitrary byte index.

This is provided via the trait LineSpanExt, which is implemented for str, and provides the following methods:

Current Line:

• find_line_start() to find the start of the current line.
• find_line_end() to find the end of the current line.
• find_line_range() to find the start and end current line.

Next Line:

• find_next_line_start() to find the start of the next line.
• find_next_line_end() to find the end of the next line.
• find_next_line_range() to find the start and end of the next line.

Previous Line:

• find_prev_line_start() to find the start of the previous line.
• find_prev_line_end() to find the end of the previous line.
• find_prev_line_range() to find both start and end of the previous line.

Iterator:

• line_spans() an iterator over LineSpans, i.e. str::lines() but including the start and end byte indicies (in the form of a Range<usize>).

Utilities:

• str_to_range() to get the range of a substring in a string.
• str_to_range_unchecked() unchecked version of str_to_range().

LineSpan and LineSpanIter

The crate includes the LineSpanIter iterator. It is functionally equivalent to str::lines(), with the addition that it includes the ability to get the start and end byte indices of each line. Additionally, it also includes the ability to get the end including and excluding the line ending (\n or \r\n).

An LineSpanIter can be created by calling line_spans(), implemented in the LineSpans trait. The crate implements the LineSpans trait for str and String.

Note, LineSpan implements Deref to &str, so in general, swapping lines() to line_spans() would not cause many issues.

use line_span::LineSpanExt;

let text = "foo\nbar\r\nbaz";

for span in text.line_spans() {
    println!(
        "{:>2?}: {:?} {:?} {:?}",
        span.range(),
        span.as_str(),
        span.as_str_with_ending(),
        span.ending_str(),
    );
}

This will output the following:

(Manually aligned for better readability)

0.. 3: "foo" "foo\n"   "\n"
4.. 7: "bar" "bar\r\n" "\r\n"
9..12: "baz" "baz"     ""

Current Line, Previous Line, and Next Line

use line_span::LineSpanExt;

let text = "foo\nbar\r\nbaz";
//                ^
let i = 5; // 'a' in "bar"

let curr_range = text.find_line_range(i);
let next_range = text.find_next_line_range(i).unwrap();
let prev_range = text.find_prev_line_range(i).unwrap();

assert_eq!(curr_range, 4..7);
assert_eq!(&text[curr_range], "bar");

assert_eq!(prev_range, 0..3);
assert_eq!(&text[prev_range], "foo");

assert_eq!(next_range, 9..12);
assert_eq!(&text[next_range], "baz");

Range of Substring in String

Use str_to_range (or str_to_range_unchecked) to get the range of a substring in a string.

let string1 = "Foo Bar Baz";
let string2 = "Hello World";

let substring = &string1[4..7]; // "Bar"

// Returns `Some` as `substring` is a part of `string1`
assert_eq!(str_to_range(string1, substring), Some(4..7));

// Returns `None` as `substring` is not a part of `string2`
assert_eq!(str_to_range(string2, substring), None);

Structs

LineSpan

LineSpan represents a single line. It is possible to get a &str of the line both including and excluding \n and \r\n.

LineSpanIter

An iterator over LineSpans.

Traits

LineSpanExt

Trait implementing utility methods for finding the start, end, and range of lines from a byte index. Further also being able to find the next and previous line, from an arbitrary byte index.

LineSpans

Trait which implements line_spans() to get a LineSpanIter.

Functions

find_line_end

Use LineSpanExt::find_line_end() instead.

find_line_range

Use LineSpanExt::find_line_range() instead.

find_line_start

Use LineSpanExt::find_line_start() instead.

find_next_line_end

Use LineSpanExt::find_next_line_end() instead.

find_next_line_range

Use LineSpanExt::find_next_line_range() instead.

find_next_line_start

Use LineSpanExt::find_next_line_start() instead.

find_prev_line_end

Use LineSpanExt::find_prev_line_end() instead.

find_prev_line_range

Use LineSpanExt::find_prev_line_range() instead.

find_prev_line_start

Use LineSpanExt::find_prev_line_start() instead.

str_to_range

Get the start and end (byte index) range (Range<usize>), where substring is located in string. The returned range is relative to string.

str_to_range_unchecked

Get the start and end (byte index) range (Range<usize>), where substring is located in string. The returned range is relative to string.