drizzle_core/expr/

math.rs

//! Type-safe math functions.
//!
//! These functions require `Numeric` types (`SmallInt`, Int, `BigInt`, Float, Double)
//! and provide compile-time enforcement of mathematical operations.
//!
//! # Type Safety
//!
//! - `abs`, `round`, `ceil`, `floor`: Require `Numeric` types
//! - `sqrt`, `power`, `log`, `exp`: Require `Numeric` types, return Double
//! - `mod_`: Modulo operation requiring `Numeric` types

use crate::dialect::DialectTypes;
use crate::sql::{SQL, Token};
use crate::traits::SQLParam;
use crate::types::{DataType, Integral, Numeric};
use crate::{Dialect, MySQLDialect, PostgresDialect, SQLiteDialect};
use drizzle_types::mysql::types::{
    BigInt as MyBigInt, BigIntUnsigned as MyBigIntUnsigned, Decimal as MyDecimal,
    Double as MyDouble, Float as MyFloat, Int as MyInt, IntUnsigned as MyIntUnsigned,
    MediumInt as MyMediumInt, MediumIntUnsigned as MyMediumIntUnsigned, SmallInt as MySmallInt,
    SmallIntUnsigned as MySmallIntUnsigned, TinyInt as MyTinyInt,
    TinyIntUnsigned as MyTinyIntUnsigned, Year as MyYear,
};
use drizzle_types::postgres::types::{Float4, Float8, Int2, Int4, Int8, Numeric as PgNumeric};
use drizzle_types::sqlite::types::{
    Integer as SqliteInteger, Numeric as SqliteNumeric, Real as SqliteReal,
};

use super::{AggOr, Expr, NullOr, Nullability, SQLExpr, Scalar};

/// Math functions that are optional on SQLite.
///
/// `CEIL`, `FLOOR`, `TRUNC`, `SQRT`, `POWER`, `EXP`, `LN`, `LOG`, `LOG10`,
/// `LOG2` and `PI` are built into PostgreSQL and MySQL, but SQLite only has
/// them when it is compiled with `SQLITE_ENABLE_MATH_FUNCTIONS`, which the
/// bundled `rusqlite` and `libsql` builds do not set. The `math` cargo feature
/// is the promise that the linked SQLite provides them; without it these
/// functions do not type-check for SQLite instead of failing at runtime with
/// "no such function".
#[diagnostic::on_unimplemented(
    message = "`{Self}` does not provide this math function",
    label = "SQLite only has CEIL/FLOOR/TRUNC/SQRT/POWER/EXP/LN/LOG*/PI with SQLITE_ENABLE_MATH_FUNCTIONS",
    note = "enable drizzle's `math` feature and build SQLite with the math functions, e.g. `LIBSQLITE3_FLAGS=\"-DSQLITE_ENABLE_MATH_FUNCTIONS\"` for bundled rusqlite"
)]
pub trait MathExt {}

impl MathExt for PostgresDialect {}
impl MathExt for MySQLDialect {}
#[cfg(feature = "math")]
impl MathExt for SQLiteDialect {}

#[diagnostic::on_unimplemented(
    message = "this math function is not available for this dialect",
    label = "use a dialect-specific alternative"
)]
pub trait Log2Policy {
    type Nullable: Nullability;
}

/// Nullability policy for math functions whose numeric domain is narrower
/// than their SQL input type.
#[doc(hidden)]
pub trait DomainMathPolicy<Input: Nullability> {
    type Nullable: Nullability;
}

#[diagnostic::on_unimplemented(
    message = "this math function is not available for this dialect",
    label = "use a dialect-specific alternative"
)]
pub trait PiSupport {}

impl Log2Policy for SQLiteDialect {
    type Nullable = super::Null;
}
impl Log2Policy for MySQLDialect {
    type Nullable = super::Null;
}
impl<Input: Nullability> DomainMathPolicy<Input> for SQLiteDialect {
    type Nullable = super::Null;
}
impl<Input: Nullability> DomainMathPolicy<Input> for MySQLDialect {
    type Nullable = super::Null;
}
impl<Input: Nullability> DomainMathPolicy<Input> for PostgresDialect {
    type Nullable = Input;
}
impl PiSupport for PostgresDialect {}
impl PiSupport for MySQLDialect {}
#[cfg(feature = "math")]
impl PiSupport for SQLiteDialect {}

