aimx/info_library/

functional_cards.rs

//! Functional programming function documentation for AIMX expressions.
//!
//! Provides comprehensive documentation for higher-order functions and functional
//! programming patterns used in AIMX arrays and closures.

use crate::info_library::{FunctionCard, ArgumentInfo};

/// Documentation for the `map` function.
///
/// Transforms each element of an array by applying a closure function.
/// Returns a new array with the transformed elements.
pub const MAP_CARD: FunctionCard = FunctionCard {
    identifier: "map",
    signature: "map(array, closure)",
    brief: "Transform each element of an array using a closure function.",
    description: "The map function applies a closure to each element of an array, producing a new array with the transformed values. This is a fundamental functional programming operation that enables data transformation pipelines. The closure receives each array element as its first parameter and should return the transformed value.",
    arguments: &[
        &ArgumentInfo {
            label: "array",
            description: "Input array to transform",
            type_hint: "Array",
            optional: false,
        },
        &ArgumentInfo {
            label: "closure",
            description: "Function to apply to each element",
            type_hint: "Closure",
            optional: false,
        },
    ],
    returns: "Array containing transformed elements",
    errors: "Returns error if closure cannot be applied or array is not provided",
    categories: &["functional", "higher-order", "transformation"],
    examples: &[
        "map((1, 2, 3), x => x * 2) // Returns (2, 4, 6)",
        "map((\"a\", \"b\", \"c\"), x => upper(x)) // Returns (\"A\", \"B\", \"C\")",
        "map((1, 2, 3), x => x > 1) // Returns (false, true, true)",
    ],
};

/// Documentation for the `filter` function.
///
/// Filters array elements based on a predicate closure.
/// Returns a new array containing only elements that satisfy the predicate.
pub const FILTER_CARD: FunctionCard = FunctionCard {
    identifier: "filter",
    signature: "filter(array, closure)",
    brief: "Filter array elements using a predicate closure.",
    description: "The filter function creates a new array containing only the elements that satisfy a given predicate. The predicate is a closure that takes an array element and returns a boolean value. Elements for which the predicate returns true are included in the result array.",
    arguments: &[
        &ArgumentInfo {
            label: "array",
            description: "Input array to filter",
            type_hint: "Array",
            optional: false,
        },
        &ArgumentInfo {
            label: "closure",
            description: "Predicate function to test each element",
            type_hint: "Closure",
            optional: false,
        },
    ],
    returns: "Array containing elements that satisfy the predicate",
    errors: "Returns error if predicate cannot be evaluated or array is not provided",
    categories: &["functional", "higher-order", "filtering"],
    examples: &[
        "filter((1, 2, 3, 4, 5), x => x > 3) // Returns (4, 5)",
        "filter((\"apple\", \"banana\", \"cherry\"), x => length(x) > 5) // Returns (\"banana\", \"cherry\")",
        "filter((1, 2, 3, 4, 5), x => x % 2 == 0) // Returns (2, 4)",
    ],
};

/// Documentation for the `reduce` function.
///
/// Reduces an array to a single value using an accumulator closure.
/// Applies the closure cumulatively to array elements.
pub const REDUCE_CARD: FunctionCard = FunctionCard {
    identifier: "reduce",
    signature: "reduce(array, initial, closure)",
    brief: "Reduce array to single value using accumulator closure.",
    description: "The reduce function combines all elements of an array into a single value by repeatedly applying an accumulator function. It starts with an initial value and applies the closure to the accumulator and each array element in sequence. This is useful for computing sums, products, concatenations, or any cumulative operation.",
    arguments: &[
        &ArgumentInfo {
            label: "array",
            description: "Input array to reduce",
            type_hint: "Array",
            optional: false,
        },
        &ArgumentInfo {
            label: "initial",
            description: "Initial accumulator value",
            type_hint: "Any",
            optional: false,
        },
        &ArgumentInfo {
            label: "closure",
            description: "Accumulator function (acc, element) => new_acc",
            type_hint: "Closure",
            optional: false,
        },
    ],
    returns: "Single value resulting from reduction",
    errors: "Returns error if closure cannot be applied or array is not provided",
    categories: &["functional", "higher-order", "aggregation"],
    examples: &[
        "reduce((1, 2, 3, 4, 5), 0, (acc, x) => acc + x) // Returns 15",
        "reduce((1, 2, 3, 4, 5), 1, (acc, x) => acc * x) // Returns 120",
        "reduce((\"a\", \"b\", \"c\"), \"\", (acc, x) => acc + x) // Returns \"abc\"",
    ],
};

