duckfn 0.0.18

//! 列集合抽象：把 DuckDB 一个 `DataChunk` 的多列当作「一行 Rust 数据」来读写。
//!
//! Column-set abstraction: treat the columns of a DuckDB `DataChunk` as a single row of
//! Rust data for reading and writing.

use crate::value_types::duck_value_type::DuckValueReader;
use quack_rs::prelude::DataChunk;
use quack_rs::prelude::LogicalType;

/// 「一行数据」的列集合抽象：描述若干列的名字、逻辑类型，以及按行读取/批量写入的方式。
///
/// 一般不需要手写实现：`#[derive(DuckStruct)]` 会为具名结构体自动生成
/// （见 `duckfn-macro` 的 `duck_struct_derive`），标量函数、表函数都复用它来
/// 解析参数和输出结果列。
///
/// `DuckColumns` describes a set of columns as a single Rust value: their names, their
/// logical types, how to materialise one row from a `DataChunk`, and how to write a batch
/// of rows back. Implementations are usually generated by `#[derive(DuckStruct)]` and are
/// reused by scalar/table functions for both argument parsing and result output.
pub trait DuckColumns: Sized {
    /// 为 `chunk` 的每一列创建读取器（顺序与列顺序一致）。
    ///
    /// Creates one reader per column of `chunk`, in column order.
    fn create_column_readers(chunk: &DataChunk) -> Vec<DuckValueReader>;

    /// 用已创建的读取器读出第 `row` 行；任何非可空列（列类型写 `T` 而不是 `Option<T>`）
    /// 遇到 SQL NULL 时返回 `None`。
    ///
    /// Reads row `row` using the given readers; returns `None` when a non-nullable column (one
    /// declared as `T` rather than `Option<T>`) contains SQL NULL.
    fn read_columns(readers: &[DuckValueReader], row: usize) -> Option<Self>;

    /// 按声明顺序返回各列的逻辑类型（丢弃列名）。
    ///
    /// Logical types of the columns in declaration order (column names dropped).
    fn column_types() -> Vec<LogicalType>{
        Self::named_column_types().into_iter().map(|(_, t)| t).collect()
    }

    /// 按声明顺序返回「列名 + 逻辑类型」二元组。
    ///
    /// Returns `(column name, logical type)` pairs in declaration order.
    fn named_column_types() -> Vec<(String, LogicalType)>;

    /// 把手写的一批行写入输出 `DataChunk`（表函数的批量输出路径）。
    ///
    /// 默认实现是占位 `todo!()`；由 `#[derive(DuckStruct)]` 生成的实现才会真正写数据。
    ///
    /// Writes a batch of rows into the output chunk (used by table functions). The default
    /// implementation is a `todo!()` placeholder; the generated implementation does the work.
    fn write_columns_batch(_chunk: &DataChunk, _row: &[Option<&Self>]){
        todo!()
    }
}