/// Dialect-specific return type for `RANDOM()`.
///
/// `SQLite` `RANDOM()` returns an integer in [-2^63, 2^63).
/// `PostgreSQL` `RANDOM()` returns a float in [0, 1).
#[diagnostic::on_unimplemented(
    message = "no RANDOM return type defined for this dialect",
    label = "RANDOM result type is not configured for this dialect marker"
)]
pub trait RandomPolicy {
    type Random: DataType;
}

impl RandomPolicy for SQLiteDialect {
    type Random = SqliteInteger;
}

impl RandomPolicy for PostgresDialect {
    type Random = drizzle_types::postgres::types::Float8;
}

impl RandomPolicy for MySQLDialect {
    type Random = drizzle_types::mysql::types::Double;
}

#[diagnostic::on_unimplemented(
    message = "no rounding policy for `{Self}` on this dialect",
    label = "round/ceil/floor/trunc return type is not defined for this SQL type/dialect"
)]
pub trait RoundingPolicy<D>: Numeric {
    type Output: DataType;

    /// Prepare the operand of `ROUND(expr, precision)`.
    ///
    /// PostgreSQL only defines the two-argument `ROUND` for `numeric`, and
    /// `double precision` does not cast to it implicitly.
    fn precision_operand<'a, V: SQLParam + 'a>(expr: SQL<'a, V>) -> SQL<'a, V> {
        expr
    }

    /// Coerce a rounding function's result to [`Self::Output`].
    ///
    /// PostgreSQL returns `numeric` for every rounding function unless the
    /// argument is `double precision`; the declared output is `float8`.
    fn coerce_result<'a, V: SQLParam + 'a>(sql: SQL<'a, V>) -> SQL<'a, V> {
        sql
    }
}

/// Coerce a math function's result to DOUBLE PRECISION on PostgreSQL.
///
/// PostgreSQL resolves `SQRT`, `EXP`, `LN`, `LOG`, `POWER` and `SIGN` to their
/// `numeric` overloads for integer or `numeric` arguments, while the declared
/// result type is the dialect's double. The cast is a no-op for `float8`.
pub(super) fn pg_double<'a, V: SQLParam + 'a>(sql: SQL<'a, V>) -> SQL<'a, V> {
    match V::DIALECT {
        Dialect::PostgreSQL => pg_cast(sql, "DOUBLE PRECISION"),
        Dialect::SQLite | Dialect::MySQL => sql,
    }
}

/// `CAST(expr AS type)` for the PostgreSQL rounding policies.
pub(super) fn pg_cast<'a, V: SQLParam + 'a>(
    expr: SQL<'a, V>,
    type_name: &'static str,
) -> SQL<'a, V> {
    SQL::func("CAST", expr.push(Token::AS).append(SQL::raw(type_name)))
}

impl RoundingPolicy<SQLiteDialect> for SqliteInteger {
    type Output = SqliteReal;
}
impl RoundingPolicy<SQLiteDialect> for SqliteReal {
    type Output = Self;
}
impl RoundingPolicy<SQLiteDialect> for SqliteNumeric {
    type Output = SqliteReal;
}

// Integers and NUMERIC round through NUMERIC on PostgreSQL; the result is
// cast to DOUBLE PRECISION so it decodes as the declared `Float8`.
macro_rules! postgres_numeric_rounding_policy {
    ($($ty:ty),+ $(,)?) => {
        $(
            impl RoundingPolicy<PostgresDialect> for $ty {
                type Output = Float8;

                fn coerce_result<'a, V: SQLParam + 'a>(sql: SQL<'a, V>) -> SQL<'a, V> {
                    pg_cast(sql, "DOUBLE PRECISION")
                }
            }
        )+
    };
}
postgres_numeric_rounding_policy!(Int2, Int4, Int8, PgNumeric);

// Floats round natively, but `ROUND(float, n)` only exists for NUMERIC, so the
// precision form casts in and back out.
macro_rules! postgres_float_rounding_policy {
    ($($ty:ty),+ $(,)?) => {
        $(
            impl RoundingPolicy<PostgresDialect> for $ty {
                type Output = Float8;

                fn precision_operand<'a, V: SQLParam + 'a>(expr: SQL<'a, V>) -> SQL<'a, V> {
                    pg_cast(expr, "NUMERIC")
                }

                fn coerce_result<'a, V: SQLParam + 'a>(sql: SQL<'a, V>) -> SQL<'a, V> {
                    pg_cast(sql, "DOUBLE PRECISION")
                }
            }
        )+
    };
}
postgres_float_rounding_policy!(Float4, Float8);

macro_rules! mysql_rounding_policy {
    ($output:ty; $($ty:ty),+ $(,)?) => {
        $(
            impl RoundingPolicy<MySQLDialect> for $ty {
                type Output = $output;
            }
        )+
    };
}

mysql_rounding_policy!(MyBigInt; MyTinyInt, MySmallInt, MyMediumInt, MyInt, MyBigInt,);
mysql_rounding_policy!(MyBigIntUnsigned;
    MyTinyIntUnsigned,
    MySmallIntUnsigned,
    MyMediumIntUnsigned,
    MyIntUnsigned,
    MyBigIntUnsigned,
    MyYear,
);

impl RoundingPolicy<MySQLDialect> for MyFloat {
    type Output = MyDouble;
}
impl RoundingPolicy<MySQLDialect> for MyDouble {
    type Output = Self;
}
impl RoundingPolicy<MySQLDialect> for MyDecimal {
    type Output = Self;
}

// =============================================================================
// ABSOLUTE VALUE
// =============================================================================

/// ABS - returns the absolute value of a number.
///
/// Preserves the SQL type and nullability of the input expression.
///
/// # Type Safety
///
/// ```rust
/// # let _ = r####"
/// // ✅ OK: Int column
/// abs(users.balance);
///
/// // ❌ Compile error: Text is not Numeric
/// abs(users.name);
/// # "####;
/// ```
pub fn abs<'a, V, E>(expr: E) -> SQLExpr<'a, V, E::SQLType, E::Nullable, E::Aggregate>
where
    V: SQLParam + 'a,
    E: Expr<'a, V>,
    E::SQLType: Numeric,
{
    SQLExpr::new(SQL::func("ABS", expr.into_sql()))
}

// =============================================================================
// ROUNDING FUNCTIONS
// =============================================================================

/// ROUND - rounds a number to the nearest integer (or specified precision).
///
/// Returns a dialect-aware float type, preserves nullability.
///
/// # Example
///
/// ```rust
/// # let _ = r####"
/// use drizzle_core::expr::round;
///
/// // SELECT ROUND(users.price)
/// let rounded = round(users.price);
/// # "####;
/// ```
#[allow(clippy::type_complexity)]
pub fn round<'a, V, E>(
    expr: E,
) -> SQLExpr<
    'a,
    V,
    <E::SQLType as RoundingPolicy<V::DialectMarker>>::Output,
    E::Nullable,
    E::Aggregate,
>
where
    V: SQLParam + 'a,
    E: Expr<'a, V>,
    E::SQLType: RoundingPolicy<V::DialectMarker>,
{
    SQLExpr::new(
        <E::SQLType as RoundingPolicy<V::DialectMarker>>::coerce_result(SQL::func(
            "ROUND",
            expr.into_sql(),
        )),
    )
}

/// ROUND with precision - rounds a number to specified decimal places.
///
/// Returns a dialect-aware float type, preserves nullability of the input expression.
///
/// # Example
///
/// ```rust
/// # let _ = r####"
/// use drizzle_core::expr::round_to;
///
/// // SELECT ROUND(users.price, 2)
/// let rounded = round_to(users.price, 2);
/// # "####;
/// ```
#[allow(clippy::type_complexity)]
pub fn round_to<'a, V, E, P>(
    expr: E,
    precision: P,
) -> SQLExpr<
    'a,
    V,
    <E::SQLType as RoundingPolicy<V::DialectMarker>>::Output,
    <E::Nullable as NullOr<P::Nullable>>::Output,
    <E::Aggregate as AggOr<P::Aggregate>>::Output,
>
where
    V: SQLParam + 'a,
    E: Expr<'a, V>,
    E::SQLType: RoundingPolicy<V::DialectMarker>,
    P: Expr<'a, V>,
    P::SQLType: Integral,
    E::Nullable: NullOr<P::Nullable>,
    P::Nullable: Nullability,
    E::Aggregate: AggOr<P::Aggregate>,
{
    SQLExpr::new(
        <E::SQLType as RoundingPolicy<V::DialectMarker>>::coerce_result(SQL::func(
            "ROUND",
            <E::SQLType as RoundingPolicy<V::DialectMarker>>::precision_operand(expr.into_sql())
                .push(Token::COMMA)
                .append(precision.into_sql()),
        )),
    )
}

/// CEIL / CEILING - rounds a number up to the nearest integer.
///
/// Returns a dialect-aware float type, preserves nullability.
///
/// # Example
///
/// ```rust
/// # let _ = r####"
/// use drizzle_core::expr::ceil;
///
/// // SELECT CEIL(users.price)
/// let ceiling = ceil(users.price);
/// # "####;
/// ```
#[allow(clippy::type_complexity)]
pub fn ceil<'a, V, E>(
    expr: E,
) -> SQLExpr<
    'a,
    V,
    <E::SQLType as RoundingPolicy<V::DialectMarker>>::Output,
    E::Nullable,
    E::Aggregate,
>
where
    V: SQLParam + 'a,
    V::DialectMarker: MathExt,
    E: Expr<'a, V>,
    E::SQLType: RoundingPolicy<V::DialectMarker>,
{
    SQLExpr::new(
        <E::SQLType as RoundingPolicy<V::DialectMarker>>::coerce_result(SQL::func(
            "CEIL",
            expr.into_sql(),
        )),
    )
}

/// FLOOR - rounds a number down to the nearest integer.
///
/// Returns a dialect-aware float type, preserves nullability.
///
/// # Example
///
/// ```rust
/// # let _ = r####"
/// use drizzle_core::expr::floor;
///
/// // SELECT FLOOR(users.price)
/// let floored = floor(users.price);
/// # "####;
/// ```
#[allow(clippy::type_complexity)]
pub fn floor<'a, V, E>(
    expr: E,
) -> SQLExpr<
    'a,
    V,
    <E::SQLType as RoundingPolicy<V::DialectMarker>>::Output,
    E::Nullable,
    E::Aggregate,
>
where
    V: SQLParam + 'a,
    V::DialectMarker: MathExt,
    E: Expr<'a, V>,
    E::SQLType: RoundingPolicy<V::DialectMarker>,
{
    SQLExpr::new(
        <E::SQLType as RoundingPolicy<V::DialectMarker>>::coerce_result(SQL::func(
            "FLOOR",
            expr.into_sql(),
        )),
    )
}

/// TRUNC - truncates a number towards zero.
///
/// Returns a dialect-aware float type, preserves nullability.
///
/// # Example
///
/// ```rust
/// # let _ = r####"
/// use drizzle_core::expr::trunc;
///
/// // SELECT TRUNC(users.price), or TRUNCATE(users.price, 0) on MySQL
/// let truncated = trunc(users.price);
/// # "####;
/// ```
#[allow(clippy::type_complexity)]
pub fn trunc<'a, V, E>(
    expr: E,
) -> SQLExpr<
    'a,
    V,
    <E::SQLType as RoundingPolicy<V::DialectMarker>>::Output,
    E::Nullable,
    E::Aggregate,
