Expand description
§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).
Structs§
- A uniform resource identifier for geographic locations (geo URI).
- Builder for
GeoUri
.
Enums§
- The reference system of the provided coordinates.
- Possible geo URI errors.
- Error type for GeoUriBuilder