Skip to content

Commit 8c033ec

Browse files
pkapka
committed
Basic library documentation
1 parent a944b2b commit 8c033ec

File tree

4 files changed

+83
-7
lines changed

4 files changed

+83
-7
lines changed

‎src/ewkb.rs

Lines changed: 33 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,9 @@
11
//
22
// Copyright (c) ShuYu Wang <andelf@gmail.com>, Feather Workshop and Pirmin Kalberer. All rights reserved.
33
//
4+
//! Read and write geometries in [OGC WKB](http://www.opengeospatial.org/standards/sfa) format.
5+
//!
6+
//! Support for SRID information according to [PostGIS EWKB extensions](https://svn.osgeo.org/postgis/trunk/doc/ZMSgeoms.txt)
47
58
use types as postgis;
69
use std;
@@ -12,10 +15,6 @@ use std::iter::FromIterator;
1215
use byteorder::{ReadBytesExt, WriteBytesExt, BigEndian, LittleEndian};
1316
use error::Error;
1417

15-
// OGC WKB specification: http://www.opengeospatial.org/standards/sfa
16-
// PostGIS EWKB extensions: https://svn.osgeo.org/postgis/trunk/doc/ZMSgeoms.txt
17-
18-
1918
// --- Structs for reading PostGIS geometries into
2019

2120
#[derive(PartialEq, Clone, Debug)]
@@ -78,6 +77,7 @@ pub trait EwkbRead: fmt::Debug + Sized {
7877
Self::read_ewkb_body(raw, is_be, srid)
7978
}
8079

80+
#[doc(hidden)]
8181
fn read_ewkb_body<R: Read>(raw: &mut R, is_be: bool, srid: Option<i32>) -> Result<Self, Error>;
8282
}
8383

@@ -114,6 +114,7 @@ pub trait EwkbWrite: fmt::Debug + Sized {
114114
self.write_ewkb_body(w)?;
115115
Ok(())
116116
}
117+
#[doc(hidden)]
117118
fn write_ewkb_body<W: Write+?Sized>(&self, w: &mut W) -> Result<(), Error>;
118119

119120
fn to_hex_ewkb(&self) -> String {
@@ -720,9 +721,13 @@ point_container_write!(LineString and AsEwkbLineString for LineStringT
720721
to EwkbLineString with type code 0x02,
721722
command write_ewkb_body);
722723

724+
/// OGC LineString type
723725
pub type LineString = LineStringT<Point>;
726+
/// OGC LineStringZ type
724727
pub type LineStringZ = LineStringT<PointZ>;
728+
/// OGC LineStringM type
725729
pub type LineStringM = LineStringT<PointM>;
730+
/// OGC LineStringZM type
726731
pub type LineStringZM = LineStringT<PointZM>;
727732

728733
/// Polygon
@@ -733,9 +738,13 @@ geometry_container_write!(Polygon and AsEwkbPolygon for PolygonT
733738
contains EwkbLineString,LineStringT as LineString named rings,
734739
command write_ewkb_body);
735740

741+
/// OGC Polygon type
736742
pub type Polygon = PolygonT<Point>;
743+
/// OGC PolygonZ type
737744
pub type PolygonZ = PolygonT<PointZ>;
745+
/// OGC PolygonM type
738746
pub type PolygonM = PolygonT<PointM>;
747+
/// OGC PolygonZM type
739748
pub type PolygonZM = PolygonT<PointZM>;
740749

741750
/// MultiPoint
@@ -745,9 +754,13 @@ point_container_write!(MultiPoint and AsEwkbMultiPoint for MultiPointT
745754
to EwkbMultiPoint with type code 0x04,
746755
command write_ewkb);
747756

757+
/// OGC MultiPoint type
748758
pub type MultiPoint = MultiPointT<Point>;
759+
/// OGC MultiPointZ type
749760
pub type MultiPointZ = MultiPointT<PointZ>;
761+
/// OGC MultiPointM type
750762
pub type MultiPointM = MultiPointT<PointM>;
763+
/// OGC MultiPointZM type
751764
pub type MultiPointZM = MultiPointT<PointZM>;
752765

753766
/// MultiLineString
@@ -758,9 +771,13 @@ geometry_container_write!(MultiLineString and AsEwkbMultiLineString for MultiLin
758771
contains EwkbLineString,LineStringT as LineString named lines,
759772
command write_ewkb);
760773

774+
/// OGC MultiLineString type
761775
pub type MultiLineString = MultiLineStringT<Point>;
776+
/// OGC MultiLineStringZ type
762777
pub type MultiLineStringZ = MultiLineStringT<PointZ>;
778+
/// OGC MultiLineStringM type
763779
pub type MultiLineStringM = MultiLineStringT<PointM>;
780+
/// OGC MultiLineStringZM type
764781
pub type MultiLineStringZM = MultiLineStringT<PointZM>;
765782

766783

@@ -772,9 +789,13 @@ geometry_container_write!(multipoly MultiPolygon and AsEwkbMultiPolygon for Mult
772789
contains EwkbPolygon,PolygonT as Polygon named polygons,
773790
command write_ewkb);
774791

792+
/// OGC MultiPolygon type
775793
pub type MultiPolygon = MultiPolygonT<Point>;
794+
/// OGC MultiPolygonZ type
776795
pub type MultiPolygonZ = MultiPolygonT<PointZ>;
796+
/// OGC MultiPolygonM type
777797
pub type MultiPolygonM = MultiPolygonT<PointM>;
798+
/// OGC MultiPolygonZM type
778799
pub type MultiPolygonZM = MultiPolygonT<PointZM>;
779800

780801

@@ -824,13 +845,16 @@ impl<P> EwkbRead for GeometryT<P>
824845
}
825846
}
826847

