sqlitegis 0.1.3

//! Diesel SQL function definitions for spatial operations.
//!
//! Hand-maintained. The set of declarations here is kept in sync with the
//! canonical function catalog in [`crate::core::function_catalog`] by three
//! parity tests in `tests/diesel_expression_methods.rs`:
//! - `diesel_functions_and_methods_surface_parity`
//! - `diesel_sql_functions_are_backed_by_sqlite_catalog`
//! - `catalog_functions_are_covered_by_diesel_declarations`
//!
//! When adding a new spatial function: add it to the catalog, add the
//! matching `define_sql_function!` block below, and (if the first arg is a
//! `Nullable<Geometry>`) add the method wrapper in
//! [`super::expression_methods`].
//!
//! Import the functions you need and use them directly in Diesel query builder
//! expressions.
//!
//! # Example
//!
//! ```rust
//! # #[cfg(feature = "diesel-sqlite")]
//! # {
//! use sqlitegis::diesel::functions::*;
//! use diesel::debug_query;
//! use diesel::prelude::*;
//! use diesel::sqlite::Sqlite;
//! use diesel::NullableExpressionMethods;
//!
//! diesel::table! {
//!     features (id) {
//!         id -> Integer,
//!         geom -> Nullable<sqlitegis::diesel::Geometry>,
//!     }
//! }
//!
//! let nearby = features::table
//!     .filter(st_dwithin(features::geom, st_point(13.4, 52.5).nullable(), 1000.0).eq(true))
//!     .select(features::geom);
//! let sql = debug_query::<Sqlite, _>(&nearby).to_string().to_lowercase();
//! assert!(sql.contains("st_dwithin"));
//! # }
//! ```
//!
//! The relate aliases are available in free-function form:
//!
//! ```rust
//! # #[cfg(feature = "diesel-sqlite")]
//! # {
//! use diesel::debug_query;
//! use diesel::dsl::select;
//! use diesel::sqlite::Sqlite;
//! use sqlitegis::diesel::functions::*;
//!
//! let a = st_geomfromtext("POINT(1 1)");
//! let b = st_geomfromtext("POLYGON((0 0,0 3,3 3,3 0,0 0))");
//! let pattern = "T*****FF*";
//!
//! // Alias for ST_Relate(a, b, pattern)
//! let via_geoms = select(st_relate_match_geoms(a, b, pattern));
//! let geoms_sql = debug_query::<Sqlite, _>(&via_geoms).to_string().to_lowercase();
//! assert!(geoms_sql.contains("st_relate"));
//!
//! // Alias for ST_RelateMatch(matrix, pattern)
//! let via_matrix = select(st_relate_match("T********", pattern));
//! let matrix_sql = debug_query::<Sqlite, _>(&via_matrix).to_string().to_lowercase();
//! assert!(matrix_sql.contains("st_relatematch"));
//! # }
//! ```
//!
//! # Spatial index lifecycle is raw SQL only
//!
//! `CreateSpatialIndex` and `DropSpatialIndex` are intentionally **not**
//! declared as typed Diesel functions in this module.
//!
//! Manage index lifecycle with `diesel::sql_query(...)` (or SQL migrations),
//! which mirrors the PostGIS workflow where index lifecycle is DDL/SQL-driven.

use crate::diesel::types::Geometry;
use diesel::sql_types::{Binary, Double, Integer, Nullable, Text};

// I/O

diesel::define_sql_function! {
    /// Parse WKT text into a geometry BLOB.
    fn st_geomfromtext(wkt: Text) -> Nullable<Geometry>;
}

diesel::define_sql_function! {
    /// Parse WKT text with explicit SRID into a geometry BLOB.
    #[sql_name = "ST_GeomFromText"]
    fn st_geomfromtext_srid(wkt: Text, srid: Integer) -> Nullable<Geometry>;
}

diesel::define_sql_function! {
    /// Serialize a geometry BLOB to WKT text.
    fn st_astext(geom: Nullable<Geometry>) -> Nullable<Text>;
}

