A Rust crate for parsing and generating uniform resource identifiers for geographic locations (geo URIs) according to RFC 5870.
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
Paul van Tilburg f00fbc76ab
Fix links in README
1 month ago
src Use assert_eq for float tests; drop dev depend on float_eq crate 2 months ago
.gitignore Ignore editor-specific files of VS Code and Vim 2 months ago
CHANGELOG.md Update the changelog 2 months ago
Cargo.toml Use assert_eq for float tests; drop dev depend on float_eq crate 2 months ago
LICENSE Add README.md and LICENSE file 2 months ago
README.md Fix links in README 1 month ago

README.md

geo-uri-rs

A Rust crate for uniform resource identifiers for geographic locations (geo URIs) according to IEEE RFC 5870. This crate supports parsing and generating geo URIs in the correct format. Its parser is currently somewhat more liberal than the proposed standard.

It supports geolocations specified by latitude and longitude, but also optionally altitude and an uncertainty radius. The currently only supported coordinate reference system is WGS-84.

Usage

Just run the following to add this library to your project:

$ cargo add geo-uri
    Updating crates.io index
      Adding geo-uri vX.Y.Z to dependencies.

Parsing

Use either the TryFrom trait or the parse method on strings to parse a geo URI string into a GeoUri struct:

use geo_uri::GeoUri;

let geo_uri = GeoUri::try_from("geo:52.107,5.134,3.6;u=1000").expect("valid geo URI");
assert_eq!(geo_uri.latitude(), 52.107);
assert_eq!(geo_uri.longitude(), 5.134);
assert_eq!(geo_uri.altitude(), Some(3.6));
assert_eq!(geo_uri.uncertainty(), Some(1000.0));

let geo_uri: GeoUri = "geo:52.107,5.134;u=2000.0".parse().expect("valid geo URI");
assert_eq!(geo_uri.latitude(), 52.107);
assert_eq!(geo_uri.longitude(), 5.134);
assert_eq!(geo_uri.altitude(), None);
assert_eq!(geo_uri.uncertainty(), Some(2000.0));

It is also possible to call the parse function directly:

use geo_uri::GeoUri;

let geo_uri = GeoUri::parse("geo:52.107,5.134,3.6").expect("valid geo URI");
assert_eq!(geo_uri.latitude(), 52.107);
assert_eq!(geo_uri.longitude(), 5.134);
assert_eq!(geo_uri.altitude(), Some(3.6));
assert_eq!(geo_uri.uncertainty(), None);

Generating

Use the GeoUriBuilder to construct a GeoUri struct. Then, use either the ToString or Display trait to generate a geo URI string:

use geo_uri::GeoUri;

let geo_uri = GeoUri::builder()
    .latitude(52.107)
    .longitude(5.134)
    .uncertainty(1_000.0)
    .build()
    .unwrap();

assert_eq!(
    geo_uri.to_string(),
    String::from("geo:52.107,5.134;u=1000")
);
assert_eq!(
    format!("{geo_uri}"),
    String::from("geo:52.107,5.134;u=1000")
);

It is also possible to construct a GeoUri struct from coordinate tuples using the TryFrom trait:

use geo_uri::GeoUri;

let geo_uri = GeoUri::try_from((52.107, 5.134)).expect("valid coordinates");
let geo_uri = GeoUri::try_from((52.107, 5.134, 3.6)).expect("valid coordinates");

Feature: url

You can enable the url feature to convert from and to Url structs from the url crate.

Enable the feature in your Cargo.toml first:

geo-uri = { version = "X.Y.Z", features = ["url"] }

Then you can do:

use geo_uri::GeoUri;
use url::Url;

let url = Url::parse("geo:52.107,5.134,3.6").expect("valid URL");
let geo_uri = GeoUri::try_from(&url).expect("valid geo URI");
let geo_url = Url::from(geo_uri);

assert_eq!(url, geo_url);

Note that it is always possible to transform a GeoUri into an Url, but not always the other way around! This is because the format of the coordinates and parameters after the URI scheme "geo:" may be invalid!

Feature: serde

If you enable the serde feature, GeoUri will implement serde::Serialize and serde::Deserialize. See the serde documentation for more information.

geo-uri = { version = "X.Y.Z", features = ["serde"] }

License

geo-uri-rs is licensed under the MIT license (see the LICENSE file or http://opensource.org/licenses/MIT).