Skip to main content

oxigeo_shapefile/
reader.rs

1//! Shapefile reader - coordinates reading from .shp, .dbf, and .shx files
2//!
3//! This module provides a high-level interface for reading Shapefiles,
4//! combining geometry from .shp, attributes from .dbf, and spatial index from .shx.
5
6use crate::dbf::{DbfReader, FieldDescriptor, MemoFile};
7use crate::error::{Result, ShapefileError};
8use crate::shp::{Shape, ShapefileHeader, ShpReader};
9use crate::shx::{IndexEntry, ShxReader};
10use oxigeo_core::vector::{
11    Coordinate, Feature, FieldValue, Geometry, LineString as CoreLineString,
12    MultiLineString as CoreMultiLineString, MultiPoint as CoreMultiPoint, Point as CorePoint,
13};
14use std::collections::HashMap;
15use std::fs::File;
16use std::io::BufReader;
17use std::path::{Path, PathBuf};
18
19/// Splits a multi-part polygon shape into its individual rings, applying
20/// `make_coord(global_index, point)` to build each coordinate (so Z/M values,
21/// which are stored in one flat parallel array, can be indexed by the global
22/// vertex position). Out-of-range or inverted part offsets are skipped
23/// defensively rather than panicking.
24fn split_rings<F>(mp: &crate::shp::MultiPartShape, make_coord: F) -> Vec<Vec<Coordinate>>
25where
26    F: Fn(usize, &crate::shp::shapes::Point) -> Coordinate,
27{
28    let mut rings = Vec::with_capacity(mp.parts.len());
29    for i in 0..mp.parts.len() {
30        let start = mp.parts[i] as usize;
31        let end = if i + 1 < mp.parts.len() {
32            mp.parts[i + 1] as usize
33        } else {
34            mp.points.len()
35        };
36        if start >= end || end > mp.points.len() {
37            continue;
38        }
39        let ring: Vec<Coordinate> = mp.points[start..end]
40            .iter()
41            .enumerate()
42            .map(|(j, p)| make_coord(start + j, p))
43            .collect();
44        rings.push(ring);
45    }
46    rings
47}
48
49/// A complete Shapefile feature (geometry + attributes)
50#[derive(Debug, Clone)]
51pub struct ShapefileFeature {
52    /// Record number (1-based)
53    pub record_number: i32,
54    /// Geometry
55    pub geometry: Option<Geometry>,
56    /// Attributes (field name -> value)
57    pub attributes: HashMap<String, FieldValue>,
58}
59
60impl ShapefileFeature {
61    /// Creates a new Shapefile feature
62    pub fn new(
63        record_number: i32,
64        geometry: Option<Geometry>,
65        attributes: HashMap<String, FieldValue>,
66    ) -> Self {
67        Self {
68            record_number,
69            geometry,
70            attributes,
71        }
72    }
73
74    /// Converts to an OxiGeo Feature
75    pub fn to_oxigeo_feature(&self) -> Result<Feature> {
76        let geometry = self
77            .geometry
78            .clone()
79            .ok_or_else(|| ShapefileError::invalid_geometry("feature has no geometry"))?;
80
81        let mut feature = Feature::new(geometry);
82
83        // Convert attributes
84        for (key, value) in &self.attributes {
85            feature.set_property(key, value.clone());
86        }
87
88        Ok(feature)
89    }
90}
91
92/// Shapefile reader that coordinates .shp, .dbf, and optionally .shx files
93pub struct ShapefileReader {
94    /// Base path (without extension)
95    base_path: PathBuf,
96    /// .shp file header
97    header: ShapefileHeader,
98    /// Field descriptors from .dbf
99    field_descriptors: Vec<FieldDescriptor>,
100    /// Index entries from .shx (if available)
101    index_entries: Option<Vec<IndexEntry>>,
102    /// CRS as WKT string from .prj file (if present)
103    pub crs: Option<String>,
104    /// Character encoding label from .cpg file (if present)
105    pub encoding: Option<String>,
106    /// Resolved encoding used to transcode DBF text fields.
107    ///
108    /// Chosen by priority: an explicit override → the `.cpg` label → the DBF
109    /// header code page (LDID byte) → UTF-8.
110    resolved_encoding: &'static ::encoding_rs::Encoding,
111}
112
113impl ShapefileReader {
114    /// Opens a Shapefile from a base path (without extension)
115    ///
116    /// Reads the .shp, .dbf, and optionally .shx, .prj, and .cpg files. The DBF
117    /// text encoding is auto-detected from the `.cpg` file or the DBF header
118    /// code page; use [`ShapefileReader::open_with_encoding`] to force one.
119    pub fn open<P: AsRef<Path>>(base_path: P) -> Result<Self> {
120        Self::open_impl(base_path.as_ref(), None)
121    }
122
123    /// Opens a Shapefile, forcing a specific DBF text encoding.
124    ///
125    /// `encoding_label` is any label `encoding_rs` accepts (e.g. `"UTF-8"`,
126    /// `"windows-1252"`, `"GBK"`) or a numeric code page (e.g. `"1252"`,
127    /// `"65001"`). This overrides both the `.cpg` file and the header code page,
128    /// which is useful when those are absent or wrong.
129    ///
130    /// # Errors
131    ///
132    /// Returns an error if `encoding_label` is not a recognised encoding, or if
133    /// the shapefile cannot be opened.
134    pub fn open_with_encoding<P: AsRef<Path>>(base_path: P, encoding_label: &str) -> Result<Self> {
135        let encoding = crate::dbf::resolve_cpg(encoding_label).ok_or_else(|| {
136            ShapefileError::encoding_error(format!("unknown encoding label: '{encoding_label}'"))
137        })?;
138        Self::open_impl(base_path.as_ref(), Some(encoding))
139    }
140
141    fn open_impl(
142        base_path: &Path,
143        encoding_override: Option<&'static ::encoding_rs::Encoding>,
144    ) -> Result<Self> {
145        // Construct file paths
146        let shp_path = Self::with_extension(base_path, "shp");
147        let dbf_path = Self::with_extension(base_path, "dbf");
148        let shx_path = Self::with_extension(base_path, "shx");
149        let prj_path = Self::with_extension(base_path, "prj");
150        let cpg_path = Self::with_extension(base_path, "cpg");
151
152        // Open .shp file
153        let shp_file = File::open(&shp_path).map_err(|_| ShapefileError::MissingFile {
154            file_type: ".shp".to_string(),
155        })?;
156        let shp_reader = BufReader::new(shp_file);
157        let shp_reader = ShpReader::new(shp_reader)?;
158        let header = shp_reader.header().clone();
159
160        // Open .dbf file
161        let dbf_file = File::open(&dbf_path).map_err(|_| ShapefileError::MissingFile {
162            file_type: ".dbf".to_string(),
163        })?;
164        let dbf_reader = BufReader::new(dbf_file);
165        let mut dbf_reader = DbfReader::new(dbf_reader)?;
166        let header_code_page = dbf_reader.header().code_page;
167        // Discover and attach the sibling memo file (`.dbt` / `.DBT`) if present.
168        if let Some(memo_path) = Self::discover_memo_path(&dbf_path)
169            && let Ok(memo) = MemoFile::open(&memo_path)
170        {
171            dbf_reader.set_memo_file(memo);
172        }
173        let field_descriptors = dbf_reader.field_descriptors().to_vec();
174
175        // Open .shx file (optional)
176        let index_entries = if shx_path.exists() {
177            let shx_file = File::open(&shx_path).ok();
178            if let Some(file) = shx_file {
179                let shx_reader = BufReader::new(file);
180                let mut shx_reader = ShxReader::new(shx_reader)?;
181                Some(shx_reader.read_all_entries()?)
182            } else {
183                None
184            }
185        } else {
186            None
187        };
188
189        // Read .prj file (optional) — contains CRS as WKT string
190        let crs = if prj_path.exists() {
191            std::fs::read_to_string(&prj_path)
192                .ok()
193                .map(|s| s.trim().to_string())
194                .filter(|s| !s.is_empty())
195        } else {
196            None
197        };
198
199        // Read .cpg file (optional) — contains the character-encoding label.
200        let encoding = if cpg_path.exists() {
201            std::fs::read_to_string(&cpg_path)
202                .ok()
203                .map(|s| s.trim().to_string())
204                .filter(|s| !s.is_empty())
205        } else {
206            None
207        };
208
209        // Resolve the DBF text encoding: explicit override → .cpg label →
210        // DBF header code page (LDID) → UTF-8.
211        let resolved_encoding = encoding_override
212            .or_else(|| encoding.as_deref().and_then(crate::dbf::resolve_cpg))
213            .or_else(|| crate::dbf::resolve_ldid(header_code_page))
214            .unwrap_or(::encoding_rs::UTF_8);
215
216        Ok(Self {
217            base_path: base_path.to_path_buf(),
218            header,
219            field_descriptors,
220            index_entries,
221            crs,
222            encoding,
223            resolved_encoding,
224        })
225    }
226
227    /// Returns the Shapefile header
228    pub fn header(&self) -> &ShapefileHeader {
229        &self.header
230    }
231
232    /// Returns the field descriptors
233    pub fn field_descriptors(&self) -> &[FieldDescriptor] {
234        &self.field_descriptors
235    }
236
237    /// Returns the index entries (if .shx was loaded)
238    pub fn index_entries(&self) -> Option<&[IndexEntry]> {
239        self.index_entries.as_deref()
240    }
241
242    /// Returns the CRS as a WKT string, if a .prj file was present
243    pub fn crs(&self) -> Option<&str> {
244        self.crs.as_deref()
245    }
246
247    /// Returns the character encoding label from the .cpg file, if present.
248    ///
249    /// Common values: `"UTF-8"`, `"CP1252"`, `"ISO-8859-1"`. This is the raw
250    /// label; for the encoding actually used to decode DBF text (which also
251    /// considers the DBF header code page and any override) see
252    /// [`ShapefileReader::resolved_encoding`].
253    pub fn encoding(&self) -> Option<&str> {
254        self.encoding.as_deref()
255    }
256
257    /// Returns the encoding used to transcode DBF text fields.
258    ///
259    /// Resolved by priority: an explicit override (see
260    /// [`ShapefileReader::open_with_encoding`]) → the `.cpg` label → the DBF
261    /// header code page → UTF-8. Use `.name()` for its canonical label.
262    pub fn resolved_encoding(&self) -> &'static ::encoding_rs::Encoding {
263        self.resolved_encoding
264    }
265
266    /// Returns features whose bounding box intersects the given query bbox.
267    ///
268    /// Reads all shape records from `.shp` and `.dbf`, then filters to those
269    /// whose bounding box overlaps `[min_x, min_y, max_x, max_y]` (inclusive).
270    /// Point shapes use the point coordinate as a degenerate bbox.
271    /// Null shapes are excluded.
272    ///
273    /// For large shapefiles this reads all geometry upfront; a full R-tree
274    /// spatial index backed by lazy `.shx` seeks is a follow-up item.
275    pub fn features_in_bbox(
276        &mut self,
277        min_x: f64,
278        min_y: f64,
279        max_x: f64,
280        max_y: f64,
281    ) -> Result<Vec<ShapefileFeature>> {
282        let all_features = self.read_features()?;
283
284        let filtered = all_features
285            .into_iter()
286            .filter(|feature| {
287                let Some(ref geom) = feature.geometry else {
288                    return false;
289                };
290                if let Some((fx_min, fy_min, fx_max, fy_max)) = Self::geometry_bbox(geom) {
291                    // Standard AABB intersection test (inclusive on edges)
292                    !(fx_max < min_x || fx_min > max_x || fy_max < min_y || fy_min > max_y)
293                } else {
294                    false
295                }
296            })
297            .collect();
298
299        Ok(filtered)
300    }
301
302    /// Extracts a 2-D bounding box `(x_min, y_min, x_max, y_max)` from a geometry.
303    ///
304    /// Delegates to the `Geometry::bounds()` method defined in `oxigeo-core`,
305    /// which returns `None` for degenerate or empty geometries.
306    fn geometry_bbox(geom: &Geometry) -> Option<(f64, f64, f64, f64)> {
307        geom.bounds()
308    }
309
310    /// Returns a streaming iterator over the Shapefile's features.
311    ///
312    /// Unlike [`read_features`], which loads everything into memory, this opens
313    /// fresh buffered readers and reads one SHP record + one DBF record per
314    /// [`Iterator::next`] call.  Memory usage is therefore O(1) with respect
315    /// to the number of features.
316    ///
317    /// # Errors
318    ///
319    /// Returns an error if the `.shp` or `.dbf` files cannot be opened, or if
320    /// the header/field-descriptor section cannot be read.  Individual record
321    /// errors are surfaced as `Err` items from the iterator.
322    ///
323    /// [`read_features`]: ShapefileReader::read_features
324    pub fn iter_features(&self) -> Result<FeatureIter<'_>> {
325        let shp_path = Self::with_extension(&self.base_path, "shp");
326        let dbf_path = Self::with_extension(&self.base_path, "dbf");
327
328        let shp_file = File::open(&shp_path)?;
329        let shp_reader = BufReader::new(shp_file);
330        let shp_reader = ShpReader::new(shp_reader)?;
331
332        let dbf_file = File::open(&dbf_path)?;
333        let dbf_reader = BufReader::new(dbf_file);
334        let mut dbf_reader = DbfReader::new(dbf_reader)?;
335        // Re-attach the sibling memo file so streamed records dereference memos.
336        if let Some(memo_path) = Self::discover_memo_path(&dbf_path)
337            && let Ok(memo) = MemoFile::open(&memo_path)
338        {
339            dbf_reader.set_memo_file(memo);
340        }
341        dbf_reader.set_encoding(self.resolved_encoding);
342
343        Ok(FeatureIter {
344            shp_reader,
345            dbf_reader,
346            field_descriptors: &self.field_descriptors,
347            done: false,
348        })
349    }
350
351    /// Reads features that satisfy an arbitrary predicate closure.
352    ///
353    /// This is a convenience wrapper over [`ShapefileReader::read_features`] that filters the
354    /// result set in-place without a second allocation.  The predicate receives
355    /// a shared reference to each [`ShapefileFeature`] and returns `true` for
356    /// features that should be included in the output.
357    ///
358    /// For structured attribute comparisons prefer
359    /// [`read_features_filtered`](ShapefileReader::read_features_filtered),
360    /// which accepts a [`crate::filter::FieldFilter`] directly.
361    ///
362    /// # Errors
363    ///
364    /// Propagates any I/O or parse errors from the underlying read.
365    pub fn read_features_where<F>(&self, predicate: F) -> Result<Vec<ShapefileFeature>>
366    where
367        F: Fn(&ShapefileFeature) -> bool,
368    {
369        let all = self.read_features()?;
370        Ok(all.into_iter().filter(|f| predicate(f)).collect())
371    }
372
373    /// Reads features that match a structured [`crate::filter::FieldFilter`].
374    ///
375    /// This is a thin convenience method over
376    /// [`read_features_where`](ShapefileReader::read_features_where) that
377    /// accepts a [`crate::filter::FieldFilter`] directly.
378    ///
379    /// # Errors
380    ///
381    /// Propagates any I/O or parse errors from the underlying read.
382    pub fn read_features_filtered(
383        &self,
384        filter: &crate::filter::FieldFilter,
385    ) -> Result<Vec<ShapefileFeature>> {
386        self.read_features_where(|f| filter.matches(f))
387    }
388
389    /// Reads all features from the Shapefile
390    pub fn read_features(&self) -> Result<Vec<ShapefileFeature>> {
391        // Open files
392        let shp_path = Self::with_extension(&self.base_path, "shp");
393        let dbf_path = Self::with_extension(&self.base_path, "dbf");
394
395        let shp_file = File::open(&shp_path)?;
396        let shp_reader = BufReader::new(shp_file);
397        let mut shp_reader = ShpReader::new(shp_reader)?;
398
399        let dbf_file = File::open(&dbf_path)?;
400        let dbf_reader = BufReader::new(dbf_file);
401        let mut dbf_reader = DbfReader::new(dbf_reader)?;
402        // Re-attach the sibling memo file so batch-read records dereference memos.
403        if let Some(memo_path) = Self::discover_memo_path(&dbf_path)
404            && let Ok(memo) = MemoFile::open(&memo_path)
405        {
406            dbf_reader.set_memo_file(memo);
407        }
408        dbf_reader.set_encoding(self.resolved_encoding);
409
410        // Read all shape records
411        let shape_records = shp_reader.read_all_records()?;
412
413        // Read all DBF records
414        let dbf_records = dbf_reader.read_all_records()?;
415
416        // Verify record counts match
417        if shape_records.len() != dbf_records.len() {
418            return Err(ShapefileError::RecordMismatch {
419                shp_count: shape_records.len(),
420                dbf_count: dbf_records.len(),
421            });
422        }
423
424        // Combine into features
425        let mut features = Vec::with_capacity(shape_records.len());
426        for (shape_record, dbf_record) in shape_records.iter().zip(dbf_records.iter()) {
427            let geometry = Self::shape_to_geometry(&shape_record.shape)?;
428
429            // Convert DBF record to attributes
430            let attributes = Self::dbf_to_attributes(dbf_record, &self.field_descriptors);
431
432            features.push(ShapefileFeature::new(
433                shape_record.record_number,
434                geometry,
435                attributes,
436            ));
437        }
438
439        Ok(features)
440    }
441
442    /// Converts a Shape to an OxiGeo Geometry
443    fn shape_to_geometry(shape: &Shape) -> Result<Option<Geometry>> {
444        match shape {
445            Shape::Null => Ok(None),
446            Shape::Point(point) => {
447                let oxigeo_point = CorePoint::new(point.x, point.y);
448                Ok(Some(Geometry::Point(oxigeo_point)))
449            }
450            Shape::PointZ(point) => {
451                use oxigeo_core::vector::Coordinate;
452                let coord = if let Some(m) = point.m {
453                    Coordinate::new_3dm(point.x, point.y, point.z, m)
454                } else {
455                    Coordinate::new_3d(point.x, point.y, point.z)
456                };
457                Ok(Some(Geometry::Point(CorePoint::from_coord(coord))))
458            }
459            Shape::PointM(point) => {
460                use oxigeo_core::vector::Coordinate;
461                let coord = Coordinate::new_2dm(point.x, point.y, point.m);
462                Ok(Some(Geometry::Point(CorePoint::from_coord(coord))))
463            }
464            Shape::PolyLine(multi_part) => {
465                if multi_part.parts.len() == 1 {
466                    // Single part - convert to LineString
467                    let coords: Vec<Coordinate> = multi_part
468                        .points
469                        .iter()
470                        .map(|p| Coordinate::new_2d(p.x, p.y))
471                        .collect();
472
473                    if coords.len() < 2 {
474                        return Ok(None);
475                    }
476
477                    let linestring = CoreLineString::new(coords).map_err(|e| {
478                        ShapefileError::invalid_geometry(format!("Invalid LineString: {}", e))
479                    })?;
480                    Ok(Some(Geometry::LineString(linestring)))
481                } else {
482                    // Multiple parts - convert to MultiLineString
483                    let mut linestrings = Vec::new();
484
485                    for i in 0..multi_part.parts.len() {
486                        let start_idx = multi_part.parts[i] as usize;
487                        let end_idx = if i + 1 < multi_part.parts.len() {
488                            multi_part.parts[i + 1] as usize
489                        } else {
490                            multi_part.points.len()
491                        };
492
493                        let coords: Vec<Coordinate> = multi_part.points[start_idx..end_idx]
494                            .iter()
495                            .map(|p| Coordinate::new_2d(p.x, p.y))
496                            .collect();
497
498                        if coords.len() >= 2
499                            && let Ok(linestring) = CoreLineString::new(coords)
500                        {
501                            linestrings.push(linestring);
502                        }
503                    }
504
505                    if linestrings.is_empty() {
506                        Ok(None)
507                    } else {
508                        Ok(Some(Geometry::MultiLineString(CoreMultiLineString::new(
509                            linestrings,
510                        ))))
511                    }
512                }
513            }
514            Shape::Polygon(multi_part) => {
515                if multi_part.parts.is_empty() {
516                    return Ok(None);
517                }
518                // Rings are distinguished by winding direction, not part position
519                // (ESRI convention): group clockwise exteriors with the holes they
520                // contain and emit a MultiPolygon when several exteriors are present.
521                let rings = split_rings(multi_part, |_, p| Coordinate::new_2d(p.x, p.y));
522                crate::polygon_rings::assemble_polygons(rings)
523            }
524            Shape::MultiPoint(multi_part) => {
525                let points: Vec<CorePoint> = multi_part
526                    .points
527                    .iter()
528                    .map(|p| CorePoint::new(p.x, p.y))
529                    .collect();
530
531                if points.is_empty() {
532                    Ok(None)
533                } else {
534                    Ok(Some(Geometry::MultiPoint(CoreMultiPoint::new(points))))
535                }
536            }
537            // Z variants: reconstruct with Z (and optionally M) coordinates
538            Shape::PolyLineZ(shape_z) => Self::multipart_z_to_linestring_geometry(
539                &shape_z.base,
540                &shape_z.z_values,
541                shape_z.m_values.as_deref(),
542            ),
543            Shape::PolygonZ(shape_z) => Self::multipart_z_to_polygon_geometry(
544                &shape_z.base,
545                &shape_z.z_values,
546                shape_z.m_values.as_deref(),
547            ),
548            Shape::MultiPointZ(shape_z) => Self::multipart_z_to_multipoint_geometry(
549                &shape_z.base,
550                &shape_z.z_values,
551                shape_z.m_values.as_deref(),
552            ),
553            // M variants: reconstruct with M coordinates
554            Shape::PolyLineM(shape_m) => {
555                Self::multipart_m_to_linestring_geometry(&shape_m.base, &shape_m.m_values)
556            }
557            Shape::PolygonM(shape_m) => {
558                Self::multipart_m_to_polygon_geometry(&shape_m.base, &shape_m.m_values)
559            }
560            Shape::MultiPointM(shape_m) => {
561                Self::multipart_m_to_multipoint_geometry(&shape_m.base, &shape_m.m_values)
562            }
563            // MultiPatch: expose as a MultiPolygon using ring parts (outer/inner ring types)
564            // or fall back to a point collection of the vertices.
565            Shape::MultiPatch(mp_shape) => {
566                // Represent patch vertices as a MultiPoint carrying Z coordinates.
567                use oxigeo_core::vector::Coordinate;
568                let points: Vec<CorePoint> = mp_shape
569                    .base
570                    .points
571                    .iter()
572                    .zip(mp_shape.z_values.iter())
573                    .map(|(p, z)| CorePoint::from_coord(Coordinate::new_3d(p.x, p.y, *z)))
574                    .collect();
575
576                if points.is_empty() {
577                    Ok(None)
578                } else {
579                    Ok(Some(Geometry::MultiPoint(CoreMultiPoint::new(points))))
580                }
581            }
582        }
583    }
584
585    /// Converts a multi-part Z shape into a LineString or MultiLineString Geometry
586    /// with Z (and optionally M) coordinates preserved.
587    fn multipart_z_to_linestring_geometry(
588        base: &crate::shp::MultiPartShape,
589        z_values: &[f64],
590        m_values: Option<&[f64]>,
591    ) -> Result<Option<Geometry>> {
592        use oxigeo_core::vector::Coordinate;
593
594        let make_coord = |i: usize, p: &crate::shp::shapes::Point| -> Coordinate {
595            let z = z_values.get(i).copied().unwrap_or(0.0);
596            if let Some(mv) = m_values {
597                Coordinate::new_3dm(p.x, p.y, z, mv.get(i).copied().unwrap_or(0.0))
598            } else {
599                Coordinate::new_3d(p.x, p.y, z)
600            }
601        };
602
603        if base.parts.len() == 1 {
604            let coords: Vec<Coordinate> = base
605                .points
606                .iter()
607                .enumerate()
608                .map(|(i, p)| make_coord(i, p))
609                .collect();
610            if coords.len() < 2 {
611                return Ok(None);
612            }
613            let linestring = CoreLineString::new(coords).map_err(|e| {
614                ShapefileError::invalid_geometry(format!("Invalid LineString: {}", e))
615            })?;
616            Ok(Some(Geometry::LineString(linestring)))
617        } else {
618            let mut linestrings = Vec::new();
619            for i in 0..base.parts.len() {
620                let start = base.parts[i] as usize;
621                let end = if i + 1 < base.parts.len() {
622                    base.parts[i + 1] as usize
623                } else {
624                    base.points.len()
625                };
626                let coords: Vec<Coordinate> = base.points[start..end]
627                    .iter()
628                    .enumerate()
629                    .map(|(j, p)| make_coord(start + j, p))
630                    .collect();
631                if coords.len() >= 2
632                    && let Ok(ls) = CoreLineString::new(coords)
633                {
634                    linestrings.push(ls);
635                }
636            }
637            if linestrings.is_empty() {
638                Ok(None)
639            } else {
640                Ok(Some(Geometry::MultiLineString(CoreMultiLineString::new(
641                    linestrings,
642                ))))
643            }
644        }
645    }
646
647    /// Converts a multi-part Z shape into a Polygon Geometry with Z coordinates.
648    fn multipart_z_to_polygon_geometry(
649        base: &crate::shp::MultiPartShape,
650        z_values: &[f64],
651        m_values: Option<&[f64]>,
652    ) -> Result<Option<Geometry>> {
653        use oxigeo_core::vector::Coordinate;
654
655        if base.parts.is_empty() {
656            return Ok(None);
657        }
658
659        let rings = split_rings(base, |i, p| {
660            let z = z_values.get(i).copied().unwrap_or(0.0);
661            if let Some(mv) = m_values {
662                Coordinate::new_3dm(p.x, p.y, z, mv.get(i).copied().unwrap_or(0.0))
663            } else {
664                Coordinate::new_3d(p.x, p.y, z)
665            }
666        });
667        crate::polygon_rings::assemble_polygons(rings)
668    }
669
670    /// Converts a multi-part Z shape into a MultiPoint Geometry with Z coordinates.
671    fn multipart_z_to_multipoint_geometry(
672        base: &crate::shp::MultiPartShape,
673        z_values: &[f64],
674        m_values: Option<&[f64]>,
675    ) -> Result<Option<Geometry>> {
676        use oxigeo_core::vector::Coordinate;
677        let points: Vec<CorePoint> = base
678            .points
679            .iter()
680            .enumerate()
681            .map(|(i, p)| {
682                let z = z_values.get(i).copied().unwrap_or(0.0);
683                let coord = if let Some(mv) = m_values {
684                    Coordinate::new_3dm(p.x, p.y, z, mv.get(i).copied().unwrap_or(0.0))
685                } else {
686                    Coordinate::new_3d(p.x, p.y, z)
687                };
688                CorePoint::from_coord(coord)
689            })
690            .collect();
691        if points.is_empty() {
692            Ok(None)
693        } else {
694            Ok(Some(Geometry::MultiPoint(CoreMultiPoint::new(points))))
695        }
696    }
697
698    /// Converts a multi-part M shape into a LineString/MultiLineString with M.
699    fn multipart_m_to_linestring_geometry(
700        base: &crate::shp::MultiPartShape,
701        m_values: &[f64],
702    ) -> Result<Option<Geometry>> {
703        use oxigeo_core::vector::Coordinate;
704
705        let make_coord = |i: usize, p: &crate::shp::shapes::Point| -> Coordinate {
706            Coordinate::new_2dm(p.x, p.y, m_values.get(i).copied().unwrap_or(0.0))
707        };
708
709        if base.parts.len() == 1 {
710            let coords: Vec<Coordinate> = base
711                .points
712                .iter()
713                .enumerate()
714                .map(|(i, p)| make_coord(i, p))
715                .collect();
716            if coords.len() < 2 {
717                return Ok(None);
718            }
719            let linestring = CoreLineString::new(coords).map_err(|e| {
720                ShapefileError::invalid_geometry(format!("Invalid LineStringM: {}", e))
721            })?;
722            Ok(Some(Geometry::LineString(linestring)))
723        } else {
724            let mut linestrings = Vec::new();
725            for i in 0..base.parts.len() {
726                let start = base.parts[i] as usize;
727                let end = if i + 1 < base.parts.len() {
728                    base.parts[i + 1] as usize
729                } else {
730                    base.points.len()
731                };
732                let coords: Vec<Coordinate> = base.points[start..end]
733                    .iter()
734                    .enumerate()
735                    .map(|(j, p)| make_coord(start + j, p))
736                    .collect();
737                if coords.len() >= 2
738                    && let Ok(ls) = CoreLineString::new(coords)
739                {
740                    linestrings.push(ls);
741                }
742            }
743            if linestrings.is_empty() {
744                Ok(None)
745            } else {
746                Ok(Some(Geometry::MultiLineString(CoreMultiLineString::new(
747                    linestrings,
748                ))))
749            }
750        }
751    }
752
753    /// Converts a multi-part M shape into a Polygon with M.
754    fn multipart_m_to_polygon_geometry(
755        base: &crate::shp::MultiPartShape,
756        m_values: &[f64],
757    ) -> Result<Option<Geometry>> {
758        use oxigeo_core::vector::Coordinate;
759
760        if base.parts.is_empty() {
761            return Ok(None);
762        }
763
764        let rings = split_rings(base, |i, p| {
765            Coordinate::new_2dm(p.x, p.y, m_values.get(i).copied().unwrap_or(0.0))
766        });
767        crate::polygon_rings::assemble_polygons(rings)
768    }
769
770    /// Converts a multi-part M shape into a MultiPoint with M.
771    fn multipart_m_to_multipoint_geometry(
772        base: &crate::shp::MultiPartShape,
773        m_values: &[f64],
774    ) -> Result<Option<Geometry>> {
775        use oxigeo_core::vector::Coordinate;
776        let points: Vec<CorePoint> = base
777            .points
778            .iter()
779            .enumerate()
780            .map(|(i, p)| {
781                CorePoint::from_coord(Coordinate::new_2dm(
782                    p.x,
783                    p.y,
784                    m_values.get(i).copied().unwrap_or(0.0),
785                ))
786            })
787            .collect();
788        if points.is_empty() {
789            Ok(None)
790        } else {
791            Ok(Some(Geometry::MultiPoint(CoreMultiPoint::new(points))))
792        }
793    }
794
795    /// Converts a DBF record to FieldValue attributes
796    fn dbf_to_attributes(
797        dbf_record: &crate::dbf::DbfRecord,
798        field_descriptors: &[FieldDescriptor],
799    ) -> HashMap<String, FieldValue> {
800        let mut attributes = HashMap::new();
801
802        for (field, value) in field_descriptors.iter().zip(&dbf_record.values) {
803            let property_value = match value {
804                crate::dbf::FieldValue::String(s) => FieldValue::String(s.clone()),
805                crate::dbf::FieldValue::Integer(i) => FieldValue::Integer(*i),
806                crate::dbf::FieldValue::Float(f) => FieldValue::Float(*f),
807                crate::dbf::FieldValue::Boolean(b) => FieldValue::Bool(*b),
808                crate::dbf::FieldValue::Date(d) => FieldValue::String(d.clone()),
809                crate::dbf::FieldValue::Null => FieldValue::Null,
810            };
811
812            attributes.insert(field.name.clone(), property_value);
813        }
814
815        attributes
816    }
817
818    /// Converts a DBF record to FieldValue attributes (static version for FeatureIter)
819    pub(crate) fn dbf_to_attributes_pub(
820        dbf_record: &crate::dbf::DbfRecord,
821        field_descriptors: &[FieldDescriptor],
822    ) -> HashMap<String, FieldValue> {
823        Self::dbf_to_attributes(dbf_record, field_descriptors)
824    }
825
826    /// Converts a Shape to an OxiGeo Geometry (public version for FeatureIter)
827    pub(crate) fn shape_to_geometry_pub(shape: &Shape) -> Result<Option<Geometry>> {
828        Self::shape_to_geometry(shape)
829    }
830
831    /// Discovers the sibling memo file (`.dbt` / `.DBT`) for the given `.dbf`
832    /// path, returning the first variant that exists on disk.
833    ///
834    /// Returns `None` when neither sibling exists; the caller treats that as
835    /// "no memo support" and emits a one-time warning if the table later
836    /// turns out to declare memo fields.
837    fn discover_memo_path(dbf_path: &Path) -> Option<PathBuf> {
838        let lower = dbf_path.with_extension("dbt");
839        if lower.exists() {
840            return Some(lower);
841        }
842        let upper = dbf_path.with_extension("DBT");
843        if upper.exists() {
844            return Some(upper);
845        }
846        None
847    }
848
849    /// Helper to add extension to base path
850    fn with_extension<P: AsRef<Path>>(base_path: P, ext: &str) -> PathBuf {
851        let base = base_path.as_ref();
852
853        // If base already has an extension, replace it
854        if base.extension().is_some() {
855            base.with_extension(ext)
856        } else {
857            // Otherwise, add the extension
858            let mut path = base.to_path_buf();
859            path.set_extension(ext);
860            path
861        }
862    }
863}
864
865// ─── Streaming feature iterator ──────────────────────────────────────────────
866
867/// A lazy, streaming iterator over the features in a Shapefile.
868///
869/// Created by [`ShapefileReader::iter_features`].  Reads one SHP record and one
870/// DBF record per call to [`Iterator::next`], keeping memory usage at O(1) with
871/// respect to the number of features.
872///
873/// The iterator is exhausted as soon as either the `.shp` or the `.dbf` reader
874/// returns `None`, or a record-level I/O error occurs (which is surfaced as an
875/// `Err` item).
876pub struct FeatureIter<'a> {
877    shp_reader: ShpReader<BufReader<File>>,
878    dbf_reader: DbfReader<BufReader<File>>,
879    /// Reference to the field descriptors owned by the parent `ShapefileReader`.
880    field_descriptors: &'a [FieldDescriptor],
881    /// Set to `true` after the first `None` or error to make the iterator fused.
882    done: bool,
883}
884
885impl<'a> Iterator for FeatureIter<'a> {
886    type Item = Result<ShapefileFeature>;
887
888    fn next(&mut self) -> Option<Self::Item> {
889        if self.done {
890            return None;
891        }
892
893        // Read one SHP record
894        let shp_record = match self.shp_reader.read_record() {
895            Ok(Some(r)) => r,
896            Ok(None) => {
897                self.done = true;
898                return None;
899            }
900            Err(e) => {
901                self.done = true;
902                return Some(Err(e));
903            }
904        };
905
906        // Read one DBF record
907        let dbf_record = match self.dbf_reader.read_record() {
908            Ok(Some(r)) => r,
909            Ok(None) => {
910                self.done = true;
911                return None;
912            }
913            Err(e) => {
914                self.done = true;
915                return Some(Err(e));
916            }
917        };
918
919        // Convert shape to geometry
920        let geometry = match ShapefileReader::shape_to_geometry_pub(&shp_record.shape) {
921            Ok(g) => g,
922            Err(e) => {
923                self.done = true;
924                return Some(Err(e));
925            }
926        };
927
928        // Convert DBF record to attributes
929        let attributes =
930            ShapefileReader::dbf_to_attributes_pub(&dbf_record, self.field_descriptors);
931
932        Some(Ok(ShapefileFeature::new(
933            shp_record.record_number,
934            geometry,
935            attributes,
936        )))
937    }
938}
939
940#[cfg(test)]
941mod tests {
942    use super::*;
943
944    #[test]
945    fn test_path_extension_helper() {
946        let base = std::env::temp_dir().join("oxigeo_shapefile_test");
947        let expected_shp = std::env::temp_dir().join("oxigeo_shapefile_test.shp");
948        assert_eq!(ShapefileReader::with_extension(&base, "shp"), expected_shp);
949
950        let base_shp = std::env::temp_dir().join("oxigeo_shapefile_test.shp");
951        let expected_dbf = std::env::temp_dir().join("oxigeo_shapefile_test.dbf");
952        assert_eq!(
953            ShapefileReader::with_extension(&base_shp, "dbf"),
954            expected_dbf
955        );
956    }
957
958    #[test]
959    fn test_shapefile_feature_creation() {
960        let mut attributes = HashMap::new();
961        attributes.insert("name".to_string(), FieldValue::String("Test".to_string()));
962        attributes.insert("value".to_string(), FieldValue::Integer(42));
963
964        let geometry = Some(Geometry::Point(CorePoint::new(10.0, 20.0)));
965
966        let feature = ShapefileFeature::new(1, geometry, attributes);
967        assert_eq!(feature.record_number, 1);
968        assert!(feature.geometry.is_some());
969        assert_eq!(feature.attributes.len(), 2);
970    }
971}