>
where
    V: SQLParam + 'a,
    V::DialectMarker: MathExt,
    E: Expr<'a, V>,
    E::SQLType: RoundingPolicy<V::DialectMarker>,
{
    let expr = expr.into_sql();
    let truncated = match V::DIALECT {
        Dialect::MySQL => SQL::func("TRUNCATE", expr.push(Token::COMMA).append(SQL::raw("0"))),
        Dialect::SQLite | Dialect::PostgreSQL => SQL::func("TRUNC", expr),
    };
    SQLExpr::new(<E::SQLType as RoundingPolicy<V::DialectMarker>>::coerce_result(truncated))
}

// =============================================================================
// POWER AND ROOT FUNCTIONS
// =============================================================================

/// SQRT - returns the square root of a number.
///
/// Returns a dialect-aware double type. SQLite and MySQL return `NULL` for a
/// negative argument, while PostgreSQL reports an error.
///
/// # Example
///
/// ```rust
/// # let _ = r####"
/// use drizzle_core::expr::sqrt;
///
/// // SELECT SQRT(users.area)
/// let root = sqrt(users.area);
/// # "####;
/// ```
#[allow(clippy::type_complexity)]
pub fn sqrt<'a, V, E>(
    expr: E,
) -> SQLExpr<
    'a,
    V,
    <V::DialectMarker as DialectTypes>::Double,
    <V::DialectMarker as DomainMathPolicy<E::Nullable>>::Nullable,
    E::Aggregate,