diesel::define_sql_function! {
    /// Serialize a geometry BLOB to EWKT text (`SRID=n;WKT`).
    fn st_asewkt(geom: Nullable<Geometry>) -> Nullable<Text>;
}

diesel::define_sql_function! {
    /// Serialize a geometry BLOB to ISO WKB bytes (strips SRID).
    fn st_asbinary(geom: Nullable<Geometry>) -> Nullable<Binary>;
}

diesel::define_sql_function! {
    /// Serialize a geometry BLOB to EWKB bytes (preserves SRID).
    fn st_asewkb(geom: Nullable<Geometry>) -> Nullable<Binary>;
}

diesel::define_sql_function! {
    /// Parse ISO WKB bytes into a geometry BLOB.
    fn st_geomfromwkb(wkb: Nullable<Binary>) -> Nullable<Geometry>;
}

diesel::define_sql_function! {
    /// Parse ISO WKB bytes with explicit SRID into a geometry BLOB.
    #[sql_name = "ST_GeomFromWKB"]
    fn st_geomfromwkb_srid(wkb: Nullable<Binary>, srid: Integer) -> Nullable<Geometry>;
}

diesel::define_sql_function! {
    /// Parse EWKB bytes into a geometry BLOB.
    fn st_geomfromewkb(ewkb: Nullable<Binary>) -> Nullable<Geometry>;
}

diesel::define_sql_function! {
    /// Serialize a geometry BLOB to GeoJSON text.
    fn st_asgeojson(geom: Nullable<Geometry>) -> Nullable<Text>;
}

diesel::define_sql_function! {
    /// Parse a GeoJSON string into a geometry BLOB.
    ///
    /// SQL signature parity follows PostGIS (`ST_GeomFromGeoJSON(json)` only).
    /// Use `st_setsrid(st_geomfromgeojson(...), srid)` to override SRID.
    fn st_geomfromgeojson(json: Text) -> Nullable<Geometry>;
}

// Constructors

diesel::define_sql_function! {
    /// Construct a Point geometry from X and Y coordinates.
    fn st_point(x: Double, y: Double) -> Geometry;
}

diesel::define_sql_function! {
    /// Construct a Point geometry from X and Y coordinates with explicit SRID.
    #[sql_name = "ST_Point"]
    fn st_point_srid(x: Double, y: Double, srid: Integer) -> Geometry;
}

diesel::define_sql_function! {
    /// Construct a rectangular envelope polygon from corner coordinates.
    fn st_makeenvelope(xmin: Double, ymin: Double, xmax: Double, ymax: Double) -> Geometry;
}

diesel::define_sql_function! {
    /// Construct a rectangular envelope polygon with explicit SRID.
    #[sql_name = "ST_MakeEnvelope"]
    fn st_makeenvelope_srid(
        xmin: Double,
        ymin: Double,
        xmax: Double,
        ymax: Double,
        srid: Integer,
    ) -> Geometry;
}

diesel::define_sql_function! {
    /// Construct a web-mercator tile envelope for the given zoom/x/y.
    fn st_tileenvelope(zoom: Integer, x: Integer, y: Integer) -> Geometry;
}

diesel::define_sql_function! {
    /// Construct a LineString from two Point geometries.
    fn st_makeline(a: Nullable<Geometry>, b: Nullable<Geometry>) -> Nullable<Geometry>;
}

diesel::define_sql_function! {
    /// Construct a Polygon from a shell LineString.
    fn st_makepolygon(shell: Nullable<Geometry>) -> Nullable<Geometry>;
}

diesel::define_sql_function! {
    /// Combine two geometries into a GeometryCollection.
    fn st_collect(a: Nullable<Geometry>, b: Nullable<Geometry>) -> Nullable<Geometry>;
}

// Accessors

diesel::define_sql_function! {
    /// Return the SRID embedded in the geometry EWKB header.
    fn st_srid(geom: Nullable<Geometry>) -> Nullable<Integer>;
}

