Struct nom_locate::LocatedSpan

source · 
pub struct LocatedSpan<T, X = ()> {
    pub extra: X,
    /* private fields */
}
Expand description

A LocatedSpan is a set of meta information about the location of a token, including extra information.

The LocatedSpan structure can be used as an input of the nom parsers. It implements all the necessary traits for LocatedSpan<&str,X> and LocatedSpan<&[u8],X>

Fields§

§extra: X

Extra information that can be embedded by the user. Example: the parsed file name

Implementations§

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)
32
33
34
35
36
37
38
39
40
41
42
43
44
45

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);
}

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");

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)
32
33
34
35
36
37
38
39
40
41
42
43
44
45

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);
}

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

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

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)
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30

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(),
        },
    ))
}

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);
}

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(),
);

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)
32
33
34
35
36
37
38
39
40
41
42
43
44
45

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);
}

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);

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§

Casts the input type to a byte slice
Converts this type into a shared reference of the (usually inferred) input type.
Returns a copy of the value. Read more
Performs copy-assignment from source. Read more
Compares self to another value for equality
Compares self to another value for equality independently of the case. Read more
Formats the value using the given formatter. Read more
The resulting type after dereferencing.
Dereferences the value.
Formats the value using the given formatter. Read more
The current input type is a sequence of that Item type. Read more
The type that will be produced
Create a new Extend of the correct type
Accumulate the input into an accumulator
Returns the byte position of the substring if it is found
Returns true if self contains the token
Converts to this type from the input type.
Feeds this value into the given Hasher. Read more
Feeds a slice of this type into the given Hasher. Read more
The current input type is a sequence of that Item type. Read more
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
An iterator over the input type, producing the item
Returns an iterator over the elements and their byte offsets
Returns an iterator over the elements
Finds the byte position of the element
Get the byte offset from the element’s position in the stream
Calculates the input length, as indicated by its name, and the name of the trait itself
Returns a slice of count bytes. panics if count > length
Split the stream at the count byte offset. panics if count > length
The current input type is a sequence of that Item type. Read more
Looks for the first element of the input type for which the condition returns true, and returns the input up to this position. Read more
Looks for the first element of the input type for which the condition returns true, and returns the input up to this position. Read more
Looks for the first element of the input type for which the condition returns true and returns the input up to this position. Read more
Looks for the first element of the input type for which the condition returns true and returns the input up to this position. Read more
Offset between the first byte of self and the first byte of the argument
Succeeds if parse() succeeded. The byte slice implementation will first convert it to a &str, then apply the parse() function
This method tests for self and other values to be equal, and is used by ==.
This method tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.
Slices self according to the range argument

Auto Trait Implementations§

Blanket Implementations§

Gets the TypeId of self. Read more
Immutably borrows from an owned value. Read more
Mutably borrows from an owned value. Read more

Returns the argument unchanged.

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

The resulting type after obtaining ownership.
Creates owned data from borrowed data, usually by cloning. Read more
Uses borrowed data to replace owned data, usually by cloning. Read more
Converts the given value to a String. Read more
The type returned in the event of a conversion error.
Performs the conversion.
The type returned in the event of a conversion error.
Performs the conversion.