/**
 * CalcPad Engine — C FFI Header
 *
 * This header declares the C-compatible interface for the CalcPad calculation
 * engine, built in Rust. It is designed for consumption by Swift via a
 * bridging header or a module map.
 *
 * All functions are safe to call from any thread. Panics in Rust are caught
 * and converted to error results — they never unwind into the caller.
 *
 * Memory ownership:
 *   - Strings returned by calcpad_eval_line / calcpad_eval_sheet are
 *     heap-allocated by Rust and MUST be freed by calling calcpad_free_result.
 *   - Passing NULL to calcpad_free_result is a safe no-op.
 *
 * JSON schema (version "1.0"):
 *
 *   Single-line result (calcpad_eval_line):
 *   {
 *     "schema_version": "1.0",
 *     "result": {
 *       "value": { "kind": "Number", "value": 42.0 },
 *       "metadata": {
 *         "span": { "start": 0, "end": 4 },
 *         "result_type": "Number",
 *         "display": "42",
 *         "raw_value": 42.0
 *       }
 *     }
 *   }
 *
 *   Multi-line result (calcpad_eval_sheet):
 *   {
 *     "schema_version": "1.0",
 *     "results": [ ... ]    // array of result objects as above
 *   }
 */

#ifndef CALCPAD_H
#define CALCPAD_H

#ifdef __cplusplus
extern "C" {
#endif

/**
 * Evaluate a single line of CalcPad input.
 *
 * @param input  A null-terminated UTF-8 string containing the expression.
 *               Passing NULL returns a JSON error result.
 *
 * @return A heap-allocated, null-terminated JSON string containing the
 *         versioned result. The caller MUST free this with
 *         calcpad_free_result(). Returns NULL only on catastrophic
 *         allocation failure.
 */
char *calcpad_eval_line(const char *input);

/**
 * Evaluate multiple lines of CalcPad input as a sheet.
 *
 * Variable assignments on earlier lines are visible to later lines
 * (e.g., "x = 5" on line 1 makes x available on line 2).
 *
 * @param lines  An array of null-terminated UTF-8 strings.
 *               NULL entries are treated as empty lines.
 * @param count  The number of elements in the lines array.
 *               Must be > 0.
 *
 * @return A heap-allocated, null-terminated JSON string containing the
 *         versioned results array. The caller MUST free this with
 *         calcpad_free_result(). Returns NULL only on catastrophic
 *         allocation failure.
 */
char *calcpad_eval_sheet(const char *const *lines, int count);

/**
 * Free a result string previously returned by calcpad_eval_line or
 * calcpad_eval_sheet.
 *
 * @param ptr  The pointer to free. Passing NULL is safe (no-op).
 *             After this call the pointer is invalid.
 */
void calcpad_free_result(char *ptr);

#ifdef __cplusplus
}
#endif

#endif /* CALCPAD_H */