Struct nom_locate::LocatedSpan

impl<T> LocatedSpan<T, ()>

pub fn new(program: T) -> LocatedSpan<T, ()>

Create a span for a particular input with default offset and line values and empty extra data. You can compute the column through the get_column or get_utf8_column methods.

offset starts at 0, line starts at 1, and column starts at 1.

Do not use this constructor in parser functions; nom and nom_locate assume span offsets are relative to the beginning of the same input. In these cases, you probably want to use the nom::traits::Slice trait instead.

Example of use

use nom_locate::LocatedSpan;

let span = LocatedSpan::new(b"foobar");

assert_eq!(span.location_offset(), 0);
assert_eq!(span.location_line(),   1);
assert_eq!(span.get_column(),      1);
assert_eq!(span.fragment(),        &&b"foobar"[..]);

Examples found in repository ?

examples/position.rs (line 33)

fn main() {
    let input = Span::new("Lorem ipsum \n foobar");
    let output = parse_foobar(input);
    let position = output.unwrap().1.position;
    assert_eq!(position, unsafe {
        Span::new_from_raw_offset(
            14, // offset
            2,  // line
            "", // fragment
            (), // extra
        )
    });
    assert_eq!(position.get_column(), 2);
}

impl<T, X> LocatedSpan<T, X>

pub fn new_extra(program: T, extra: X) -> LocatedSpan<T, X>

Create a span for a particular input with default offset and line values. You can compute the column through the get_column or get_utf8_column methods.

offset starts at 0, line starts at 1, and column starts at 1.

Do not use this constructor in parser functions; nom and nom_locate assume span offsets are relative to the beginning of the same input. In these cases, you probably want to use the nom::traits::Slice trait instead.

Example of use

use nom_locate::LocatedSpan;

let span = LocatedSpan::new_extra(b"foobar", "extra");

assert_eq!(span.location_offset(), 0);
assert_eq!(span.location_line(),   1);
assert_eq!(span.get_column(),      1);
assert_eq!(span.fragment(),        &&b"foobar"[..]);
assert_eq!(span.extra,             "extra");

pub unsafe fn new_from_raw_offset( offset: usize, line: u32, fragment: T, extra: X ) -> LocatedSpan<T, X>

Similar to new_extra, but allows overriding offset and line. This is unsafe, because giving an offset too large may result in undefined behavior, as some methods move back along the fragment assuming any negative index within the offset is valid.

Examples found in repository ?

examples/position.rs (lines 37-42)

fn main() {
    let input = Span::new("Lorem ipsum \n foobar");
    let output = parse_foobar(input);
    let position = output.unwrap().1.position;
    assert_eq!(position, unsafe {
        Span::new_from_raw_offset(
            14, // offset
            2,  // line
            "", // fragment
            (), // extra
        )
    });
    assert_eq!(position.get_column(), 2);
}

pub fn location_offset(&self) -> usize

The offset represents the position of the fragment relatively to the input of the parser. It starts at offset 0.

pub fn location_line(&self) -> u32

The line number of the fragment relatively to the input of the parser. It starts at line 1.

pub fn fragment(&self) -> &T

The fragment that is spanned. The fragment represents a part of the input of the parser.

Examples found in repository ?

examples/position.rs (line 26)

fn parse_foobar(s: Span) -> IResult<Span, Token> {
    let (s, _) = take_until("foo")(s)?;
    let (s, pos) = position(s)?;
    let (s, foo) = tag("foo")(s)?;
    let (s, bar) = tag("bar")(s)?;

    Ok((
        s,
        Token {
            position: pos,
            _foo: foo.fragment(),
            _bar: bar.fragment(),
        },
    ))
}

pub fn map_extra<U, F: FnOnce(X) -> U>(self, f: F) -> LocatedSpan<T, U>

Transform the extra inside into another type

Example of use

use nom::{
  IResult,
  combinator::{recognize, map_res},
  sequence::{terminated, tuple},
  character::{complete::{char, one_of}, is_digit},
  bytes::complete::{tag, take_while1}
};

fn decimal(input: LocatedSpan<&str>) -> IResult<LocatedSpan<&str>, LocatedSpan<&str>> {
  recognize(
       take_while1(|c| is_digit(c as u8) || c == '_')
  )(input)
}

fn main() {
    let span = LocatedSpan::new("$10");
    // matches the $ and then matches the decimal number afterwards,
    // converting it into a `u8` and putting that value in the span
    let (_, (_, n)) = tuple((
                        tag("$"),
                        map_res(
                            decimal,
                            |x| x.fragment().parse::<u8>().map(|n| x.map_extra(|_| n))
                        )
                      ))(span).unwrap();
    assert_eq!(n.extra, 10);
}

pub fn into_fragment(self) -> T

Takes ownership of the fragment without (re)borrowing it.

Example of use

use nom::{
    IResult,
    bytes::complete::{take_till, tag},
    combinator::rest,
};

fn parse_pair<'a>(input: LocatedSpan<&'a str>) -> IResult<LocatedSpan<&'a str>, (&'a str, &'a str)> {
    let (input, key) = take_till(|c| c == '=')(input)?;
    let (input, _) = tag("=")(input)?;
    let (input, value) = rest(input)?;

    Ok((input, (key.into_fragment(), value.into_fragment())))
}

fn main() {
    let span = LocatedSpan::new("key=value");
    let (_, pair) = parse_pair(span).unwrap();
    assert_eq!(pair, ("key", "value"));
}

pub fn into_fragment_and_extra(self) -> (T, X)

Takes ownership of the fragment and extra data without (re)borrowing them.

impl<T: AsBytes, X> LocatedSpan<T, X>