/// Documentation for the `scan` function.
///
/// Like reduce but returns intermediate results as an array.
/// Provides running accumulation values throughout the reduction process.
pub const SCAN_CARD: FunctionCard = FunctionCard {
    identifier: "scan",
    signature: "scan(array, initial, closure)",
    brief: "Reduce array while keeping intermediate results.",
    description: "The scan function is similar to reduce but returns an array of all intermediate accumulator values instead of just the final result. This is useful for tracking the progression of cumulative operations, such as running totals, partial sums, or step-by-step transformations. Each element in the result array represents the accumulator value after processing the corresponding input element.",
    arguments: &[
        &ArgumentInfo {
            label: "array",
            description: "Input array to scan",
            type_hint: "Array",
            optional: false,
        },
        &ArgumentInfo {
            label: "initial",
            description: "Initial accumulator value",
            type_hint: "Any",
            optional: false,
        },
        &ArgumentInfo {
            label: "closure",
            description: "Accumulator function (acc, element) => new_acc",
            type_hint: "Closure",
            optional: false,
        },
    ],
    returns: "Array of intermediate accumulator values",
    errors: "Returns error if closure cannot be applied or array is not provided",
    categories: &["functional", "higher-order", "aggregation"],
    examples: &[
        "scan((1, 2, 3, 4, 5), 0, (acc, x) => acc + x) // Returns (0, 1, 3, 6, 10, 15)",
        "scan((1, 2, 3), 1, (acc, x) => acc * x) // Returns (1, 1, 2, 6)",
        "scan((\"a\", \"b\", \"c\"), \"\", (acc, x) => acc + x) // Returns (\"\", \"a\", \"ab\", \"abc\")",
    ],
};

/// Documentation for the `some` function.
///
/// Tests if any element in the array satisfies the predicate.
/// Returns true if at least one element matches the condition.
pub const SOME_CARD: FunctionCard = FunctionCard {
    identifier: "some",
    signature: "some(array, closure)",
    brief: "Check if any element satisfies the predicate.",
    description: "The some function tests whether at least one element in the array satisfies a given predicate. It returns true as soon as the first matching element is found, making it efficient for existence checks. The predicate is a closure that takes an array element and returns a boolean value.",
    arguments: &[
        &ArgumentInfo {
            label: "array",
            description: "Input array to test",
            type_hint: "Array",
            optional: false,
        },
        &ArgumentInfo {
            label: "closure",
            description: "Predicate function to test each element",
            type_hint: "Closure",
            optional: false,
        },
    ],
    returns: "Boolean indicating if any element satisfies the predicate",
    errors: "Returns error if predicate cannot be evaluated or array is not provided",
    categories: &["functional", "higher-order", "testing"],
    examples: &[
        "some((1, 2, 3, 4, 5), x => x > 4) // Returns true",
        "some((1, 2, 3, 4, 5), x => x > 5) // Returns false",
        "some((\"apple\", \"banana\", \"cherry\"), x => contains(x, \"z\")) // Returns false",
    ],
};

/// Documentation for the `every` function.
///
/// Tests if all elements in the array satisfy the predicate.
/// Returns true only if every element matches the condition.
pub const EVERY_CARD: FunctionCard = FunctionCard {
    identifier: "every",
    signature: "every(array, closure)",
    brief: "Check if all elements satisfy the predicate.",
    description: "The every function tests whether all elements in the array satisfy a given predicate. It returns true only if every single element matches the condition. The function stops evaluation and returns false as soon as the first non-matching element is found, providing early termination for efficiency.",
    arguments: &[
        &ArgumentInfo {
            label: "array",
            description: "Input array to test",
            type_hint: "Array",
            optional: false,
        },
        &ArgumentInfo {
            label: "closure",
            description: "Predicate function to test each element",
            type_hint: "Closure",
            optional: false,
        },
    ],
    returns: "Boolean indicating if all elements satisfy the predicate",
    errors: "Returns error if predicate cannot be evaluated or array is not provided",
    categories: &["functional", "higher-order", "testing"],
    examples: &[
        "every((1, 2, 3, 4, 5), x => x > 0) // Returns true",
        "every((1, 2, 3, 4, 5), x => x > 1) // Returns false",
        "every((\"apple\", \"banana\", \"cherry\"), x => length(x) > 3) // Returns true",
    ],
};

