vector-traits 0.6.2

// SPDX-License-Identifier: MIT OR Apache-2.0
// Copyright (c) 2023, 2025 lacklustr@protonmail.com https://github.com/eadf

// This file is part of vector-traits.

//! # Vector-Traits Crate
//!
//! `vector-traits` is a Rust crate designed to provide a limited set of traits for abstracting over different vector
//! implementations and scalar types, offering a unified interface for a basic set of vector operations. This crate facilitates
//! seamless transitions between different vector libraries and scalar precisions (e.g., `f32` and `f64`) without
//! requiring significant code modifications.
//!
//! ## Features
//!
//! - Abstract over two-dimensional and three-dimensional vectors with `GenericVector2` and `GenericVector3` traits.
//! - Generic scalar trait `GenericScalar` for flexible scalar type handling.
//! - Basic vector traits `HasXY` and `HasXYZ` for low-level, custom vector storage types, e.g., FFI types.
//! - Seamless transition between different vector libraries like `cgmath`, `glam`, and `nalgebra`.
//! - Ability to switch between different scalar types (`f32`, `f64`) effortlessly.
//!
//! ## Design Philosophy
//!
//! This library is designed to be **agnostic** to whether the underlying type represents a **point** or a **vector**.
//! For example, you can compute the distance between two points (`v0.distance(v1)`) or the magnitude of a vector (`v0.magnitude()`)
//! regardless of how the underlying library differentiates between points and vectors. This approach simplifies interoperability
//! and allows you to focus on the geometric operations rather than the semantic distinctions.
//!
//! While some libraries make a deliberate effort to differentiate between points and vectors (e.g., `nalgebra` and `cgmath`), this crate
//! intentionally treats them uniformly to provide a consistent and flexible interface. This means that operations like
//! `distance`, `magnitude`, and `normalize` are available on any type that implements the relevant traits, whether it
//! represents a point or a vector in the underlying library.
//!
//! ## Supported Vector Implementations
//!
//! Currently, the following vector types from `cgmath`, `glam`, and `nalgebra` libraries are supported:
//!
//! - `glam::Vec2`, `glam::Vec3`, `glam::Mat3`, `glam::Mat4`
//! - `glam::Vec3A`, `glam::Mat3A` (uses newtype wrappers: `Vec2A` & `Mat4A` for symmetry)
//! - `glam::DVec2`, `glam::DVec3`, `glam::DMat3`, `glam::DMat4`
//! - `cgmath::Vector2`, `cgmath::Vector3`
//! - `nalgebra::Vector2`, `nalgebra::Vector3`
//!
//! ## Usage
//!
//! Add `vector-traits` to your `Cargo.toml` dependencies along with the desired features:
//!
//! ```toml
//! [dependencies]
//! vector-traits = { version = "0.4.0", features = ["glam", "cgmath", "nalgebra"] }  # only use what you need
//! ```
//!
//! ## Example
//!
//! In this example we use the linestring crate, that builds upon these traits, to calculate the
//! convex hull of a `Vec` of coordinates and an RDP simplified linestring. It does this without any
//! type conversions, but instead uses the specified vector type throughout.
//!
//! ```rust,ignore
//! use vector_traits::prelude::GenericVector2;
//! use linestring::prelude::LineString2;
//!
//! let point_cloud: Vec<glam::Vec2> = vec![/* your glam::Vec2 data */];
//! let convex_hull = point_cloud.convex_hull();
//!
//! let linestring: Vec<nalgebra::Vector2<f64>> = vec![/* your nalgebra::Vector2<f64> data */];
//! let simplified_linestring = linestring.simplify_rdp(0.001);
//! ```
//!
//! ## Contributing
//!
//! Contributions are welcome! Feel free to open an issue or submit a pull request.
//!
//! ## License
//!
//! Licensed under either of
//!
//! - Apache License, Version 2.0 ([LICENSE-APACHE](https://example.com/your-apache-license-link))
//! - MIT license ([LICENSE-MIT](https://example.com/your-mit-license-link))
//!
//! at your option.

#![deny(
    rust_2018_compatibility,
    rust_2018_idioms,
    rust_2021_compatibility,
    nonstandard_style,
    unused,
    future_incompatible,
    non_camel_case_types,
    unused_parens,
    non_upper_case_globals,
    unused_qualifications,
    unused_results,
    unused_imports,
    unused_variables,
    bare_trait_objects,
    ellipsis_inclusive_range_patterns,
    elided_lifetimes_in_paths
)]
#![warn(clippy::explicit_into_iter_loop)]

#[cfg(all(feature = "glam", feature = "macaw"))]
compile_error!(
    "Features `glam` and `macaw` cannot be enabled at the same time. Choose one of the two."
);

#[doc(hidden)]
#[cfg(feature = "cgmath")]
pub mod cgmath_impl;

#[doc(hidden)]
#[cfg(feature = "glam")]
pub mod glam_impl;

#[doc(hidden)]
#[cfg(feature = "macaw")]
mod macaw_impl;

#[doc(hidden)]
#[cfg(feature = "nalgebra")]
pub mod nalgebra_impl;

mod aabb;
mod affine;
mod plane;
mod scalar;
#[allow(clippy::just_underscores_and_digits)]
#[allow(dead_code)]
#[cfg(test)]
mod tests;
mod trait_impl;
mod vector2;
mod vector3;

pub use approx;
#[cfg(feature = "cgmath")]
pub use cgmath;
#[cfg(feature = "glam")]
pub use glam;
#[cfg(feature = "macaw")]
pub use macaw;
#[cfg(feature = "nalgebra")]
pub use nalgebra;
pub use num_traits;

pub mod prelude {

    #[cfg(feature = "glam")]
    pub mod glam_ext {
        pub use crate::glam_impl::{
            Aabb3, Aabb3A, DAabb3,
            mat4a::Mat4A,
            vec2a::{Vec2A, vec2a},
        };
    }

    #[cfg(feature = "macaw")]
    pub mod macaw_ext {
        pub use crate::macaw_impl::{
            Aabb3, Aabb3A, DAabb3,
            mat4a::Mat4A,
            vec2a::{Vec2A, vec2a},
        };
    }

    #[cfg(feature = "cgmath")]
    pub mod cgmath_ext {
        pub use crate::cgmath_impl::{Aabb2, Aabb3};
    }

    #[cfg(feature = "nalgebra")]
    pub mod nalgebra_ext {
        pub use crate::nalgebra_impl::{Aabb2, Aabb3};
    }

    pub use crate::{
        aabb::{Aabb2, Aabb3},
        affine::{Affine2D, Affine3D},
        plane::Plane,
        scalar::GenericScalar,
        vector2::{Approx, GenericVector2, HasXY},
        vector3::{GenericVector3, HasXYZ, SimdUpgradable},
    };
}