Generic geometry traits for EWKB/PostGIS output and support for Tiny WKB geometries

README.md

@@ -10,19 +10,65 @@ An extension to rust-postgres, adds support for PostGIS.
 
 - PostGIS type helper
 - GCJ02 support (used offically in Mainland China)
-- Type-safe SRID support
+- Tiny WKB (TWKB) support
 
-## HowTo
+## Usage
 
 ```rust
 use postgres::{Connection, SslMode};
-use postgis::{Point, LineString, WGS84};
+use postgis::ewkb;
+use postgis::LineString;
 
 fn main() {
     // conn ....
-    let stmt = conn.prepare("SELECT * FROM busline").unwrap();
-    for row in stmt.query(&[]).unwrap() {
-        println!(">>>>>> {}", row.get::<_, LineString<Point>>("route"));
+    for row in &conn.query("SELECT * FROM busline", &[]).unwrap() {
+        let route: ewkb::LineString = row.get("route");
+        let last_stop = route.points().last().unwrap();
+        let _ = conn.execute("INSERT INTO stops (stop) VALUES ($1)", &[&last_stop]);
     }
 }
 ```
+
+Handling NULL values:
+```rust
+let route = row.get_opt::<_, Option<ewkb::LineString>>("route");
+match route.unwrap() {
+    Ok(Some(geom)) => { println!("{:?}", geom) }
+    Ok(None) => { /* Handle NULL value */ }
+    Err(err) => { println!("Error: {}", err) }
+}
+```
+
+## Writing other geometry types into PostGIS
+
+rust-postgis supports writing geometry types into PostGIS which implement the following traits:
+
+* `Point`, `LineString`, ...
+* `AsEwkbPoint`, `AsEwkbLineString`, ...
+
+See the TWKB implementation as an example.
+
+An example for reading a TWKB geometry and writing it back as EWKB:
+
+```rust
+use postgis::twkb;
+use postgis::LineString;
+
+for row in &conn.query("SELECT ST_AsTWKB(route) FROM busline", &[]).unwrap() {
+    let route: twkb::LineString = row.get(0);
+    let last_stop = route.points().last().unwrap();
+    let _ = conn.execute("INSERT INTO stops (stop) VALUES ($1)", &[&last_stop.as_ewkb()]);
+}
+```
+
+
+## Unit tests
+
+Unit tests which need a PostgreSQL connection are ignored by default.
+To run the database tests, declare the connection in an environment variable `DBCONN`. Example:
+
+    export DBCONN=postgresql://user@localhost/testdb
+
+Run the tests with
+
+    cargo test -- --ignored

src/error.rs

@@ -0,0 +1,32 @@
+//  FileName    : error.rs
+//  Author      : ShuYu Wang <[email protected]>
+//  Created     : Wed May 27 01:45:41 2015 by ShuYu Wang
+//  Copyright   : Feather Workshop (c) 2015
+//  Description : PostGIS helper
+//  Time-stamp: <2015-06-13 19:21:08 andelf>
+
+use std;
+use std::fmt;
+
+#[derive(Debug, )]
+pub enum Error {
+    Read(String),
+    Write(String),
+    Other(String)
+}
+
+impl fmt::Display for Error {
+    fn fmt(&self, fmt: &mut fmt::Formatter) -> fmt::Result {
+        write!(fmt, "{:?}", self)
+    }
+}
+
+impl std::error::Error for Error {
+    fn description(&self) -> &str {
+        match *self {
+            Error::Read(_)  => "postgis error while reading",
+            Error::Write(_) => "postgis error while writing",
+            Error::Other(_) => "postgis unknown error"
+        }
+    }
+}