/// Documentation for the `none` function.
///
/// Tests if no elements in the array satisfy the predicate.
/// Returns true if zero elements match the condition.
pub const NONE_CARD: FunctionCard = FunctionCard {
    identifier: "none",
    signature: "none(array, closure)",
    brief: "Check if no elements satisfy the predicate.",
    description: "The none function tests whether no elements in the array satisfy a given predicate. It returns true only if zero elements match the condition. This is the logical opposite of the some function. The function stops evaluation and returns false as soon as the first matching element is found.",
    arguments: &[
        &ArgumentInfo {
            label: "array",
            description: "Input array to test",
            type_hint: "Array",
            optional: false,
        },
        &ArgumentInfo {
            label: "closure",
            description: "Predicate function to test each element",
            type_hint: "Closure",
            optional: false,
        },
    ],
    returns: "Boolean indicating if no elements satisfy the predicate",
    errors: "Returns error if predicate cannot be evaluated or array is not provided",
    categories: &["functional", "higher-order", "testing"],
    examples: &[
        "none((1, 2, 3, 4, 5), x => x > 5) // Returns true",
        "none((1, 2, 3, 4, 5), x => x > 4) // Returns false",
        "none((\"apple\", \"banana\", \"cherry\"), x => contains(x, \"z\")) // Returns true",
    ],
};

/// Documentation for the `exactly_one` function.
///
/// Tests if exactly one element in the array satisfies the predicate.
/// Returns true only if precisely one element matches the condition.
pub const EXACTLY_ONE_CARD: FunctionCard = FunctionCard {
    identifier: "exactly_one",
    signature: "exactly_one(array, closure)",
    brief: "Check if exactly one element satisfies the predicate.",
    description: "The exactly_one function tests whether precisely one element in the array satisfies a given predicate. It returns true only if exactly one element matches the condition. The function stops evaluation and returns false as soon as a second matching element is found, providing early termination for efficiency.",
    arguments: &[
        &ArgumentInfo {
            label: "array",
            description: "Input array to test",
            type_hint: "Array",
            optional: false,
        },
        &ArgumentInfo {
            label: "closure",
            description: "Predicate function to test each element",
            type_hint: "Closure",
            optional: false,
        },
    ],
    returns: "Boolean indicating if exactly one element satisfies the predicate",
    errors: "Returns error if predicate cannot be evaluated or array is not provided",
    categories: &["functional", "higher-order", "testing"],
    examples: &[
        "exactly_one((1, 2, 3, 4, 5), x => x == 3) // Returns true",
        "exactly_one((1, 2, 3, 4, 5), x => x > 3) // Returns false",
        "exactly_one((\"apple\", \"banana\", \"cherry\"), x => length(x) == 5) // Returns true",
    ],
};

/// Documentation for the `select` function.
///
/// Like map but provides both element and index to the closure.
/// Enables index-aware transformations of array elements.
pub const SELECT_CARD: FunctionCard = FunctionCard {
    identifier: "select",
    signature: "select(array, closure)",
    brief: "Transform array elements with access to their indices.",
    description: "The select function is similar to map but provides both the array element and its index to the closure. This enables index-aware transformations where the position of elements matters. The closure receives the element as the first parameter and the zero-based index as the second parameter.",
    arguments: &[
        &ArgumentInfo {
            label: "array",
            description: "Input array to transform",
            type_hint: "Array",
            optional: false,
        },
        &ArgumentInfo {
            label: "closure",
            description: "Function to apply with element and index parameters",
            type_hint: "Closure",
            optional: false,
        },
    ],
    returns: "Array containing transformed elements",
    errors: "Returns error if closure cannot be applied or array is not provided",
    categories: &["functional", "higher-order", "transformation"],
    examples: &[
        "select((\"a\", \"b\", \"c\"), (x, i) => x + string(i)) // Returns (\"a0\", \"b1\", \"c2\")",
        "select((1, 2, 3), (x, i) => x * (i + 1)) // Returns (1, 4, 9)",
        "select((\"first\", \"second\", \"third\"), (x, i) => i == 0 ? upper(x) : x) // Returns (\"FIRST\", \"second\", \"third\")",
    ],
};

/// Array of all functional programming function cards.
pub const FUNCTIONAL_CARDS: &[&FunctionCard] = &[
    &MAP_CARD,
    &FILTER_CARD,
    &REDUCE_CARD,
    &SCAN_CARD,
    &SOME_CARD,
    &EVERY_CARD,
    &NONE_CARD,
    &EXACTLY_ONE_CARD,
    &SELECT_CARD,
];