geometry_io_ewkb/
lib.rs

1//! `PostGIS` Extended Well-Known Binary (EWKB) reader and writer.
2//!
3//! EWKB is OGC Well-Known Binary with a `PostGIS` header dialect: four
4//! flag bits in the 32-bit type word, and an optional 32-bit
5//! spatial-reference id between the type word and the body. Everything
6//! after that header is byte-identical OGC WKB, so this crate is a
7//! header codec — it delegates every body to `geometry-io-wkb` rather
8//! than carrying a second parser.
9//!
10//! Only the **outermost** record carries an SRID, which is what
11//! `PostGIS` writes. This is a strictly-2D reader: the `Z`, `M` and
12//! bounding-box flags are refused by name rather than silently dropped.
13//!
14//! Empty polygons use zero rings, including inside collections. Other
15//! geometry structure is preserved without validation; consumers can
16//! reject short or unclosed rings and holes without an exterior.
17//!
18//! ```
19//! use geometry_cs::Cartesian;
20//! use geometry_io_ewkb::{ByteOrder, Srid, from_ewkb, to_ewkb, to_ewkb_hex};
21//! use geometry_model::Point2D;
22//!
23//! let p = Point2D::<f64, Cartesian>::new(1.0, 2.0);
24//! let bytes = to_ewkb(&p, Some(Srid::new(4326)), ByteOrder::LittleEndian);
25//!
26//! let read = from_ewkb(&bytes).unwrap();
27//! assert_eq!(read.srid, Some(Srid::new(4326)));
28//! assert_eq!(read.byte_order, ByteOrder::LittleEndian);
29//!
30//! // The text form of a PostGIS `geometry` column is hex EWKB.
31//! assert_eq!(
32//!     to_ewkb_hex(&p, Some(Srid::new(4326)), ByteOrder::LittleEndian),
33//!     "0101000020E6100000000000000000F03F0000000000000040",
34//! );
35//! ```
36//!
37//! # Bringing your own polygon
38//!
39//! ```
40//! use geometry_cs::Cartesian;
41//! use geometry_io_ewkb::{ByteOrder, Srid, to_ewkb_polygon};
42//! use geometry_model::{Point2D, Polygon, Ring};
43//!
44//! type Pt = Point2D<f64, Cartesian>;
45//! let pg = Polygon::<Pt>::new(Ring::from_vec(vec![
46//!     Pt::new(0.0, 0.0),
47//!     Pt::new(0.0, 1.0),
48//!     Pt::new(1.0, 1.0),
49//!     Pt::new(0.0, 0.0),
50//! ]));
51//! let bytes = to_ewkb_polygon(&pg, Some(Srid::new(4326)), ByteOrder::BigEndian);
52//! assert_eq!(bytes[0], 0x00); // big-endian
53//! ```
54
55#![cfg_attr(not(feature = "std"), no_std)]
56#![forbid(unsafe_code)]
57
58extern crate alloc;
59
60mod ewkb;
61mod ewkb_error;
62mod hex;
63mod record_header;
64
65pub use ewkb::Ewkb;
66pub use ewkb_error::EwkbError;
67#[doc(hidden)]
68pub use geometry_io_wkb::WriteWkb;
69pub use geometry_io_wkb::{ByteOrder, WkbError};
70pub use geometry_srid::Srid;
71// feature-group: I/O — Extended Well-Known Binary
72// feature-desc: Parse and write PostGIS EWKB (WKB with an SRID header), binary and hex
73pub use ewkb::from_ewkb;
74// feature-group: I/O — Extended Well-Known Binary
75pub use ewkb::{to_ewkb, to_ewkb_polygon};
76// feature-group: I/O — Extended Well-Known Binary
77pub use hex::{from_ewkb_hex, to_ewkb_hex};
geometry_io_ewkb/lib.rs

geometry_io_ewkb/
lib.rs
