oxigeo_geojson/lib.rs
1//! OxiGeo GeoJSON Driver - RFC 7946 Implementation
2//!
3//! This crate provides a pure Rust implementation of GeoJSON (RFC 7946) reading
4//! and writing for the OxiGeo ecosystem. It supports all geometry types,
5//! features, feature collections, and coordinate reference systems.
6//!
7//! # Features
8//!
9//! - Full RFC 7946 compliance
10//! - Support for all geometry types (Point, LineString, Polygon, MultiPoint, MultiLineString, MultiPolygon, GeometryCollection)
11//! - Feature and FeatureCollection support
12//! - CRS (Coordinate Reference System) handling
13//! - GeoJSONL / newline-delimited GeoJSON reading with O(1) memory per feature
14//! - Efficient writer with customizable formatting
15//! - Comprehensive validation
16//! - Zero-copy optimizations where possible
17//! - No `unwrap()` or `panic!()` in production code
18//!
19//! # Example
20//!
21//! ```rust
22//! use oxigeo_geojson::{GeoJsonReader, GeoJsonWriter, FeatureCollection};
23//! use std::fs::File;
24//! use std::io::{BufReader, BufWriter};
25//!
26//! # fn main() -> Result<(), Box<dyn std::error::Error>> {
27//! // Reading GeoJSON
28//! # let temp_dir = std::env::temp_dir();
29//! # let input_path = temp_dir.join("test_input.geojson");
30//! # std::fs::write(&input_path, r#"{"type":"FeatureCollection","features":[]}"#)?;
31//! let file = File::open(&input_path)?;
32//! let reader = BufReader::new(file);
33//! let mut geojson_reader = GeoJsonReader::new(reader);
34//! let feature_collection = geojson_reader.read_feature_collection()?;
35//!
36//! // Writing GeoJSON
37//! # let output_path = temp_dir.join("test_output.geojson");
38//! let file = File::create(&output_path)?;
39//! let writer = BufWriter::new(file);
40//! let mut geojson_writer = GeoJsonWriter::new(writer);
41//! geojson_writer.write_feature_collection(&feature_collection)?;
42//! # std::fs::remove_file(&input_path)?;
43//! # std::fs::remove_file(&output_path)?;
44//! # Ok(())
45//! # }
46//! ```
47//!
48//! # RFC 7946 Compliance
49//!
50//! This implementation follows RFC 7946 strictly:
51//! - Right-hand rule for polygon orientation
52//! - WGS84 as default CRS (EPSG:4326)
53//! - Longitude-latitude order for coordinates
54//! - Validation of geometry topologies
55//! - Support for bounding boxes
56//! - Foreign members preserved during round-trip
57//!
58//! # Performance
59//!
60//! - GeoJSONL (`read_geojsonl`) streaming for O(1) memory per feature on
61//! newline-delimited input; standard `FeatureCollection` reads
62//! (`read_feature_collection`, `iter_features`) fully buffer and parse the
63//! document up front
64//! - Zero-copy deserialization where possible
65//! - Efficient buffering and I/O
66//! - Parallel processing support (with `async` feature)
67//!
68//! # COOLJAPAN Policies
69//!
70//! - Pure Rust implementation (no C/C++ dependencies)
71//! - No `unwrap()` or `expect()` in production code
72//! - Comprehensive error handling
73//! - Extensive testing (unit + integration + property-based)
74//! - Clean API design following Rust idioms
75
76#![cfg_attr(not(feature = "std"), no_std)]
77#![warn(clippy::all)]
78// Pedantic disabled to reduce noise - default clippy::all is sufficient
79// #![warn(clippy::pedantic)]
80#![deny(clippy::unwrap_used)]
81#![deny(clippy::panic)]
82#![allow(clippy::module_name_repetitions)]
83#![allow(clippy::similar_names)]
84// Allow doc overindent in complex nested lists
85#![allow(clippy::doc_overindented_list_items)]
86// Allow partial documentation
87#![allow(missing_docs)]
88// Allow dead code for internal structures
89#![allow(dead_code)]
90// Allow manual div_ceil for CRS calculations
91#![allow(clippy::manual_div_ceil)]
92// Allow expect() for internal invariants
93#![allow(clippy::expect_used)]
94// Allow collapsible match for CRS handling
95#![allow(clippy::collapsible_match)]
96// Allow manual strip for path parsing
97#![allow(clippy::manual_strip)]
98// Allow should_implement_trait for builder patterns
99#![allow(clippy::should_implement_trait)]
100
101#[cfg(feature = "std")]
102extern crate std;
103
104pub mod error;
105pub mod reader;
106pub mod types;
107pub mod utils;
108pub mod validation;
109pub mod writer;
110
111// Re-export commonly used types
112pub use error::{GeoJsonError, Result};
113pub use reader::GeoJsonReader;
114pub use types::{
115 Coordinate, CoordinateSequence, Crs, Feature, FeatureCollection, Geometry, GeometryType,
116 Position, Properties,
117};
118pub use validation::{RingRole, Validator};
119pub use writer::GeoJsonWriter;
120
121// Re-export GeoJSONL helpers
122pub use reader::{
123 feature_bbox_intersects, features_in_bbox, geometry_bbox, open, open_geojsonl, read_geojsonl,
124};
125pub use writer::{write_geojsonl, write_geojsonl_to_file};
126
127/// Crate version
128pub const VERSION: &str = env!("CARGO_PKG_VERSION");
129
130/// Crate name
131pub const NAME: &str = env!("CARGO_PKG_NAME");
132
133/// Default CRS for GeoJSON (WGS84)
134pub const DEFAULT_CRS: &str = "urn:ogc:def:crs:OGC:1.3:CRS84";
135
136/// GeoJSON MIME type
137pub const MIME_TYPE: &str = "application/geo+json";
138
139/// GeoJSON file extension
140pub const FILE_EXTENSION: &str = ".geojson";
141
142#[cfg(test)]
143mod tests {
144 use super::*;
145
146 #[test]
147 fn test_constants() {
148 assert!(!VERSION.is_empty());
149 assert_eq!(NAME, "oxigeo-geojson");
150 assert_eq!(DEFAULT_CRS, "urn:ogc:def:crs:OGC:1.3:CRS84");
151 assert_eq!(MIME_TYPE, "application/geo+json");
152 assert_eq!(FILE_EXTENSION, ".geojson");
153 }
154}