Struct geo_types::geometry::LineString

source ·

pub struct LineString<T: CoordNum = f64>(pub Vec<Coord<T>>);

Expand description

An ordered collection of Coords, representing a path between locations. To be valid, a LineString must be empty, or have two or more coords.

§Semantics

A LineString is closed if it is empty, or if the first and last coordinates are the same.
The boundary of a LineString is either:
- empty if it is closed (see 1) or
- contains the start and end coordinates.
The interior is the (infinite) set of all coordinates along the LineString, not including the boundary.
A LineString is simple if it does not intersect except optionally at the first and last coordinates (in which case it is also closed, see 1).
A simple and closed LineString is a LinearRing as defined in the OGC-SFA (but is not defined as a separate type in this crate).

§Validity

A LineString is valid if it is either empty or contains 2 or more coordinates.

Further, a closed LineString must not self-intersect. Note that its validity is not enforced, and operations and predicates are undefined on invalid LineStrings.

§Examples

§Creation

Create a LineString by calling it directly:

use geo_types::{coord, LineString};

let line_string = LineString::new(vec![
    coord! { x: 0., y: 0. },
    coord! { x: 10., y: 0. },
]);

Create a LineString with the line_string! macro:

use geo_types::line_string;

let line_string = line_string![
    (x: 0., y: 0.),
    (x: 10., y: 0.),
];

By converting from a Vec of coordinate-like things:

use geo_types::LineString;

let line_string: LineString<f32> = vec![(0., 0.), (10., 0.)].into();

use geo_types::LineString;

let line_string: LineString = vec![[0., 0.], [10., 0.]].into();

Or by collecting from a Coord iterator

use geo_types::{coord, LineString};

let mut coords_iter =
    vec![coord! { x: 0., y: 0. }, coord! { x: 10., y: 0. }].into_iter();

let line_string: LineString<f32> = coords_iter.collect();

§Iteration

LineString provides five iterators: coords, coords_mut, points, lines, and triangles:

use geo_types::{coord, LineString};

let line_string = LineString::new(vec![
    coord! { x: 0., y: 0. },
    coord! { x: 10., y: 0. },
]);

line_string.coords().for_each(|coord| println!("{:?}", coord));

for point in line_string.points() {
    println!("Point x = {}, y = {}", point.x(), point.y());
}

Note that its IntoIterator impl yields Coords when looping:

use geo_types::{coord, LineString};

let line_string = LineString::new(vec![
    coord! { x: 0., y: 0. },
    coord! { x: 10., y: 0. },
]);

for coord in &line_string {
    println!("Coordinate x = {}, y = {}", coord.x, coord.y);
}

for coord in line_string {
    println!("Coordinate x = {}, y = {}", coord.x, coord.y);
}

§Decomposition

You can decompose a LineString into a Vec of Coords or Points:

use geo_types::{coord, LineString, Point};

let line_string = LineString::new(vec![
    coord! { x: 0., y: 0. },
    coord! { x: 10., y: 0. },
]);

let coordinate_vec = line_string.clone().into_inner();
let point_vec = line_string.clone().into_points();

Tuple Fields§

§0: Vec<Coord<T>>

Implementations§

source §

impl<T: CoordNum> LineString<T>

source

pub fn new(value: Vec<Coord<T>>) -> Self

Instantiate Self from the raw content value

source

pub fn points_iter(&self) -> PointsIter<'_, T> ⓘ

👎Deprecated: Use points() instead

Return an iterator yielding the coordinates of a LineString as Points

source

pub fn points(&self) -> PointsIter<'_, T> ⓘ

Return an iterator yielding the coordinates of a LineString as Points

source

pub fn coords(&self) -> impl DoubleEndedIterator<Item = &Coord<T>>

Return an iterator yielding the members of a LineString as Coords

source

pub fn coords_mut(&mut self) -> impl DoubleEndedIterator<Item = &mut Coord<T>>

Return an iterator yielding the coordinates of a LineString as mutable Coords

source

pub fn into_points(self) -> Vec<Point<T>>

Return the coordinates of a LineString as a Vec of Points

source

pub fn into_inner(self) -> Vec<Coord<T>>

Return the coordinates of a LineString as a Vec of Coords

source

pub fn lines(&self) -> impl ExactSizeIterator<Item = Line<T>> + '_

Return an iterator yielding one Line for each line segment in the LineString.

§Examples

use geo_types::{coord, Line, LineString};

let mut coords = vec![(0., 0.), (5., 0.), (7., 9.)];
let line_string: LineString<f32> = coords.into_iter().collect();

let mut lines = line_string.lines();
assert_eq!(
    Some(Line::new(
        coord! { x: 0., y: 0. },
        coord! { x: 5., y: 0. }
    )),
    lines.next()
);
assert_eq!(
    Some(Line::new(
        coord! { x: 5., y: 0. },
        coord! { x: 7., y: 9. }
    )),
    lines.next()
);
assert!(lines.next().is_none());

source

pub fn triangles(&self) -> impl ExactSizeIterator<Item = Triangle<T>> + '_

An iterator which yields the coordinates of a LineString as Triangles

source

pub fn close(&mut self)

Close the LineString. Specifically, if the LineString has at least one Coord, and the value of the first Coord does not equal the value of the last Coord, then a new Coord is added to the end with the value of the first Coord.

source

pub fn num_coords(&self) -> usize

👎Deprecated: Use geo::CoordsIter::coords_count instead

Return the number of coordinates in the LineString.

§Examples

use geo_types::LineString;

let mut coords = vec![(0., 0.), (5., 0.), (7., 9.)];
let line_string: LineString<f32> = coords.into_iter().collect();

assert_eq!(3, line_string.num_coords());

source

pub fn is_closed(&self) -> bool

Checks if the linestring is closed; i.e. it is either empty or, the first and last points are the same.

§Examples

use geo_types::LineString;

let mut coords = vec![(0., 0.), (5., 0.), (0., 0.)];
let line_string: LineString<f32> = coords.into_iter().collect();
assert!(line_string.is_closed());

Note that we diverge from some libraries (JTS et al), which have a LinearRing type, separate from LineString. Those libraries treat an empty LinearRing as closed by definition, while treating an empty LineString as open. Since we don’t have a separate LinearRing type, and use a LineString in its place, we adopt the JTS LinearRing is_closed behavior in all places: that is, we consider an empty LineString as closed.

This is expected when used in the context of a Polygon.exterior and elsewhere; And there seems to be no reason to maintain the separate behavior for LineStrings used in non-LinearRing contexts.