diesel::define_sql_function! {
    /// Set (replace) the SRID in the geometry EWKB header.
    fn st_setsrid(geom: Nullable<Geometry>, srid: Integer) -> Nullable<Geometry>;
}

diesel::define_sql_function! {
    /// Return the OGC geometry type name (e.g. `ST_Point`, `ST_Polygon`).
    fn st_geometrytype(geom: Nullable<Geometry>) -> Nullable<Text>;
}

diesel::define_sql_function! {
    /// Return the X coordinate of a Point geometry.
    fn st_x(geom: Nullable<Geometry>) -> Nullable<Double>;
}

diesel::define_sql_function! {
    /// Return the Y coordinate of a Point geometry.
    fn st_y(geom: Nullable<Geometry>) -> Nullable<Double>;
}

diesel::define_sql_function! {
    /// Return the Z coordinate of a Point geometry when present.
    fn st_z(geom: Nullable<Geometry>) -> Nullable<Double>;
}

diesel::define_sql_function! {
    /// Return whether the geometry is empty.
    fn st_isempty(geom: Nullable<Geometry>) -> Nullable<diesel::sql_types::Bool>;
}

diesel::define_sql_function! {
    /// Return the number of coordinate dimensions (2, 3, or 4).
    fn st_ndims(geom: Nullable<Geometry>) -> Nullable<diesel::sql_types::SmallInt>;
}

diesel::define_sql_function! {
    /// Return the coordinate dimension (same as `ST_NDims` for non-curve types).
    fn st_coorddim(geom: Nullable<Geometry>) -> Nullable<diesel::sql_types::SmallInt>;
}

diesel::define_sql_function! {
    /// Return the Z/M dimensionality flag (0=2D, 1=M, 2=Z, 3=ZM).
    fn st_zmflag(geom: Nullable<Geometry>) -> Nullable<diesel::sql_types::SmallInt>;
}

diesel::define_sql_function! {
    /// Return the EWKB memory size in bytes.
    fn st_memsize(geom: Nullable<Geometry>) -> Nullable<diesel::sql_types::BigInt>;
}

diesel::define_sql_function! {
    /// Return whether geometry is valid.
    fn st_isvalid(geom: Nullable<Geometry>) -> Nullable<diesel::sql_types::Bool>;
}

diesel::define_sql_function! {
    /// Return the validity reason string.
    fn st_isvalidreason(geom: Nullable<Geometry>) -> Nullable<Text>;
}

diesel::define_sql_function! {
    /// Return the number of points in a LineString.
    fn st_numpoints(geom: Nullable<Geometry>) -> Nullable<Integer>;
}

diesel::define_sql_function! {
    /// Return the total point count across any geometry type.
    fn st_npoints(geom: Nullable<Geometry>) -> Nullable<Integer>;
}

diesel::define_sql_function! {
    /// Return the number of component geometries.
    fn st_numgeometries(geom: Nullable<Geometry>) -> Nullable<Integer>;
}

diesel::define_sql_function! {
    /// Return the number of interior rings in a Polygon.
    fn st_numinteriorrings(geom: Nullable<Geometry>) -> Nullable<Integer>;
}

diesel::define_sql_function! {
    /// Return the total number of rings in a Polygon.
    fn st_numrings(geom: Nullable<Geometry>) -> Nullable<Integer>;
}

diesel::define_sql_function! {
    /// Return the topological dimension (0, 1, or 2).
    fn st_dimension(geom: Nullable<Geometry>) -> Nullable<Integer>;
}

diesel::define_sql_function! {
    /// Return the axis-aligned envelope of a geometry.
    fn st_envelope(geom: Nullable<Geometry>) -> Nullable<Geometry>;
}

diesel::define_sql_function! {
    /// Return the 1-based Nth point of a LineString.
    fn st_pointn(geom: Nullable<Geometry>, n: Integer) -> Nullable<Geometry>;
}

diesel::define_sql_function! {
    /// Return the first point of a LineString.
    fn st_startpoint(geom: Nullable<Geometry>) -> Nullable<Geometry>;
}