pub fn get_line_beginning(&self) -> &[u8] ⓘ

Return the line that contains this LocatedSpan.

The get_column and get_utf8_column functions returns indexes that corresponds to the line returned by this function.

Note that if this LocatedSpan ends before the end of the original data, the result of calling get_line_beginning() will not include any data from after the LocatedSpan.

let program = LocatedSpan::new(
    "Hello World!\
    \nThis is a multi-line input\
    \nthat ends after this line.\n");
let multi = program.find_substring("multi").unwrap();

assert_eq!(
    program.slice(multi..).get_line_beginning(),
    "This is a multi-line input".as_bytes(),
);

pub fn get_column(&self) -> usize

Return the column index, assuming 1 byte = 1 column.

Use it for ascii text, or use get_utf8_column for UTF8.

Example of use


let span = LocatedSpan::new("foobar");

assert_eq!(span.slice(3..).get_column(), 4);

Examples found in repository ?

examples/position.rs (line 44)

fn main() {
    let input = Span::new("Lorem ipsum \n foobar");
    let output = parse_foobar(input);
    let position = output.unwrap().1.position;
    assert_eq!(position, unsafe {
        Span::new_from_raw_offset(
            14, // offset
            2,  // line
            "", // fragment
            (), // extra
        )
    });
    assert_eq!(position.get_column(), 2);
}

pub fn get_utf8_column(&self) -> usize

Return the column index for UTF8 text. Return value is unspecified for non-utf8 text.

This version uses bytecount’s hyper algorithm to count characters. This is much faster for long lines, but is non-negligibly slower for short slices (below around 100 bytes). This is also sped up significantly more depending on architecture and enabling the simd feature gates. If you expect primarily short lines, you may get a noticeable speedup in parsing by using naive_get_utf8_column instead. Benchmark your specific use case!

Example of use


let span = LocatedSpan::new("メカジキ");
let indexOf3dKanji = span.find_substring("ジ").unwrap();

assert_eq!(span.slice(indexOf3dKanji..).get_column(), 7);
assert_eq!(span.slice(indexOf3dKanji..).get_utf8_column(), 3);

pub fn naive_get_utf8_column(&self) -> usize

Return the column index for UTF8 text. Return value is unspecified for non-utf8 text.

A simpler implementation of get_utf8_column that may be faster on shorter lines. If benchmarking shows that this is faster, you can use it instead of get_utf8_column. Prefer defaulting to get_utf8_column unless this legitimately is a performance bottleneck.

Example of use


let span = LocatedSpan::new("メカジキ");
let indexOf3dKanji = span.find_substring("ジ").unwrap();

assert_eq!(span.slice(indexOf3dKanji..).get_column(), 7);
assert_eq!(span.slice(indexOf3dKanji..).naive_get_utf8_column(), 3);

Trait Implementations§

impl<T: AsBytes, X> AsBytes for LocatedSpan<T, X>

fn as_bytes(&self) -> &[u8] ⓘ

Casts the input type to a byte slice

impl<T, U, X> AsRef for LocatedSpan<&T, X>where T: ?Sized + AsRef, U: ?Sized,

fn as_ref(&self) -> &U

Converts this type into a shared reference of the (usually inferred) input type.

impl<T: Clone, X: Clone> Clone for LocatedSpan<T, X>

fn clone(&self) -> LocatedSpan<T, X>

Returns a copy of the value. Read more

1.0.0 · source§

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

Performs copy-assignment from source. Read more

impl<A: Compare, B: Into<LocatedSpan>, X> Compare for LocatedSpan<A, X>

fn compare(&self, t: B) -> CompareResult

Compares self to another value for equality

fn compare_no_case(&self, t: B) -> CompareResult

Compares self to another value for equality independently of the case. Read more

impl<T: Debug, X: Debug> Debug for LocatedSpan<T, X>

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

Formats the value using the given formatter. Read more

impl<T, X> Deref for LocatedSpan<T, X>

type Target = T

The resulting type after dereferencing.

fn deref(&self) -> &Self::Target

Dereferences the value.

impl<T: ToString, X> Display for LocatedSpan<T, X>

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

Formats the value using the given formatter. Read more

impl<'a, T, X> ExtendInto for LocatedSpan<T, X>where T: ExtendInto,

type Item = <T as ExtendInto>::Item

The current input type is a sequence of that Item type. Read more

type Extender = <T as ExtendInto>::Extender

The type that will be produced

fn new_builder(&self) -> Self::Extender

Create a new Extend of the correct type

fn extend_into(&self, acc: &mut Self::Extender)

Accumulate the input into an accumulator

impl<T, U, X> FindSubstring for LocatedSpan<T, X>where T: FindSubstring,

fn find_substring(&self, substr: U) -> Option<usize>

Returns the byte position of the substring if it is found

impl<Fragment: FindToken<Token>, Token, X> FindToken<Token> for LocatedSpan<Fragment, X>

fn find_token(&self, token: Token) -> bool

Returns true if self contains the token

impl<T: AsBytes, X: Default> From<T> for LocatedSpan<T, X>

fn from(i: T) -> Self

Converts to this type from the input type.

impl<T: Hash, X> Hash for LocatedSpan<T, X>

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

Feeds this value into the given Hasher. Read more

1.3.0 · source§

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

Feeds a slice of this type into the given Hasher. Read more

impl<'a, T, X> InputIter for LocatedSpan<T, X>where T: InputIter,

type Item = <T as InputIter>::Item

The current input type is a sequence of that Item type. Read more

type Iter = <T as InputIter>::Iter

An iterator over the input type, producing the item and its position for use with Slice. If we’re iterating over &str, the position corresponds to the byte index of the character