>
where
    V: SQLParam + 'a,
    V::DialectMarker: MathExt,
    V::DialectMarker: DomainMathPolicy<E::Nullable>,
    E: Expr<'a, V>,
    E::SQLType: Numeric,
{
    SQLExpr::new(pg_double(SQL::func("SQRT", expr.into_sql())))
}

/// POWER - raises a number to a power.
///
/// Returns a dialect-aware double type. The result is nullable if either input is nullable.
///
/// # Example
///
/// ```rust
/// # let _ = r####"
/// use drizzle_core::expr::power;
///
/// // SELECT POWER(users.base, 2)
/// let squared = power(users.base, 2);
/// # "####;
/// ```
#[allow(clippy::type_complexity)]
pub fn power<'a, V, E1, E2>(
    base: E1,
    exponent: E2,
) -> SQLExpr<
    'a,
    V,
    <V::DialectMarker as DialectTypes>::Double,
    <E1::Nullable as NullOr<E2::Nullable>>::Output,
    <E1::Aggregate as AggOr<E2::Aggregate>>::Output,
>
where
    V: SQLParam + 'a,
    V::DialectMarker: MathExt,
    E1: Expr<'a, V>,
    E1::SQLType: Numeric,
    E2: Expr<'a, V>,
    E2::SQLType: Numeric,
    E1::Nullable: NullOr<E2::Nullable>,
    E2::Nullable: Nullability,
    E1::Aggregate: AggOr<E2::Aggregate>,
{
    SQLExpr::new(pg_double(SQL::func(
        "POWER",
        base.into_sql()
            .push(Token::COMMA)
            .append(exponent.into_sql()),
    )))
}