diesel::define_sql_function! {
    /// Return the last point of a LineString.
    fn st_endpoint(geom: Nullable<Geometry>) -> Nullable<Geometry>;
}

diesel::define_sql_function! {
    /// Return the exterior ring of a Polygon.
    fn st_exteriorring(geom: Nullable<Geometry>) -> Nullable<Geometry>;
}

diesel::define_sql_function! {
    /// Return the 1-based Nth interior ring of a Polygon.
    fn st_interiorringn(geom: Nullable<Geometry>, n: Integer) -> Nullable<Geometry>;
}

diesel::define_sql_function! {
    /// Return the 1-based Nth geometry from a collection.
    fn st_geometryn(geom: Nullable<Geometry>, n: Integer) -> Nullable<Geometry>;
}

diesel::define_sql_function! {
    /// Return the X coordinate of the bounding-box minimum corner.
    fn st_xmin(geom: Nullable<Geometry>) -> Nullable<Double>;
}

diesel::define_sql_function! {
    /// Return the X coordinate of the bounding-box maximum corner.
    fn st_xmax(geom: Nullable<Geometry>) -> Nullable<Double>;
}

diesel::define_sql_function! {
    /// Return the Y coordinate of the bounding-box minimum corner.
    fn st_ymin(geom: Nullable<Geometry>) -> Nullable<Double>;
}

diesel::define_sql_function! {
    /// Return the Y coordinate of the bounding-box maximum corner.
    fn st_ymax(geom: Nullable<Geometry>) -> Nullable<Double>;
}

// Measurement

diesel::define_sql_function! {
    /// Return the planar area of a polygon geometry.
    fn st_area(geom: Nullable<Geometry>) -> Nullable<Double>;
}

diesel::define_sql_function! {
    /// Return the planar length of a linestring geometry.
    fn st_length(geom: Nullable<Geometry>) -> Nullable<Double>;
}

diesel::define_sql_function! {
    /// Return the planar perimeter of a polygon geometry.
    fn st_perimeter(geom: Nullable<Geometry>) -> Nullable<Double>;
}

diesel::define_sql_function! {
    /// Return the minimum Euclidean distance between two geometries.
    fn st_distance(a: Nullable<Geometry>, b: Nullable<Geometry>) -> Nullable<Double>;
}

diesel::define_sql_function! {
    /// Return the Haversine (spherical) distance in metres between two points.
    fn st_distancesphere(a: Nullable<Geometry>, b: Nullable<Geometry>) -> Nullable<Double>;
}

diesel::define_sql_function! {
    /// Return the geodesic distance in metres between two points (Karney algorithm).
    fn st_distancespheroid(a: Nullable<Geometry>, b: Nullable<Geometry>) -> Nullable<Double>;
}

diesel::define_sql_function! {
    /// Return the centroid of a geometry.
    fn st_centroid(geom: Nullable<Geometry>) -> Nullable<Geometry>;
}

diesel::define_sql_function! {
    /// Return a point guaranteed to lie on or inside the geometry.
    fn st_pointonsurface(geom: Nullable<Geometry>) -> Nullable<Geometry>;
}

diesel::define_sql_function! {
    /// Return the Hausdorff distance between two geometries.
    fn st_hausdorffdistance(a: Nullable<Geometry>, b: Nullable<Geometry>) -> Nullable<Double>;
}

// Operations

diesel::define_sql_function! {
    /// Compute the geometric union of two polygon geometries.
    fn st_union(a: Nullable<Geometry>, b: Nullable<Geometry>) -> Nullable<Geometry>;
}

diesel::define_sql_function! {
    /// Compute the geometric intersection of two polygon geometries.
    fn st_intersection(a: Nullable<Geometry>, b: Nullable<Geometry>) -> Nullable<Geometry>;
}

diesel::define_sql_function! {
    /// Compute the geometric difference (A minus B) of two polygon geometries.
    fn st_difference(a: Nullable<Geometry>, b: Nullable<Geometry>) -> Nullable<Geometry>;
}

