razeri-plugin-contract 0.15.0

// Copyright (C) 2026 Gabriel Shea
// Licensed under either of the Apache License, Version 2.0 or the MIT
// license, at your option.

//! **A value an engine may hold as a large object**: how a load compares one,
//! and the unit a length is counted in.
//!
//! Some engines hold a text column with no length — or bytes, or a document —
//! as a large object (`CLOB`, `NCLOB`, `BLOB`), and such a value is not an
//! ordinary value there: it cannot be grouped or compared directly, and its
//! length may be counted in units other than characters. Razeri asks the
//! dialect about each column with the type the load holds it in
//! ([`HeldAs`]), through
//! [`ExpressionRenderer::render_comparable`](crate::ExpressionRenderer::render_comparable)
//! and [`ExpressionRenderer::text_length_unit`](crate::ExpressionRenderer::text_length_unit).

/// **Where a load holds a column when it compares or measures it.**
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
#[non_exhaustive]
pub enum HeldAs {
    /// As declared: the type the design gives the column, spelled through
    /// [`SqlRenderer::render_data_type`](crate::SqlRenderer::render_data_type)
    /// — a staging table, a dimension, a fact.
    Declared,
    /// Converted from staged text into the declared type, spelled through
    /// [`SqlRenderer::render_cast_type`](crate::SqlRenderer::render_cast_type)
    /// — a core table's load reads its rows this way.
    Converted,
}

/// **The unit an engine's text length counts in.**
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Default)]
#[non_exhaustive]
pub enum TextLengthUnit {
    /// One per character, whatever its code point: `Zoë` is three and an
    /// emoji is one.
    #[default]
    Characters,
    /// One per UTF-16 code unit: a character outside the basic plane, such as
    /// an emoji, is two.
    Utf16CodeUnits,
}