// =============================================================================
// LOGARITHMIC AND EXPONENTIAL FUNCTIONS
// =============================================================================

/// EXP - returns e raised to the power of the argument.
///
/// Returns a dialect-aware double type and preserves nullability.
///
/// # Example
///
/// ```rust
/// # let _ = r####"
/// use drizzle_core::expr::exp;
///
/// // SELECT EXP(users.rate)
/// let exponential = exp(users.rate);
/// # "####;
/// ```
pub fn exp<'a, V, E>(
    expr: E,
) -> SQLExpr<'a, V, <V::DialectMarker as DialectTypes>::Double, E::Nullable, E::Aggregate>
where
    V: SQLParam + 'a,
    V::DialectMarker: MathExt,
    E: Expr<'a, V>,
    E::SQLType: Numeric,
{
    SQLExpr::new(pg_double(SQL::func("EXP", expr.into_sql())))
}

/// LN - returns the natural logarithm of a number.
///
/// SQLite and MySQL return `NULL` outside the logarithm domain. PostgreSQL
/// reports an error for invalid non-NULL input.
///
/// # Example
///
/// ```rust
/// # let _ = r####"
/// use drizzle_core::expr::ln;
///
/// // SELECT LN(users.value)
/// let natural_log = ln(users.value);
/// # "####;
/// ```
#[allow(clippy::type_complexity)]
pub fn ln<'a, V, E>(
    expr: E,
) -> SQLExpr<
    'a,
    V,
    <V::DialectMarker as DialectTypes>::Double,
    <V::DialectMarker as DomainMathPolicy<E::Nullable>>::Nullable,
    E::Aggregate,
>
where
    V: SQLParam + 'a,
    V::DialectMarker: MathExt,
    V::DialectMarker: DomainMathPolicy<E::Nullable>,
    E: Expr<'a, V>,
    E::SQLType: Numeric,
{
    SQLExpr::new(pg_double(SQL::func("LN", expr.into_sql())))
}