diesel::define_sql_function! {
    /// Compute the symmetric difference (XOR) of two polygon geometries.
    fn st_symdifference(a: Nullable<Geometry>, b: Nullable<Geometry>) -> Nullable<Geometry>;
}

diesel::define_sql_function! {
    /// Expand or shrink a geometry by a given distance.
    fn st_buffer(geom: Nullable<Geometry>, distance: Double) -> Nullable<Geometry>;
}

// Predicates

diesel::define_sql_function! {
    /// Return whether geometries share any interior or boundary points.
    fn st_intersects(a: Nullable<Geometry>, b: Nullable<Geometry>) -> Nullable<diesel::sql_types::Bool>;
}

diesel::define_sql_function! {
    /// Return whether geometry A fully contains geometry B.
    fn st_contains(a: Nullable<Geometry>, b: Nullable<Geometry>) -> Nullable<diesel::sql_types::Bool>;
}

diesel::define_sql_function! {
    /// Return whether geometry A is fully contained within geometry B.
    fn st_within(a: Nullable<Geometry>, b: Nullable<Geometry>) -> Nullable<diesel::sql_types::Bool>;
}

diesel::define_sql_function! {
    /// Convenience alias for strict "inside area" selection.
    ///
    /// Semantics match `ST_Within`: boundary-touching geometries are not inside.
    #[sql_name = "ST_Within"]
    fn inside_area(geom: Nullable<Geometry>, area: Nullable<Geometry>) -> Nullable<diesel::sql_types::Bool>;
}

diesel::define_sql_function! {
    /// Return whether A covers B (every point of B lies within A).
    fn st_covers(a: Nullable<Geometry>, b: Nullable<Geometry>) -> Nullable<diesel::sql_types::Bool>;
}

diesel::define_sql_function! {
    /// Return whether A is covered by B.
    fn st_coveredby(a: Nullable<Geometry>, b: Nullable<Geometry>) -> Nullable<diesel::sql_types::Bool>;
}

diesel::define_sql_function! {
    /// Return whether geometries share no points.
    fn st_disjoint(a: Nullable<Geometry>, b: Nullable<Geometry>) -> Nullable<diesel::sql_types::Bool>;
}

diesel::define_sql_function! {
    /// Convenience alias for strict "outside area" selection.
    ///
    /// Semantics match `ST_Disjoint`: boundary-touching geometries are not outside.
    #[sql_name = "ST_Disjoint"]
    fn outside_area(geom: Nullable<Geometry>, area: Nullable<Geometry>) -> Nullable<diesel::sql_types::Bool>;
}

diesel::define_sql_function! {
    /// Return whether geometries are spatially equal.
    fn st_equals(a: Nullable<Geometry>, b: Nullable<Geometry>) -> Nullable<diesel::sql_types::Bool>;
}

diesel::define_sql_function! {
    /// Return whether A and B are within the given **Euclidean** (planar) distance.
    ///
    /// Note: This uses planar distance only. For geodesic radius predicates,
    /// use `ST_DWithinSphere` / `ST_DWithinSpheroid`.
    fn st_dwithin(a: Nullable<Geometry>, b: Nullable<Geometry>, distance: Double) -> Nullable<diesel::sql_types::Bool>;
}

diesel::define_sql_function! {
    /// Return whether two geographic points are within distance (metres) using
    /// Haversine (spherical) distance (requires SRID 4326 on both points).
    fn st_dwithinsphere(a: Nullable<Geometry>, b: Nullable<Geometry>, distance: Double) -> Nullable<diesel::sql_types::Bool>;
}

diesel::define_sql_function! {
    /// Return whether two geographic points are within distance (metres) using
    /// geodesic (spheroid) distance (requires SRID 4326 on both points).
    fn st_dwithinspheroid(a: Nullable<Geometry>, b: Nullable<Geometry>, distance: Double) -> Nullable<diesel::sql_types::Bool>;
}

