Module error 

Error types for OxiGDAL

This module provides a comprehensive error hierarchy for all OxiGDAL operations. All error types implement std::error::Error via thiserror.

Error Codes

Each error variant has an associated error code (e.g., E001, E002) for easier debugging and documentation. Error codes are stable across versions.

Helper Methods

All error types provide:

• code() - Returns the error code
• suggestion() - Returns helpful hints for fixing the error
• context() - Returns additional context about the error

Builder Pattern

For simple errors, use the direct constructors:

use oxigdal_core::error::OxiGdalError;

let err = OxiGdalError::io_error("Cannot read file");

For errors with rich context, use the builder pattern via ErrorBuilder:

use oxigdal_core::error::OxiGdalError;

let err = OxiGdalError::io_error_builder("Cannot read file")
    .with_path("/data/file.tif")
    .with_operation("read_raster")
    .with_suggestion("Check file permissions")
    .build();

When to Use Which Error Type

• IoError: File I/O, network operations, HTTP requests
• FormatError: File format parsing, magic number validation, header parsing
• CrsError: Coordinate system operations, transformations, WKT/EPSG handling
• CompressionError: Compression/decompression operations
• InvalidParameter: Parameter validation failures
• NotSupported: Unsupported features or operations
• OutOfBounds: Index or range validation failures
• Internal: Internal invariant violations, allocation failures

Examples of Rich Error Messages

File Not Found with Context

use oxigdal_core::error::OxiGdalError;
use std::path::Path;

fn read_geotiff(path: &Path) -> Result<(), OxiGdalError> {
    if !path.exists() {
        return Err(OxiGdalError::io_error_builder("GeoTIFF file not found")
            .with_path(path)
            .with_operation("read_geotiff")
            .with_suggestion("Verify the file path and ensure the file exists")
            .build());
    }
    Ok(())
}

Parameter Validation with Constraints

use oxigdal_core::error::{OxiGdalError, Result};

fn create_raster(width: usize, height: usize) -> Result<()> {
    if width == 0 || width > 65535 {
        return Err(OxiGdalError::invalid_parameter_builder("width", "must be between 1 and 65535")
            .with_parameter("value", width.to_string())
            .with_parameter("min", "1")
            .with_parameter("max", "65535")
            .with_operation("create_raster")
            .build());
    }
    Ok(())
}

Format Error with Details

use oxigdal_core::error::{OxiGdalError, FormatError};

fn parse_header(data: &[u8]) -> Result<(), OxiGdalError> {
    if data.len() < 4 {
        return Err(FormatError::InvalidHeader {
            message: format!("Header too short: expected at least 4 bytes, got {}", data.len())
        }.into());
    }
    Ok(())
}

CRS Transformation Error

use oxigdal_core::error::{OxiGdalError, CrsError};

fn transform_coordinates(src_epsg: u32, dst_epsg: u32) -> Result<(), OxiGdalError> {
    if src_epsg == dst_epsg {
        return Err(CrsError::TransformationError {
            source_crs: format!("EPSG:{}", src_epsg),
            target_crs: format!("EPSG:{}", dst_epsg),
            message: "Source and target CRS are identical".to_string(),
        }.into());
    }
    Ok(())
}

Re-exports

pub use builder::*;

pub use extensions::*;

pub use types::*;

Modules

builder

Error builder and context types

extensions

Error handling extensions and utilities

methods

Method implementations for error types

types

Error type definitions for OxiGDAL

Type Aliases

Result

The main result type for OxiGDAL operations