848+
/// OGC Geometry type
827849
pub type Geometry = GeometryT<Point>;
850+
/// OGC GeometryZ type
828851
pub type GeometryZ = GeometryT<PointZ>;
852+
/// OGC GeometryM type
829853
pub type GeometryM = GeometryT<PointM>;
854+
/// OGC GeometryZM type
830855
pub type GeometryZM = GeometryT<PointZM>;
831856

832857

833-
/// GeometryCollection
834858
#[derive(Debug)]
835859
pub struct GeometryCollectionT<P: postgis::Point + EwkbRead> {
836860
pub geometries: Vec<GeometryT<P>>
@@ -877,9 +901,13 @@ impl<P> EwkbRead for GeometryCollectionT<P>
877901
}
878902
}
879903

904+
/// OGC GeometryCollection type
880905
pub type GeometryCollection = GeometryCollectionT<Point>;
906+
/// OGC GeometryCollectionZ type
881907
pub type GeometryCollectionZ = GeometryCollectionT<PointZ>;
908+
/// OGC GeometryCollectionM type
882909
pub type GeometryCollectionM = GeometryCollectionT<PointM>;
910+
/// OGC GeometryCollectionZM type
883911
pub type GeometryCollectionZM = GeometryCollectionT<PointZM>;
884912

885913

‎src/lib.rs

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,38 @@
22
// Copyright (c) ShuYu Wang <andelf@gmail.com>, Feather Workshop and Pirmin Kalberer. All rights reserved.
33
//
44

5+
//! An extension to rust-postgres, adds support for PostGIS.
6+
//!
7+
//! - PostGIS type helper
8+
//! - GCJ02 support (used offically in Mainland China)
9+
//! - Tiny WKB (TWKB) support
10+
//!
11+
//! ```rust,no_run
12+
//! use postgres::{Connection, TlsMode};
13+
//! use postgis::ewkb;
14+
//! use postgis::LineString;
15+
//!
16+
//! fn main() {
17+
//! // conn ....
18+
//! for row in &conn.query("SELECT * FROM busline", &[]).unwrap() {
19+
//! let route: ewkb::LineString = row.get("route");
20+
//! let last_stop = route.points().last().unwrap();
21+
//! let _ = conn.execute("INSERT INTO stops (stop) VALUES ($1)", &[&last_stop]);
22+
//! }
23+
//! }
24+
//! ```
25+
//!
26+
//! Handling NULL values:
27+
//!
28+
//! ```rust,no_run
29+
//! let route = row.get_opt::<_, Option<ewkb::LineString>>("route");
30+
//! match route.unwrap() {
31+
//! Ok(Some(geom)) => { println!("{:?}", geom) }
32+
//! Ok(None) => { /* Handle NULL value */ }
33+
//! Err(err) => { println!("Error: {}", err) }
34+
//! }
35+
//! ```
36+
537
#[macro_use(to_sql_checked)]
638
extern crate postgres;
739
extern crate byteorder;

‎src/mars.rs

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,8 @@
55
// Description : WGS84 GCJ02 conversion for rust
66
// Time-stamp: <2015-06-01 10:45:55 andelf>
77

8+
//! Conversion between GCJ-02 and WGS-84 coordinates.
9+
810
use ewkb;
911

1012
// http://emq.googlecode.com/svn/emq/src/Algorithm/Coords/Converter.java

‎src/twkb.rs

Lines changed: 16 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,19 @@
22
// Copyright (c) Pirmin Kalberer. All rights reserved.
33
//
44

5+
//! Read geometries in [Tiny WKB](https://github.com/TWKB/Specification/blob/master/twkb.md) format.
6+
//!
7+
//! ```rust,no_run
8+
//! use postgis::twkb;
9+
//! use postgis::LineString;
10+
//!
11+
//! for row in &conn.query("SELECT ST_AsTWKB(route) FROM busline", &[]).unwrap() {
12+
//! let route: twkb::LineString = row.get(0);
13+
//! let last_stop = route.points().last().unwrap();
14+
//! let _ = conn.execute("INSERT INTO stops (stop) VALUES ($1)", &[&last_stop.as_ewkb()]);
15+
//! }
16+
//! ```
17+
518
use types as postgis;
619
use ewkb;
720
use std::io::prelude::*;
@@ -13,8 +26,6 @@ use std::slice::Iter;
1326
use byteorder::ReadBytesExt;
1427
use error::Error;
1528

16-
// Tiny WKB specification: https://github.com/TWKB/Specification/blob/master/twkb.md
17-
1829

1930
#[derive(PartialEq, Clone, Debug)]
2031
pub struct Point {
@@ -51,6 +62,7 @@ pub struct MultiPolygon {
5162
pub ids: Option<Vec<u64>>,
5263
}
5364

65+
#[doc(hidden)]
5466
#[derive(Default,Debug)]
5567
pub struct TwkbInfo {
5668
geom_type: u8,
@@ -108,8 +120,10 @@ pub trait TwkbGeom: fmt::Debug + Sized {
108120
Self::read_twkb_body(raw, &twkb_info)
109121
}
110122

123+
#[doc(hidden)]
111124
fn read_twkb_body<R: Read>(raw: &mut R, twkb_info: &TwkbInfo) -> Result<Self, Error>;
112125

126+
#[doc(hidden)]
113127
fn read_relative_point<R: Read>(raw: &mut R, twkb_info: &TwkbInfo, x: f64, y: f64, z: Option<f64>, m: Option<f64>)
114128
-> Result<(f64, f64, Option<f64>, Option<f64>), Error>
115129
{

0 commit comments

Comments
 (0)