geonative_geojson/lib.rs
1//! # geonative-geojson
2//!
3//! Pure-Rust reader and writer for **GeoJSON** (RFC 7946), part of the
4//! [`geonative`](https://geonative.zebflow.com) geospatial library.
5//!
6//! ## What v0.1 covers
7//!
8//! Reader:
9//! - Top-level `FeatureCollection`, bare `Feature`, or bare geometry object
10//! - All seven RFC 7946 geometry types (Point/Multi*/Polygon/Multi*/Collection)
11//! - Schema inference from `properties` (one pass; widening rules in
12//! [`properties`])
13//! - CRS detection: default `EPSG:4326`, honours legacy 2008 `crs.properties.name`
14//! URNs like `urn:ogc:def:crs:EPSG::3857`
15//! - String / numeric `id` → `Feature::fid` (i64 only — string ids that don't
16//! parse as integers fall back to row index)
17//!
18//! Writer:
19//! - Streaming — O(one feature) memory regardless of input size
20//! - Compact output (no whitespace); wrap your sink in a pretty-printer if
21//! you need indentation
22//! - Always writes `FeatureCollection`; no `crs` member (RFC 7946 removed it)
23//!
24//! ## v0.1 scope cuts
25//!
26//! - **Z/M coordinates** silently truncated on read; never emitted on write.
27//! GeoJSON's third position is optional and underspecified across tools;
28//! v0.2 will add an opt-in `--preserve-z` switch.
29//! - **Foreign members** (`bbox`, custom top-level keys) are read but not
30//! round-tripped on write — only spec-defined fields are emitted.
31//! - **Streaming reader (v0.4)** — `GeoJsonReader::open(path)` now scans
32//! the file in two streaming passes (schema inference + feature yield)
33//! instead of materialising the whole JSON tree. Peak RAM is bounded
34//! to ~one feature regardless of file size; the previous in-memory
35//! path (`from_bytes` / `from_value`) is still available for callers
36//! who already have the bytes and want the eager `features()` slice.
37//!
38//! ## Usage
39//!
40//! ```no_run
41//! let r = geonative_geojson::GeoJsonReader::open("things.geojson")?;
42//! println!("{} features, schema: {:?}", r.feature_count(), r.schema());
43//! for f in r.features() {
44//! // f.fid, f.geometry, f.attributes
45//! }
46//! # Ok::<(), geonative_geojson::GeoJsonError>(())
47//! ```
48
49#![forbid(unsafe_code)]
50#![warn(missing_debug_implementations)]
51
52pub mod error;
53pub mod geometry;
54pub mod properties;
55pub mod reader;
56pub(crate) mod scanner;
57pub mod writer;
58
59pub use error::{GeoJsonError, Result};
60pub use reader::GeoJsonReader;
61pub use writer::{write_features_to_path, GeoJsonWriter};
62
63pub const VERSION: &str = env!("CARGO_PKG_VERSION");