geonative_shapefile/lib.rs
1//! # geonative-shapefile
2//!
3//! Pure-Rust reader for the Esri Shapefile family (`.shp` + `.shx` + `.dbf`
4//! + optional `.prj` / `.cpg`). No GDAL, no shapelib.
5//!
6//! ## What v0.1 covers
7//!
8//! - 2D shape types: `Null`, `Point`, `Polyline`, `Polygon`, `MultiPoint`
9//! - DBF field types: `C` (char), `N` (numeric), `F` (float), `D` (date),
10//! `L` (logical); other DBF types come through as `Value::String` or `Null`
11//! - Ring orientation flipped from Shapefile (CW outer / CCW hole) to OGC
12//! (CCW outer / CW hole) so polygons match the rest of the geonative IR
13//! - `.shp` is **mmapped** for bounded RAM usage on multi-GB inputs;
14//! `.shx` + `.dbf` are read into Vecs (small)
15//!
16//! ## v0.1 scope cuts
17//!
18//! - Z/M variants (PointZ, PolygonZ, MultipointZ, etc.) return Unsupported
19//! - MultiPatch (type 31) — surface-class geometry; defer
20//! - Non-UTF-8 codepages (`.cpg` / LDID full table) — defer; v0.1 treats
21//! string bytes as UTF-8 with replacement for invalid sequences
22//! - `.qix` / `.sbn` spatial index files — ignored
23//! - Sparse / corrupt-`.shx` repair — error rather than auto-rebuild
24//!
25//! ## Usage
26//!
27//! ```no_run
28//! let shp = geonative_shapefile::Shapefile::open("roads.shp")?;
29//! println!("{} features, schema: {:?}", shp.feature_count(), shp.schema());
30//! for f in shp.read() {
31//! let f = f?;
32//! // f.fid, f.geometry, f.attributes
33//! }
34//! # Ok::<(), geonative_shapefile::ShpError>(())
35//! ```
36
37// We `deny` rather than `forbid` so the single mmap call in `dataset.rs`
38// can explicitly opt in via `#[allow(unsafe_code)]`. Every other module
39// remains safe-Rust-only.
40#![deny(unsafe_code)]
41#![warn(missing_debug_implementations)]
42
43pub mod bytes;
44pub mod dataset;
45pub mod dbf;
46pub mod error;
47pub mod header;
48pub mod shape;
49pub mod shx;
50
51pub use dataset::{FeatureIter, Shapefile};
52pub use error::{Result, ShpError};
53pub use header::{ShapeType, ShpHeader};
54
55/// Convenience: open a `.shp` (or any file in the shapefile triad) and
56/// produce a `Shapefile` handle.
57pub fn open(path: impl AsRef<std::path::Path>) -> Result<Shapefile> {
58 Shapefile::open(path)
59}