/// LOG10 - returns the base-10 logarithm of a number.
///
/// SQLite and MySQL return `NULL` outside the logarithm domain. PostgreSQL
/// reports an error for invalid non-NULL input.
///
/// # Example
///
/// ```rust
/// # let _ = r####"
/// use drizzle_core::expr::log10;
///
/// // SELECT LOG10(users.value)
/// let log_base_10 = log10(users.value);
/// # "####;
/// ```
#[allow(clippy::type_complexity)]
pub fn log10<'a, V, E>(
    expr: E,
) -> SQLExpr<
    'a,
    V,
    <V::DialectMarker as DialectTypes>::Double,
    <V::DialectMarker as DomainMathPolicy<E::Nullable>>::Nullable,
    E::Aggregate,
>
where
    V: SQLParam + 'a,
    V::DialectMarker: MathExt,
    V::DialectMarker: DomainMathPolicy<E::Nullable>,
    E: Expr<'a, V>,
    E::SQLType: Numeric,
{
    SQLExpr::new(pg_double(SQL::func("LOG10", expr.into_sql())))
}

/// LOG - returns the logarithm of a number with a specified base.
///
/// Returns a dialect-aware double type. The result is nullable if either input is nullable.
///
/// # Example
///
/// ```rust
/// # let _ = r####"
/// use drizzle_core::expr::log;
///
/// // SELECT LOG(2, users.value)
/// let log_base_2 = log(2, users.value);
/// # "####;
/// ```
#[allow(clippy::type_complexity)]
pub fn log<'a, V, E1, E2>(
    base: E1,
    value: E2,
) -> SQLExpr<
    'a,
    V,
    <V::DialectMarker as DialectTypes>::Double,
    <V::DialectMarker as DomainMathPolicy<
        <E1::Nullable as NullOr<E2::Nullable>>::Output,
    >>::Nullable,
    <E1::Aggregate as AggOr<E2::Aggregate>>::Output,
>
where
    V: SQLParam + 'a,
    V::DialectMarker: MathExt,
    V::DialectMarker:
        DomainMathPolicy<<E1::Nullable as NullOr<E2::Nullable>>::Output>,
    E1: Expr<'a, V>,
    E1::SQLType: Numeric,
    E2: Expr<'a, V>,
    E2::SQLType: Numeric,
    E1::Nullable: NullOr<E2::Nullable>,
    E2::Nullable: Nullability,
    E1::Aggregate: AggOr<E2::Aggregate>,
{
    let (base, value) = (base.into_sql(), value.into_sql());
    // PostgreSQL only defines the two-argument LOG for NUMERIC operands.
    let (base, value) = match V::DIALECT {
        Dialect::PostgreSQL => (pg_cast(base, "NUMERIC"), pg_cast(value, "NUMERIC")),
        Dialect::SQLite | Dialect::MySQL => (base, value),
    };
    SQLExpr::new(pg_double(SQL::func(
        "LOG",
        base.push(Token::COMMA).append(value),
    )))
}

// =============================================================================
// SIGN AND MODULO
// =============================================================================

/// The type `SIGN` returns on each dialect.
///
/// SQLite and MySQL answer an integer; PostgreSQL answers `numeric` or
/// `double precision` depending on the argument, which [`sign`] coerces to
/// `double precision`.
pub trait SignPolicy {
    /// The SQL type of `SIGN(expr)`.
    type Sign: DataType;
}

impl SignPolicy for SQLiteDialect {
    type Sign = SqliteInteger;
}

impl SignPolicy for PostgresDialect {
    type Sign = Float8;
}

impl SignPolicy for MySQLDialect {
    type Sign = MyBigInt;
}

/// SIGN - returns the sign of a number (-1, 0, or 1).
///
/// Returns the dialect's [`SignPolicy::Sign`] type (an integer on SQLite and
/// MySQL, `double precision` on PostgreSQL), preserves nullability.
///
/// # Example
///
/// ```rust
/// # let _ = r####"
/// use drizzle_core::expr::sign;
///
/// // SELECT SIGN(users.balance)
/// let balance_sign = sign(users.balance);
/// # "####;
/// ```
pub fn sign<'a, V, E>(
    expr: E,
) -> SQLExpr<'a, V, <V::DialectMarker as SignPolicy>::Sign, E::Nullable, E::Aggregate>
where
    V: SQLParam + 'a,
    V::DialectMarker: SignPolicy,
    E: Expr<'a, V>,
    E::SQLType: Numeric,
{
    SQLExpr::new(pg_double(SQL::func("SIGN", expr.into_sql())))
}