diesel::define_sql_function! {
    /// Return whether geometries share boundary points but no interior points.
    fn st_touches(a: Nullable<Geometry>, b: Nullable<Geometry>) -> Nullable<diesel::sql_types::Bool>;
}

diesel::define_sql_function! {
    /// Return whether geometries cross each other (intersect with a lower-dimensional result).
    fn st_crosses(a: Nullable<Geometry>, b: Nullable<Geometry>) -> Nullable<diesel::sql_types::Bool>;
}

diesel::define_sql_function! {
    /// Return whether geometries overlap (same dimension, intersect but neither contains the other).
    fn st_overlaps(a: Nullable<Geometry>, b: Nullable<Geometry>) -> Nullable<diesel::sql_types::Bool>;
}

diesel::define_sql_function! {
    /// Return the DE-9IM relationship matrix string between two geometries.
    fn st_relate(a: Nullable<Geometry>, b: Nullable<Geometry>) -> Nullable<Text>;
}

diesel::define_sql_function! {
    /// Alias of `ST_Relate(a, b, pattern)` matching core naming.
    #[sql_name = "ST_Relate"]
    fn st_relate_match_geoms(a: Nullable<Geometry>, b: Nullable<Geometry>, pattern: Text) -> Nullable<diesel::sql_types::Bool>;
}

diesel::define_sql_function! {
    /// Return whether the DE-9IM matrix string matches the pattern.
    fn st_relatematch(matrix: Text, pattern: Text) -> Nullable<diesel::sql_types::Bool>;
}

diesel::define_sql_function! {
    /// Alias of `ST_RelateMatch(matrix, pattern)` matching core naming.
    #[sql_name = "st_relatematch"]
    fn st_relate_match(matrix: Text, pattern: Text) -> Nullable<diesel::sql_types::Bool>;
}

// Geography variants

diesel::define_sql_function! {
    /// Haversine arc length of a linestring in metres.
    fn st_lengthsphere(geom: Nullable<Geometry>) -> Nullable<Double>;
}

diesel::define_sql_function! {
    /// Geodesic bearing from origin to target in radians (0 = north, clockwise).
    fn st_azimuth(origin: Nullable<Geometry>, target: Nullable<Geometry>) -> Nullable<Double>;
}

diesel::define_sql_function! {
    /// Destination point from origin given distance (metres) and azimuth (radians).
    fn st_project(origin: Nullable<Geometry>, distance: Double, azimuth: Double) -> Nullable<Geometry>;
}

diesel::define_sql_function! {
    /// Closest point on geometry A to point B.
    fn st_closestpoint(a: Nullable<Geometry>, b: Nullable<Geometry>) -> Nullable<Geometry>;
}

// Aliases
// PostGIS-compatible alias names registered alongside their canonical forms.

diesel::define_sql_function! {
    /// Alias for `ST_Point`: construct a Point geometry from X and Y coordinates.
    #[sql_name = "ST_MakePoint"]
    fn st_makepoint(x: Double, y: Double) -> Geometry;
}

diesel::define_sql_function! {
    /// Alias for `ST_GeometryType`: return the OGC geometry type name (e.g. `ST_Point`).
    #[sql_name = "GeometryType"]
    fn geometry_type(geom: Nullable<Geometry>) -> Nullable<Text>;
}

diesel::define_sql_function! {
    /// Alias for `ST_NumInteriorRings`: return the number of interior rings in a Polygon.
    #[sql_name = "ST_NumInteriorRing"]
    fn st_numinteriorring(geom: Nullable<Geometry>) -> Nullable<Integer>;
}

diesel::define_sql_function! {
    /// Alias for `ST_Length`: return the planar length of a linestring geometry.
    #[sql_name = "ST_Length2D"]
    fn st_length2d(geom: Nullable<Geometry>) -> Nullable<Double>;
}

diesel::define_sql_function! {
    /// Alias for `ST_Perimeter`: return the planar perimeter of a polygon geometry.
    #[sql_name = "ST_Perimeter2D"]
    fn st_perimeter2d(geom: Nullable<Geometry>) -> Nullable<Double>;
}