/// MOD - returns the remainder of division (using % operator).
///
/// Returns the same type as the dividend. The result is nullable if either input is nullable.
/// Named `mod_` to avoid conflict with Rust's `mod` keyword.
///
/// Note: Uses the `%` operator which works on both `SQLite` and `PostgreSQL`.
///
/// # Example
///
/// ```rust
/// # let _ = r####"
/// use drizzle_core::expr::mod_;
///
/// // SELECT users.value % 3
/// let remainder = mod_(users.value, 3);
/// # "####;
/// ```
#[allow(clippy::type_complexity)]
pub fn mod_<'a, V, E1, E2>(
    dividend: E1,
    divisor: E2,
) -> SQLExpr<
    'a,
    V,
    E1::SQLType,
    <E1::Nullable as NullOr<E2::Nullable>>::Output,
    <E1::Aggregate as AggOr<E2::Aggregate>>::Output,
>
where
    V: SQLParam + 'a,
    E1: Expr<'a, V>,
    E1::SQLType: Numeric,
    E2: Expr<'a, V>,
    E2::SQLType: Numeric,
    E1::Nullable: NullOr<E2::Nullable>,
    E2::Nullable: Nullability,
    E1::Aggregate: AggOr<E2::Aggregate>,
{
    SQLExpr::new(super::ops::binary_operator_sql(
        dividend.into_expr_sql(),
        Token::REM,
        divisor.into_expr_sql(),
    ))
}

// =============================================================================
// CONSTANTS AND RANDOM
// =============================================================================

/// PI - returns the mathematical constant pi (`PostgreSQL` and `MySQL`).
///
/// # Example
///
/// ```rust
/// # let _ = r####"
/// use drizzle_core::expr::pi;
///
/// // SELECT PI()
/// let pi_val = pi::<PostgresValue>();
/// # "####;
/// ```
#[must_use]
pub fn pi<'a, V>()
-> SQLExpr<'a, V, <V::DialectMarker as DialectTypes>::Double, super::NonNull, Scalar>
where
    V: SQLParam + 'a,
    V::DialectMarker: MathExt,
    V::DialectMarker: PiSupport,
{
    SQLExpr::new(SQL::raw("PI()"))
}

/// RANDOM - returns a random value.
///
/// Return type is dialect-aware:
/// - `SQLite`: integer in [-2^63, 2^63)
/// - `PostgreSQL` and `MySQL`: float in [0, 1)
///
/// # Example
///
/// ```rust
/// # let _ = r####"
/// use drizzle_core::expr::random;
///
/// // SELECT RANDOM() on SQLite/PostgreSQL, SELECT RAND() on MySQL
/// let rnd = random::<SQLiteValue>();
/// # "####;
/// ```
#[must_use]
pub fn random<'a, V>()
-> SQLExpr<'a, V, <V::DialectMarker as RandomPolicy>::Random, super::NonNull, Scalar>
where
    V: SQLParam + 'a,
    V::DialectMarker: RandomPolicy,
{
    SQLExpr::new(SQL::raw(match V::DIALECT {
        Dialect::MySQL => "RAND()",
        Dialect::SQLite | Dialect::PostgreSQL => "RANDOM()",
    }))
}

// =============================================================================
// Dialect-gated Math Functions
// =============================================================================

/// LOG2 - returns the base-2 logarithm of a number.
///
/// Available in `SQLite` when compiled with `SQLITE_ENABLE_MATH_FUNCTIONS`,
/// and natively in `MySQL`.
/// Returns a nullable dialect-aware double because invalid domains produce
/// `NULL` in both dialects.
///
/// # Example
///
/// ```rust
/// # let _ = r####"
/// use drizzle_core::expr::log2;
///
/// // SELECT LOG2(users.value)
/// let log_base_2 = log2(users.value);
/// # "####;
/// ```
#[allow(clippy::type_complexity)]
pub fn log2<'a, V, E>(
    expr: E,
) -> SQLExpr<
    'a,
    V,
    <V::DialectMarker as DialectTypes>::Double,
    <V::DialectMarker as Log2Policy>::Nullable,
    E::Aggregate,
>
where
    V: SQLParam + 'a,
    V::DialectMarker: MathExt,
    V::DialectMarker: Log2Policy,
    E: Expr<'a, V>,
    E::SQLType: Numeric,
{
    SQLExpr::new(SQL::func("LOG2", expr.into_sql()))
}