runmat_runtime/builtins/structs/core/

setfield.rs

//! MATLAB-compatible `setfield` builtin with struct array and object support.
//!
//! Mirrors MATLAB's `setfield` semantics, including nested field creation, struct
//! array indexing via cell arguments, and property assignment on MATLAB-style
//! objects. The builtin performs all updates on host data; GPU-resident values are
//! gathered automatically before mutation. Updated tensors remain on the host.

use crate::builtins::common::spec::{
    BroadcastSemantics, BuiltinFusionSpec, BuiltinGpuSpec, ConstantStrategy, GpuOpKind,
    ReductionNaN, ResidencyPolicy, ShapeRequirements,
};
use crate::builtins::common::tensor;
use crate::builtins::introspection::dynamicprops;
use crate::builtins::structs::type_resolvers::setfield_type;
use crate::{
    build_runtime_error, call_builtin_async, gather_if_needed_async, object_property_getter_name,
    object_property_setter_name, BuiltinResult, RuntimeError,
};
use runmat_builtins::{
    BuiltinCompletionPolicy, BuiltinDescriptor, BuiltinErrorDescriptor, BuiltinOutputMode,
    BuiltinParamArity, BuiltinParamDescriptor, BuiltinParamType, BuiltinSignatureDescriptor,
};
use runmat_builtins::{
    BuiltinIntegerBackendRule, BuiltinIntegerCapabilityDescriptor, BuiltinIntegerComputationDomain,
    BuiltinIntegerInputAvailability, BuiltinIntegerInputCapability, BuiltinIntegerOutputClassRule,
    BuiltinIntegerOverflowRule, BuiltinIntegerOverloadKind, BuiltinIntegerScalarDoubleRule,
};
use runmat_macros::runtime_builtin;
use runmat_types::MemberAccess;
use runmat_value::{
    CellArray, CharArray, ComplexTensor, HandleRef, LogicalArray, NumericScalar, ObjectInstance,
    StructValue, Tensor, Value,
};
use std::convert::TryFrom;

#[runmat_macros::register_gpu_spec(builtin_path = "crate::builtins::structs::core::setfield")]
pub const GPU_SPEC: BuiltinGpuSpec = BuiltinGpuSpec {
    name: "setfield",
    op_kind: GpuOpKind::Custom("setfield"),
    supported_precisions: &[],
    broadcast: BroadcastSemantics::None,
    provider_hooks: &[],
    constant_strategy: ConstantStrategy::InlineLiteral,
    residency: ResidencyPolicy::InheritInputs,
    nan_mode: ReductionNaN::Include,
    two_pass_threshold: None,
    workgroup_size: None,
    accepts_nan_mode: false,
    notes: "Host-only metadata mutation; GPU tensors are gathered before assignment.",
};

#[runmat_macros::register_fusion_spec(builtin_path = "crate::builtins::structs::core::setfield")]
pub const FUSION_SPEC: BuiltinFusionSpec = BuiltinFusionSpec {
    name: "setfield",
    shape: ShapeRequirements::Any,
    constant_strategy: ConstantStrategy::InlineLiteral,
    elementwise: None,
    reduction: None,
    emits_nan: false,
    notes: "Assignments terminate fusion and gather device data back to the host.",
};

const BUILTIN_NAME: &str = "setfield";
const SETFIELD_OUTPUT: [BuiltinParamDescriptor; 1] = [BuiltinParamDescriptor {
    name: "S",
    ty: BuiltinParamType::Any,
    arity: BuiltinParamArity::Required,
    default: None,
    description: "Updated struct/object/array value.",
}];

const SETFIELD_INPUTS_SCALAR: [BuiltinParamDescriptor; 3] = [
    BuiltinParamDescriptor {
        name: "S",
        ty: BuiltinParamType::Any,
        arity: BuiltinParamArity::Required,
        default: None,
        description: "Input struct/object/struct-array target.",
    },
    BuiltinParamDescriptor {
        name: "field",
        ty: BuiltinParamType::PropertyName,
        arity: BuiltinParamArity::Required,
        default: None,
        description: "Field/property name to assign.",
    },
    BuiltinParamDescriptor {
        name: "value",
        ty: BuiltinParamType::Any,
        arity: BuiltinParamArity::Required,
        default: None,
        description: "Assigned value.",
    },
];

const SETFIELD_INPUTS_NESTED: [BuiltinParamDescriptor; 3] = [
    BuiltinParamDescriptor {
        name: "S",
        ty: BuiltinParamType::Any,
        arity: BuiltinParamArity::Required,
        default: None,
        description: "Input struct/object/struct-array target.",
    },
    BuiltinParamDescriptor {
        name: "path",
        ty: BuiltinParamType::Any,
        arity: BuiltinParamArity::Variadic,
        default: None,
        description:
            "Alternating field names and optional index-selector cells `{...}` for nested assignment.",
    },
    BuiltinParamDescriptor {
        name: "value",
        ty: BuiltinParamType::Any,
        arity: BuiltinParamArity::Required,
        default: None,
        description: "Assigned value.",
    },
];

const SETFIELD_INPUTS_LEADING_INDEX: [BuiltinParamDescriptor; 4] = [
    BuiltinParamDescriptor {
        name: "S",
        ty: BuiltinParamType::Any,
        arity: BuiltinParamArity::Required,
        default: None,
        description: "Input struct-array target.",
    },
    BuiltinParamDescriptor {
        name: "index_selector",
        ty: BuiltinParamType::Any,
        arity: BuiltinParamArity::Required,
        default: None,
        description: "Leading index selector in a cell array, e.g. `{2}` or `{end}`.",
    },
    BuiltinParamDescriptor {
        name: "path",
        ty: BuiltinParamType::Any,
        arity: BuiltinParamArity::Variadic,
        default: None,
        description:
            "Alternating field names and optional index-selector cells `{...}` for nested assignment.",
    },
    BuiltinParamDescriptor {
        name: "value",
        ty: BuiltinParamType::Any,
        arity: BuiltinParamArity::Required,
        default: None,
        description: "Assigned value.",
    },
];

const SETFIELD_SIGNATURES: [BuiltinSignatureDescriptor; 3] = [
    BuiltinSignatureDescriptor {
        label: "S = setfield(S, field, value)",
        inputs: &SETFIELD_INPUTS_SCALAR,
        outputs: &SETFIELD_OUTPUT,
    },
    BuiltinSignatureDescriptor {
        label: "S = setfield(S, field_or_index, ..., value)",
        inputs: &SETFIELD_INPUTS_NESTED,
        outputs: &SETFIELD_OUTPUT,
    },
    BuiltinSignatureDescriptor {
        label: "S = setfield(S, {idx0}, field_or_index, ..., value)",
        inputs: &SETFIELD_INPUTS_LEADING_INDEX,
        outputs: &SETFIELD_OUTPUT,
    },
];

const SETFIELD_INTEGER_VALUE_INPUT: [BuiltinIntegerInputCapability; 1] =
    [BuiltinIntegerInputCapability {
        name: "value",
        classes: &crate::builtins::common::integer_capability::ALL_INTEGER_CLASSES,
        availability: BuiltinIntegerInputAvailability::Documented,
        scalar_double: BuiltinIntegerScalarDoubleRule::NotApplicable,
        notes: "An integer assigned as a new or replacement field value remains an ordinary exact MATLAB value with its native class and shape.",
    }];
const SETFIELD_INTEGER_INDEX_INPUT: [BuiltinIntegerInputCapability; 1] =
    [BuiltinIntegerInputCapability {
        name: "idx cells",
        classes: &crate::builtins::common::integer_capability::ALL_INTEGER_CLASSES,
        availability: BuiltinIntegerInputAvailability::Documented,
        scalar_double: BuiltinIntegerScalarDoubleRule::Allowed,
        notes: "Numeric index values inside selector cells are decoded exactly and range checked before structural indexing.",
    }];
pub const SETFIELD_INTEGER_CAPABILITIES: [BuiltinIntegerCapabilityDescriptor; 2] = [
    BuiltinIntegerCapabilityDescriptor { form: "S = setfield(S, field_or_path, integer_value)", inputs: &SETFIELD_INTEGER_VALUE_INPUT, computation_domain: BuiltinIntegerComputationDomain::Structural, output_class: BuiltinIntegerOutputClassRule::PreserveInput, overflow: BuiltinIntegerOverflowRule::NotApplicable, backend: BuiltinIntegerBackendRule::GatherFallback, overload: BuiltinIntegerOverloadKind::Multiple, notes: "Direct structure and object field replacement preserves authoritative integer payloads; assignment into an existing typed numeric container follows that container's documented conversion rule." },
    BuiltinIntegerCapabilityDescriptor { form: "S = setfield(S, {integer_idx}, field_or_path, value)", inputs: &SETFIELD_INTEGER_INDEX_INPUT, computation_domain: BuiltinIntegerComputationDomain::Structural, output_class: BuiltinIntegerOutputClassRule::FunctionSpecific, overflow: BuiltinIntegerOverflowRule::Error, backend: BuiltinIntegerBackendRule::GatherFallback, overload: BuiltinIntegerOverloadKind::Multiple, notes: "Index selectors are decoded exactly in every supported integer class; host mutation gathers automatically resident values when required." },
];

const SETFIELD_ERROR_NOT_ENOUGH_INPUTS: BuiltinErrorDescriptor = BuiltinErrorDescriptor {
    code: "RM.SETFIELD.NOT_ENOUGH_INPUTS",
    identifier: Some("RunMat:setfield:NotEnoughInputs"),
    when: "Input does not provide at least one path component plus assigned value.",
    message: "setfield: expected at least one field name and a value",
};

const SETFIELD_ERROR_FIELD_EXPECTED: BuiltinErrorDescriptor = BuiltinErrorDescriptor {
    code: "RM.SETFIELD.FIELD_EXPECTED",
    identifier: Some("RunMat:setfield:FieldExpected"),
    when: "Field/path arguments are missing after parsing selectors.",
    message: "setfield: expected field name arguments",
};

const SETFIELD_ERROR_INDEX_SELECTOR_TYPE: BuiltinErrorDescriptor = BuiltinErrorDescriptor {
    code: "RM.SETFIELD.INDEX_SELECTOR_TYPE",
    identifier: Some("RunMat:setfield:IndexSelectorType"),
    when: "Index selector is not provided as a cell array.",
    message: "setfield: indices must be provided in a cell array",
};

const SETFIELD_ERROR_INDEX_INVALID: BuiltinErrorDescriptor = BuiltinErrorDescriptor {
    code: "RM.SETFIELD.INDEX_INVALID",
    identifier: Some("RunMat:setfield:InvalidIndex"),
    when: "Index component is malformed, empty, unsupported, or not a positive integer.",
    message: "setfield: invalid index element",
};

const SETFIELD_ERROR_FIELD_NAME_TYPE: BuiltinErrorDescriptor = BuiltinErrorDescriptor {
    code: "RM.SETFIELD.FIELD_NAME_TYPE",
    identifier: Some("RunMat:setfield:FieldNameType"),
    when: "Field name is not a scalar string or 1-by-N char vector.",
    message: "setfield: expected field name",
};

const SETFIELD_ERROR_INDEX_SHAPE: BuiltinErrorDescriptor = BuiltinErrorDescriptor {
    code: "RM.SETFIELD.INDEX_SHAPE",
    identifier: Some("RunMat:setfield:IndexShape"),
    when: "Indexing rank/shape is unsupported for the targeted value.",
    message: "setfield: unsupported index shape for target value",
};

const SETFIELD_ERROR_NON_STRUCT_ASSIGNMENT: BuiltinErrorDescriptor = BuiltinErrorDescriptor {
    code: "RM.SETFIELD.NON_STRUCT_ASSIGNMENT",
    identifier: Some("RunMat:setfield:NonStructAssignment"),
    when: "Assignment target does not support struct-like field updates.",
    message: "Struct contents assignment to a non-struct object is not supported.",
};

const SETFIELD_ERROR_INDEX_OUT_OF_BOUNDS: BuiltinErrorDescriptor = BuiltinErrorDescriptor {
    code: "RM.SETFIELD.INDEX_OUT_OF_BOUNDS",
    identifier: Some("RunMat:setfield:IndexOutOfBounds"),
    when: "Resolved index is outside bounds for target value.",
    message: "Index exceeds the number of array elements.",
};

const SETFIELD_ERROR_MISSING_FIELD: BuiltinErrorDescriptor = BuiltinErrorDescriptor {
    code: "RM.SETFIELD.MISSING_FIELD",
    identifier: Some("RunMat:setfield:MissingField"),
    when: "Indexed assignment path references a missing field.",
    message: "Reference to non-existent field",
};

const SETFIELD_ERROR_PROPERTY_PRIVATE_ACCESS: BuiltinErrorDescriptor = BuiltinErrorDescriptor {
    code: "RM.SETFIELD.PROPERTY_PRIVATE_ACCESS",
    identifier: Some("RunMat:PropertyPrivateAccess"),
    when: "Property exists but get/set access is private.",
    message: "setfield: private property access denied",
};

const SETFIELD_ERROR_PROPERTY_STATIC_ACCESS: BuiltinErrorDescriptor = BuiltinErrorDescriptor {
    code: "RM.SETFIELD.PROPERTY_STATIC_ACCESS",
    identifier: Some("RunMat:PropertyStaticAccess"),
    when: "Property exists but is static and cannot be assigned through an instance.",
    message: "setfield: static property access denied",
};

const SETFIELD_ERROR_OBJECT_PROPERTY: BuiltinErrorDescriptor = BuiltinErrorDescriptor {
    code: "RM.SETFIELD.OBJECT_PROPERTY",
    identifier: Some("RunMat:setfield:ObjectProperty"),
    when: "Object property operation is invalid (static, non-public, or malformed setter result).",
    message: "setfield: invalid object property operation",
};

const SETFIELD_ERROR_INVALID_HANDLE: BuiltinErrorDescriptor = BuiltinErrorDescriptor {
    code: "RM.SETFIELD.INVALID_HANDLE",
    identifier: Some("RunMat:setfield:InvalidHandle"),
    when: "Handle target is invalid/deleted/null.",
    message: "setfield: invalid or deleted handle object",
};

const SETFIELD_ERROR_INTERNAL: BuiltinErrorDescriptor = BuiltinErrorDescriptor {
    code: "RM.SETFIELD.INTERNAL",
    identifier: Some("RunMat:setfield:InternalError"),
    when: "Internal conversion/allocation failed while assigning values.",
    message: "setfield: internal error",
};

const SETFIELD_ERRORS: [BuiltinErrorDescriptor; 14] = [
    SETFIELD_ERROR_NOT_ENOUGH_INPUTS,
    SETFIELD_ERROR_FIELD_EXPECTED,
    SETFIELD_ERROR_INDEX_SELECTOR_TYPE,
    SETFIELD_ERROR_INDEX_INVALID,
    SETFIELD_ERROR_FIELD_NAME_TYPE,
    SETFIELD_ERROR_INDEX_SHAPE,
    SETFIELD_ERROR_NON_STRUCT_ASSIGNMENT,
    SETFIELD_ERROR_INDEX_OUT_OF_BOUNDS,
    SETFIELD_ERROR_MISSING_FIELD,
    SETFIELD_ERROR_PROPERTY_PRIVATE_ACCESS,
    SETFIELD_ERROR_PROPERTY_STATIC_ACCESS,
    SETFIELD_ERROR_OBJECT_PROPERTY,
    SETFIELD_ERROR_INVALID_HANDLE,
    SETFIELD_ERROR_INTERNAL,
];

pub const SETFIELD_DESCRIPTOR: BuiltinDescriptor = BuiltinDescriptor {
    signatures: &SETFIELD_SIGNATURES,
    output_mode: BuiltinOutputMode::Fixed,
    completion_policy: BuiltinCompletionPolicy::Public,
    errors: &SETFIELD_ERRORS,
};

fn setfield_flow(message: impl Into<String>) -> RuntimeError {
    setfield_error_with_message(
        format!("{}: {}", SETFIELD_ERROR_INTERNAL.message, message.into()),
        &SETFIELD_ERROR_INTERNAL,
    )
}

fn setfield_error_with_message(
    message: impl Into<String>,
    error: &'static BuiltinErrorDescriptor,
) -> RuntimeError {
    let mut builder = build_runtime_error(message).with_builtin(BUILTIN_NAME);
    if let Some(identifier) = error.identifier {
        builder = builder.with_identifier(identifier);
    }
    builder.build()
}

fn setfield_private_access(message: impl Into<String>) -> RuntimeError {
    setfield_error_with_message(message, &SETFIELD_ERROR_PROPERTY_PRIVATE_ACCESS)
}

fn setfield_static_access(message: impl Into<String>) -> RuntimeError {
    setfield_error_with_message(message, &SETFIELD_ERROR_PROPERTY_STATIC_ACCESS)
}

fn remap_setfield_flow(err: RuntimeError, prefix: Option<&str>) -> RuntimeError {
    let mut message = err.message().to_string();
    if let Some(prefix) = prefix {
        if !message.starts_with(prefix) {
            message = format!("{prefix}{message}");
        }
    }
    let mut builder = build_runtime_error(message).with_builtin(BUILTIN_NAME);
    if let Some(identifier) = err.identifier() {
        builder = builder.with_identifier(identifier);
    }
    builder.with_source(err).build()
}

fn is_undefined_function(err: &RuntimeError) -> bool {
    err.identifier() == Some(crate::IDENT_UNDEFINED_FUNCTION)
}

#[runtime_builtin(
    name = "setfield",
    category = "structs/core",
    summary = "Assign values into struct fields, nested fields, or struct-array elements.",
    keywords = "setfield,struct,assignment,object property",
    type_resolver(setfield_type),
    descriptor(crate::builtins::structs::core::setfield::SETFIELD_DESCRIPTOR),
    integer_capabilities(crate::builtins::structs::core::setfield::SETFIELD_INTEGER_CAPABILITIES),
    builtin_path = "crate::builtins::structs::core::setfield"
)]
async fn setfield_builtin(base: Value, rest: Vec<Value>) -> BuiltinResult<Value> {
    let parsed = parse_arguments(rest)?;
    let ParsedArguments {
        leading_index,
        steps,
        value,
    } = parsed;
    assign_value(base, leading_index, steps, value).await
}

struct ParsedArguments {
    leading_index: Option<IndexSelector>,
    steps: Vec<FieldStep>,
    value: Value,
}

struct FieldStep {
    name: String,
    index: Option<IndexSelector>,
}

#[derive(Clone)]
struct IndexSelector {
    components: Vec<IndexComponent>,
}

#[derive(Clone)]
enum IndexComponent {
    Scalar(usize),
    End,
}

fn parse_arguments(mut rest: Vec<Value>) -> BuiltinResult<ParsedArguments> {
    if rest.len() < 2 {
        return Err(setfield_flow(SETFIELD_ERROR_NOT_ENOUGH_INPUTS.message));
    }

    let value = rest
        .pop()
        .expect("rest contains at least two elements after early return");

    let mut parsed = ParsedArguments {
        leading_index: None,
        steps: Vec::new(),
        value,
    };

    if let Some(first) = rest.first() {
        if is_index_selector(first) {
            let selector = rest.remove(0);
            parsed.leading_index = Some(parse_index_selector(selector)?);
        }
    }

    if rest.is_empty() {
        return Err(setfield_flow(SETFIELD_ERROR_FIELD_EXPECTED.message));
    }

    let mut iter = rest.into_iter().peekable();
    while let Some(arg) = iter.next() {
        let name = parse_field_name(arg)?;
        let mut step = FieldStep { name, index: None };
        if let Some(next) = iter.peek() {
            if is_index_selector(next) {
                let selector = iter.next().unwrap();
                step.index = Some(parse_index_selector(selector)?);
            }
        }
        parsed.steps.push(step);
    }

    if parsed.steps.is_empty() {
        return Err(setfield_flow(SETFIELD_ERROR_FIELD_EXPECTED.message));
    }

    Ok(parsed)
}

async fn assign_value(
    base: Value,
    leading_index: Option<IndexSelector>,
    steps: Vec<FieldStep>,
    rhs: Value,
) -> BuiltinResult<Value> {
    if steps.is_empty() {
        return Err(setfield_flow(SETFIELD_ERROR_FIELD_EXPECTED.message));
    }
    if let Some(selector) = leading_index {
        assign_with_leading_index(base, &selector, &steps, rhs).await
    } else {
        assign_without_leading_index(base, &steps, rhs).await
    }
}

async fn assign_with_leading_index(
    base: Value,
    selector: &IndexSelector,
    steps: &[FieldStep],
    rhs: Value,
) -> BuiltinResult<Value> {
    match base {
        Value::Cell(cell) => assign_into_struct_array(cell, selector, steps, rhs).await,
        other => Err(setfield_flow(format!(
            "setfield: leading indices require a struct array, got {other:?}"
        ))),
    }
}

async fn assign_without_leading_index(
    base: Value,
    steps: &[FieldStep],
    rhs: Value,
) -> BuiltinResult<Value> {
    match base {
        Value::Struct(struct_value) => assign_into_struct(struct_value, steps, rhs).await,
        Value::Object(object) => assign_into_object(object, steps, rhs).await,
        Value::Cell(cell) if is_struct_array(&cell) => {
            if cell.data.is_empty() {
                Err(setfield_flow(
                    "setfield: struct array is empty; supply indices in a cell array",
                ))
            } else {
                let selector = IndexSelector {
                    components: vec![IndexComponent::Scalar(1)],
                };
                assign_into_struct_array(cell, &selector, steps, rhs).await
            }
        }
        Value::HandleObject(handle) => assign_into_handle(handle, steps, rhs).await,
        Value::Listener(_) => Err(setfield_flow(
            "setfield: listeners do not support direct field assignment",
        )),
        other => Err(setfield_flow(format!(
            "setfield unsupported on this value for field '{}': {other:?}",
            steps.first().map(|s| s.name.as_str()).unwrap_or_default()
        ))),
    }
}

async fn assign_into_struct_array(
    mut cell: CellArray,
    selector: &IndexSelector,
    steps: &[FieldStep],
    rhs: Value,
) -> BuiltinResult<Value> {
    if selector.components.is_empty() {
        return Err(setfield_flow(
            "setfield: index cell must contain at least one element",
        ));
    }

    let resolved = resolve_indices(&Value::Cell(cell.clone()), selector)?;

    let position = match resolved.len() {
        1 => {
            let idx = resolved[0];
            if idx == 0 || idx > cell.data.len() {
                return Err(setfield_flow(SETFIELD_ERROR_INDEX_OUT_OF_BOUNDS.message));
            }
            idx - 1
        }
        2 => {
            let row = resolved[0];
            let col = resolved[1];
            if row == 0 || row > cell.rows || col == 0 || col > cell.cols {
                return Err(setfield_flow(SETFIELD_ERROR_INDEX_OUT_OF_BOUNDS.message));
            }
            (row - 1) * cell.cols + (col - 1)
        }
        _ => {
            return Err(setfield_flow(
                "setfield: indexing with more than two indices is not supported yet",
            ));
        }
    };

    let handle = cell
        .data
        .get(position)
        .ok_or_else(|| setfield_flow(SETFIELD_ERROR_INDEX_OUT_OF_BOUNDS.message))?
        .clone();

    let current = handle.clone();
    let updated = assign_into_value(current, steps, rhs).await?;
    cell.data[position] = updated;
    Ok(Value::Cell(cell))
}

#[async_recursion::async_recursion(?Send)]
async fn assign_into_value(value: Value, steps: &[FieldStep], rhs: Value) -> BuiltinResult<Value> {
    if steps.is_empty() {
        return Ok(rhs);
    }
    match value {
        Value::Struct(struct_value) => assign_into_struct(struct_value, steps, rhs).await,
        Value::Object(object) => assign_into_object(object, steps, rhs).await,
        Value::Cell(cell) => assign_into_cell(cell, steps, rhs).await,
        Value::HandleObject(handle) => assign_into_handle(handle, steps, rhs).await,
        Value::Listener(_) => Err(setfield_flow(
            "setfield: listeners do not support nested field assignment",
        )),
        other => Err(setfield_flow(format!(
            "Struct contents assignment to a {other:?} object is not supported."
        ))),
    }
}

#[async_recursion::async_recursion(?Send)]
async fn assign_into_struct(
    mut struct_value: StructValue,
    steps: &[FieldStep],
    rhs: Value,
) -> BuiltinResult<Value> {
    let (first, rest) = steps
        .split_first()
        .expect("steps is non-empty when assign_into_struct is called");

    if rest.is_empty() {
        if let Some(selector) = &first.index {
            let current = struct_value
                .fields
                .get(&first.name)
                .cloned()
                .ok_or_else(|| format!("Reference to non-existent field '{}'.", first.name))?;
            let updated = assign_with_selector(current, selector, &[], rhs).await?;
            struct_value.fields.insert(first.name.clone(), updated);
        } else {
            struct_value.fields.insert(first.name.clone(), rhs);
        }
        return Ok(Value::Struct(struct_value));
    }

    if let Some(selector) = &first.index {
        let current = struct_value
            .fields
            .get(&first.name)
            .cloned()
            .ok_or_else(|| format!("Reference to non-existent field '{}'.", first.name))?;
        let updated = assign_with_selector(current, selector, rest, rhs).await?;
        struct_value.fields.insert(first.name.clone(), updated);
        return Ok(Value::Struct(struct_value));
    }

    let current = struct_value
        .fields
        .get(&first.name)
        .cloned()
        .unwrap_or_else(|| Value::Struct(StructValue::new()));
    let updated = assign_into_value(current, rest, rhs).await?;
    struct_value.fields.insert(first.name.clone(), updated);
    Ok(Value::Struct(struct_value))
}

async fn assign_into_object(
    mut object: ObjectInstance,
    steps: &[FieldStep],
    rhs: Value,
) -> BuiltinResult<Value> {
    let (first, rest) = steps
        .split_first()
        .expect("steps is non-empty when assign_into_object is called");

    if first.index.is_some() {
        return Err(setfield_flow(
            "setfield: indexing into object properties is not currently supported",
        ));
    }

    if rest.is_empty() {
        write_object_property(&mut object, &first.name, rhs).await?;
        return Ok(Value::Object(object));
    }

    let current = read_object_property(&object, &first.name).await?;
    let updated = assign_into_value(current, rest, rhs).await?;
    write_object_property(&mut object, &first.name, updated).await?;
    Ok(Value::Object(object))
}

async fn assign_into_cell(
    cell: CellArray,
    steps: &[FieldStep],
    rhs: Value,
) -> BuiltinResult<Value> {
    let (first, rest) = steps
        .split_first()
        .expect("steps is non-empty when assign_into_cell is called");

    let selector = first.index.as_ref().ok_or_else(|| {
        setfield_flow("setfield: cell array assignments require indices in a cell array")
    })?;
    if rest.is_empty() {
        assign_with_selector(Value::Cell(cell), selector, &[], rhs).await
    } else {
        assign_with_selector(Value::Cell(cell), selector, rest, rhs).await
    }
}

#[async_recursion::async_recursion(?Send)]
async fn assign_with_selector(
    value: Value,
    selector: &IndexSelector,
    rest: &[FieldStep],
    rhs: Value,
) -> BuiltinResult<Value> {
    let host_value = gather_if_needed_async(&value)
        .await
        .map_err(|flow| remap_setfield_flow(flow, Some("setfield: ")))?;
    match host_value {
        Value::Cell(mut cell) => {
            let resolved = resolve_indices(&Value::Cell(cell.clone()), selector)?;
            let position = match resolved.len() {
                1 => {
                    let idx = resolved[0];
                    if idx == 0 || idx > cell.data.len() {
                        return Err(setfield_flow(SETFIELD_ERROR_INDEX_OUT_OF_BOUNDS.message));
                    }
                    idx - 1
                }
                2 => {
                    let row = resolved[0];
                    let col = resolved[1];
                    if row == 0 || row > cell.rows || col == 0 || col > cell.cols {
                        return Err(setfield_flow(SETFIELD_ERROR_INDEX_OUT_OF_BOUNDS.message));
                    }
                    (row - 1) * cell.cols + (col - 1)
                }
                _ => {
                    return Err(setfield_flow(
                        "setfield: indexing with more than two indices is not supported yet",
                    ));
                }
            };

            let handle = cell
                .data
                .get(position)
                .ok_or_else(|| setfield_flow(SETFIELD_ERROR_INDEX_OUT_OF_BOUNDS.message))?
                .clone();
            let existing = handle.clone();
            let new_value = if rest.is_empty() {
                rhs
            } else {
                assign_into_value(existing, rest, rhs).await?
            };
            cell.data[position] = new_value;
            Ok(Value::Cell(cell))
        }
        Value::Tensor(mut tensor) => {
            if !rest.is_empty() {
                return Err(setfield_flow(
                    "setfield: cannot traverse deeper fields after indexing into a numeric tensor",
                ));
            }
            assign_tensor_element(&mut tensor, selector, rhs)?;
            Ok(Value::Tensor(tensor))
        }
        Value::LogicalArray(mut logical) => {
            if !rest.is_empty() {
                return Err(setfield_flow(
                    "setfield: cannot traverse deeper fields after indexing into a logical array",
                ));
            }
            assign_logical_element(&mut logical, selector, rhs)?;
            Ok(Value::LogicalArray(logical))
        }
        Value::StringArray(mut sa) => {
            if !rest.is_empty() {
                return Err(setfield_flow(
                    "setfield: cannot traverse deeper fields after indexing into a string array",
                ));
            }
            assign_string_array_element(&mut sa, selector, rhs)?;
            Ok(Value::StringArray(sa))
        }
        Value::CharArray(mut ca) => {
            if !rest.is_empty() {
                return Err(setfield_flow(
                    "setfield: cannot traverse deeper fields after indexing into a char array",
                ));
            }
            assign_char_array_element(&mut ca, selector, rhs)?;
            Ok(Value::CharArray(ca))
        }
        Value::ComplexTensor(mut tensor) => {
            if !rest.is_empty() {
                return Err(setfield_flow(
                    "setfield: cannot traverse deeper fields after indexing into a complex tensor",
                ));
            }
            assign_complex_tensor_element(&mut tensor, selector, rhs)?;
            Ok(Value::ComplexTensor(tensor))
        }
        other => Err(setfield_flow(format!(
            "Struct contents assignment to a {other:?} object is not supported."
        ))),
    }
}

fn assign_tensor_element(
    tensor: &mut Tensor,
    selector: &IndexSelector,
    rhs: Value,
) -> BuiltinResult<()> {
    let resolved = resolve_indices(&Value::Tensor(tensor.clone()), selector)?;
    let value = value_to_numeric_scalar(rhs)?;
    match resolved.len() {
        1 => {
            let idx = resolved[0];
            if idx == 0 || idx > tensor.len() {
                return Err(setfield_flow(SETFIELD_ERROR_INDEX_OUT_OF_BOUNDS.message));
            }
            tensor
                .set_numeric_assignment_at(idx - 1, value)
                .map_err(setfield_flow)
        }
        2 => {
            let row = resolved[0];
            let col = resolved[1];
            if row == 0 || row > tensor.rows() || col == 0 || col > tensor.cols() {
                return Err(setfield_flow(SETFIELD_ERROR_INDEX_OUT_OF_BOUNDS.message));
            }
            let pos = (row - 1) + (col - 1) * tensor.rows();
            tensor
                .set_numeric_assignment_at(pos, value)
                .map_err(setfield_flow)
        }
        _ => Err(setfield_flow(
            "setfield: indexing with more than two indices is not supported yet",
        )),
    }
}

fn assign_logical_element(
    logical: &mut LogicalArray,
    selector: &IndexSelector,
    rhs: Value,
) -> BuiltinResult<()> {
    let resolved = resolve_indices(&Value::LogicalArray(logical.clone()), selector)?;
    let value = value_to_bool(rhs)?;
    match resolved.len() {
        1 => {
            let idx = resolved[0];
            if idx == 0 || idx > logical.data.len() {
                return Err(setfield_flow(SETFIELD_ERROR_INDEX_OUT_OF_BOUNDS.message));
            }
            logical.data[idx - 1] = if value { 1 } else { 0 };
            Ok(())
        }
        2 => {
            if logical.shape.len() < 2 {
                return Err(setfield_flow(SETFIELD_ERROR_INDEX_OUT_OF_BOUNDS.message));
            }
            let row = resolved[0];
            let col = resolved[1];
            let rows = logical.shape[0];
            let cols = logical.shape[1];
            if row == 0 || row > rows || col == 0 || col > cols {
                return Err(setfield_flow(SETFIELD_ERROR_INDEX_OUT_OF_BOUNDS.message));
            }
            let pos = (row - 1) + (col - 1) * rows;
            if pos >= logical.data.len() {
                return Err(setfield_flow(SETFIELD_ERROR_INDEX_OUT_OF_BOUNDS.message));
            }
            logical.data[pos] = if value { 1 } else { 0 };
            Ok(())
        }
        _ => Err(setfield_flow(
            "setfield: indexing with more than two indices is not supported yet",
        )),
    }
}

fn assign_string_array_element(
    array: &mut runmat_value::StringArray,
    selector: &IndexSelector,
    rhs: Value,
) -> BuiltinResult<()> {
    let resolved = resolve_indices(&Value::StringArray(array.clone()), selector)?;
    let text = String::try_from(&rhs).map_err(|_| {
        setfield_flow("setfield: string assignments require text-compatible values")
    })?;
    match resolved.len() {
        1 => {
            let idx = resolved[0];
            if idx == 0 || idx > array.data.len() {
                return Err(setfield_flow(SETFIELD_ERROR_INDEX_OUT_OF_BOUNDS.message));
            }
            array.data[idx - 1] = text;
            Ok(())
        }
        2 => {
            let row = resolved[0];
            let col = resolved[1];
            if row == 0 || row > array.rows || col == 0 || col > array.cols {
                return Err(setfield_flow(SETFIELD_ERROR_INDEX_OUT_OF_BOUNDS.message));
            }
            let pos = (row - 1) + (col - 1) * array.rows;
            if pos >= array.data.len() {
                return Err(setfield_flow(SETFIELD_ERROR_INDEX_OUT_OF_BOUNDS.message));
            }
            array.data[pos] = text;
            Ok(())
        }
        _ => Err(setfield_flow(
            "setfield: indexing with more than two indices is not supported yet",
        )),
    }
}

fn assign_char_array_element(
    array: &mut CharArray,
    selector: &IndexSelector,
    rhs: Value,
) -> BuiltinResult<()> {
    let resolved = resolve_indices(&Value::CharArray(array.clone()), selector)?;
    let text = String::try_from(&rhs)
        .map_err(|_| setfield_flow("setfield: char assignments require text-compatible values"))?;
    if text.chars().count() != 1 {
        return Err(setfield_flow(
            "setfield: char array assignments require single characters",
        ));
    }
    let ch = text.chars().next().unwrap();
    match resolved.len() {
        1 => {
            let idx = resolved[0];
            if idx == 0 || idx > array.data.len() {
                return Err(setfield_flow(SETFIELD_ERROR_INDEX_OUT_OF_BOUNDS.message));
            }
            array.data[idx - 1] = ch;
            Ok(())
        }
        2 => {
            let row = resolved[0];
            let col = resolved[1];
            if row == 0 || row > array.rows || col == 0 || col > array.cols {
                return Err(setfield_flow(SETFIELD_ERROR_INDEX_OUT_OF_BOUNDS.message));
            }
            let pos = (row - 1) * array.cols + (col - 1);
            if pos >= array.data.len() {
                return Err(setfield_flow(SETFIELD_ERROR_INDEX_OUT_OF_BOUNDS.message));
            }
            array.data[pos] = ch;
            Ok(())
        }
        _ => Err(setfield_flow(
            "setfield: indexing with more than two indices is not supported yet",
        )),
    }
}

fn assign_complex_tensor_element(
    tensor: &mut ComplexTensor,
    selector: &IndexSelector,
    rhs: Value,
) -> BuiltinResult<()> {
    let resolved = resolve_indices(&Value::ComplexTensor(tensor.clone()), selector)?;
    let (re, im) = match rhs {
        Value::Complex(r, i) => (r, i),
        Value::Num(n) => (n, 0.0),
        Value::Int(i) => (i.to_f64(), 0.0),
        other => {
            return Err(setfield_flow(format!(
                "setfield: cannot assign {other:?} into a complex tensor element"
            )));
        }
    };
    match resolved.len() {
        1 => {
            let idx = resolved[0];
            if idx == 0 || idx > tensor.len() {
                return Err(setfield_flow(SETFIELD_ERROR_INDEX_OUT_OF_BOUNDS.message));
            }
            tensor
                .set_f64_assignment_at(idx - 1, re, im)
                .map_err(setfield_flow)?;
            Ok(())
        }
        2 => {
            let row = resolved[0];
            let col = resolved[1];
            if row == 0 || row > tensor.rows || col == 0 || col > tensor.cols {
                return Err(setfield_flow(SETFIELD_ERROR_INDEX_OUT_OF_BOUNDS.message));
            }
            let pos = (row - 1) + (col - 1) * tensor.rows;
            if pos >= tensor.len() {
                return Err(setfield_flow(SETFIELD_ERROR_INDEX_OUT_OF_BOUNDS.message));
            }
            tensor
                .set_f64_assignment_at(pos, re, im)
                .map_err(setfield_flow)?;
            Ok(())
        }
        _ => Err(setfield_flow(
            "setfield: indexing with more than two indices is not supported yet",
        )),
    }
}

async fn read_object_property(obj: &ObjectInstance, name: &str) -> BuiltinResult<Value> {
    if let Some((prop, _owner)) = crate::class_registry::lookup_property(&obj.class_name, name) {
        if prop.is_static {
            return Err(setfield_flow(format!(
                "You cannot access the static property '{}' through an instance of class '{}'.",
                name, obj.class_name
            )));
        }
        if prop.get_access == MemberAccess::Private {
            return Err(setfield_private_access(format!(
                "You cannot get the '{}' property of '{}' class.",
                name, obj.class_name
            )));
        }
        if prop.is_dependent {
            let getter = object_property_getter_name(name);
            match call_builtin_async(&getter, &[Value::Object(obj.clone())]).await {
                Ok(value) => return Ok(value),
                Err(err) => {
                    if !is_undefined_function(&err) {
                        return Err(remap_setfield_flow(err, None));
                    }
                }
            }
            if let Some(value) = obj.properties.get(&format!("{name}_backing")) {
                return Ok(value.clone());
            }
        }
    }

    if let Some(value) = obj.properties.get(name) {
        return Ok(value.clone());
    }

    if let Some((prop, _owner)) = crate::class_registry::lookup_property(&obj.class_name, name) {
        if prop.get_access == MemberAccess::Private {
            return Err(setfield_private_access(format!(
                "You cannot get the '{}' property of '{}' class.",
                name, obj.class_name
            )));
        }
        return Err(setfield_flow(format!(
            "No public property '{}' for class '{}'.",
            name, obj.class_name
        )));
    }

    Err(setfield_flow(format!(
        "Undefined property '{}' for class {}",
        name, obj.class_name
    )))
}

async fn write_object_property(
    obj: &mut ObjectInstance,
    name: &str,
    rhs: Value,
) -> BuiltinResult<()> {
    if dynamicprops::metadata_assignment(obj, name, rhs.clone())? {
        return Ok(());
    }

    if let Some((prop, _owner)) = crate::class_registry::lookup_property(&obj.class_name, name) {
        if prop.is_static {
            return Err(setfield_static_access(format!(
                "Property '{}' is static; use classref('{}').{}",
                name, obj.class_name, name
            )));
        }
        if prop.set_access == MemberAccess::Private {
            return Err(setfield_private_access(format!(
                "Property '{name}' is private"
            )));
        }
        if prop.is_dependent {
            let setter = object_property_setter_name(name);
            match call_builtin_async(&setter, &[Value::Object(obj.clone()), rhs.clone()]).await {
                Ok(value) => {
                    if let Value::Object(updated) = value {
                        *obj = updated;
                        return Ok(());
                    }
                    return Err(setfield_flow(format!(
                        "Dependent property setter for '{}' must return the updated object",
                        name
                    )));
                }
                Err(err) => {
                    if !is_undefined_function(&err) {
                        return Err(remap_setfield_flow(err, None));
                    }
                }
            }
            obj.properties.insert(format!("{name}_backing"), rhs);
            return Ok(());
        }
    }

    if dynamicprops::dynamic_property_assign(obj, name, rhs.clone())? {
        return Ok(());
    }

    obj.properties.insert(name.to_string(), rhs);
    Ok(())
}

async fn assign_into_handle(
    handle: HandleRef,
    steps: &[FieldStep],
    rhs: Value,
) -> BuiltinResult<Value> {
    if steps.is_empty() {
        return Err(setfield_flow(
            "setfield: expected at least one field name when assigning into a handle",
        ));
    }
    if !crate::is_handle_valid(&handle) {
        return Err(setfield_flow(format!(
            "Invalid or deleted handle object '{}'.",
            handle.class_name
        )));
    }
    let current = runmat_gc::gc_clone_value(&handle.target)
        .map_err(|e| setfield_flow(format!("setfield: invalid handle target: {e}")))?;
    let updated = assign_into_value(current.clone(), steps, rhs).await?;
    runmat_gc::gc_with_value_mut(&handle.target, |target| -> BuiltinResult<()> {
        let target_valid = match target {
            Value::Object(obj) => !matches!(
                obj.properties.get(crate::HANDLE_VALID_FLAG_PROPERTY),
                Some(Value::Bool(false))
            ),
            _ => {
                return Err(setfield_flow(format!(
                    "Invalid or deleted handle object '{}'.",
                    handle.class_name
                )));
            }
        };
        if !target_valid {
            return Err(setfield_flow(format!(
                "Invalid or deleted handle object '{}'.",
                handle.class_name
            )));
        }
        if *target != current {
            return Err(setfield_flow(
                "setfield: handle target changed during asynchronous assignment",
            ));
        }
        runmat_gc::gc_record_handle_write(&handle.target, &updated);
        *target = updated;
        Ok(())
    })
    .map_err(|e| setfield_flow(format!("setfield: invalid handle target: {e}")))??;
    Ok(Value::HandleObject(handle))
}

fn is_index_selector(value: &Value) -> bool {
    matches!(value, Value::Cell(_))
}

fn parse_index_selector(value: Value) -> BuiltinResult<IndexSelector> {
    let Value::Cell(cell) = value else {
        return Err(setfield_flow(SETFIELD_ERROR_INDEX_SELECTOR_TYPE.message));
    };
    let mut components = Vec::with_capacity(cell.data.len());
    for handle in &cell.data {
        let entry = handle;
        components.push(parse_index_component(entry)?);
    }
    Ok(IndexSelector { components })
}

fn parse_index_component(value: &Value) -> BuiltinResult<IndexComponent> {
    match value {
        Value::CharArray(ca) => {
            let text: String = ca.data.iter().collect();
            parse_index_text(text.trim())
        }
        Value::String(s) => parse_index_text(s.trim()),
        Value::StringArray(sa) if sa.data.len() == 1 => parse_index_text(sa.data[0].trim()),
        _ => {
            let idx = parse_positive_scalar(value).map_err(|err| {
                setfield_flow(format!(
                    "setfield: invalid index element ({})",
                    err.message()
                ))
            })?;
            Ok(IndexComponent::Scalar(idx))
        }
    }
}

fn parse_index_text(text: &str) -> BuiltinResult<IndexComponent> {
    if text.eq_ignore_ascii_case("end") {
        return Ok(IndexComponent::End);
    }
    if text == ":" {
        return Err(setfield_flow(
            "setfield: ':' indexing is not currently supported",
        ));
    }
    if text.is_empty() {
        return Err(setfield_flow("setfield: index elements must not be empty"));
    }
    if let Ok(value) = text.parse::<usize>() {
        if value == 0 {
            return Err(setfield_flow("setfield: index must be >= 1"));
        }
        return Ok(IndexComponent::Scalar(value));
    }
    Err(setfield_flow(format!(
        "setfield: invalid index element '{}'",
        text
    )))
}

fn parse_positive_scalar(value: &Value) -> BuiltinResult<usize> {
    if let Value::Int(i) = value {
        return i
            .try_to_usize()
            .filter(|index| *index >= 1)
            .ok_or_else(|| setfield_flow("index must be >= 1"));
    }
    if let Value::Tensor(t) = value {
        if tensor::is_scalar_tensor(t) {
            if let Some(storage) = t.integer_storage() {
                return storage
                    .value_at(0)
                    .and_then(|value| value.try_to_usize())
                    .filter(|index| *index >= 1)
                    .ok_or_else(|| setfield_flow("index must be >= 1"));
            }
        }
    }
    let number = match value {
        Value::Num(n) => *n,
        Value::Tensor(t) if tensor::is_scalar_tensor(t) => tensor::tensor_value_f64(t, 0),
        _ => {
            let repr = format!("{value:?}");
            return Err(setfield_flow(format!(
                "expected positive integer index, got {repr}"
            )));
        }
    };

    if !number.is_finite() {
        return Err(setfield_flow("index must be a finite number"));
    }
    if number.fract() != 0.0 {
        return Err(setfield_flow("index must be an integer"));
    }
    if number <= 0.0 {
        return Err(setfield_flow("index must be >= 1"));
    }
    if number > usize::MAX as f64 || (usize::BITS == 64 && number == usize::MAX as f64) {
        return Err(setfield_flow("index exceeds platform limits"));
    }
    Ok(number as usize)
}

fn parse_field_name(value: Value) -> BuiltinResult<String> {
    match value {
        Value::String(s) => Ok(s),
        Value::StringArray(sa) => {
            if sa.data.len() == 1 {
                Ok(sa.data[0].clone())
            } else {
                Err(setfield_flow(
                    "setfield: field names must be scalar string arrays or character vectors",
                ))
            }
        }
        Value::CharArray(ca) => {
            if ca.rows == 1 {
                Ok(ca.data.iter().collect())
            } else {
                Err(setfield_flow(
                    "setfield: field names must be 1-by-N character vectors",
                ))
            }
        }
        other => Err(setfield_flow(format!(
            "setfield: expected field name, got {other:?}"
        ))),
    }
}

fn resolve_indices(value: &Value, selector: &IndexSelector) -> BuiltinResult<Vec<usize>> {
    let dims = selector.components.len();
    let mut resolved = Vec::with_capacity(dims);
    for (dim_idx, component) in selector.components.iter().enumerate() {
        let index = match component {
            IndexComponent::Scalar(idx) => *idx,
            IndexComponent::End => dimension_length(value, dims, dim_idx)?,
        };
        resolved.push(index);
    }
    Ok(resolved)
}

fn dimension_length(value: &Value, dims: usize, dim_idx: usize) -> BuiltinResult<usize> {
    match value {
        Value::Tensor(tensor) => tensor_dimension_length(tensor, dims, dim_idx),
        Value::Cell(cell) => cell_dimension_length(cell, dims, dim_idx),
        Value::StringArray(array) => string_array_dimension_length(array, dims, dim_idx),
        Value::LogicalArray(logical) => logical_array_dimension_length(logical, dims, dim_idx),
        Value::CharArray(array) => char_array_dimension_length(array, dims, dim_idx),
        Value::ComplexTensor(tensor) => complex_tensor_dimension_length(tensor, dims, dim_idx),
        Value::Num(_) | Value::Int(_) | Value::Bool(_) => {
            if dims == 1 {
                Ok(1)
            } else {
                Err(setfield_flow(
                    "setfield: indexing with more than one dimension is not supported for scalars",
                ))
            }
        }
        other => Err(setfield_flow(format!(
            "Struct contents assignment to a {other:?} object is not supported."
        ))),
    }
}

fn tensor_dimension_length(tensor: &Tensor, dims: usize, dim_idx: usize) -> BuiltinResult<usize> {
    if dims == 1 {
        let total = tensor.len();
        if total == 0 {
            return Err(setfield_flow(
                "Index exceeds the number of array elements (0).",
            ));
        }
        return Ok(total);
    }
    if dims > 2 {
        return Err(setfield_flow(
            "setfield: indexing with more than two indices is not supported yet",
        ));
    }
    let len = if dim_idx == 0 {
        tensor.rows()
    } else {
        tensor.cols()
    };
    if len == 0 {
        return Err(setfield_flow(
            "Index exceeds the number of array elements (0).",
        ));
    }
    Ok(len)
}

fn cell_dimension_length(cell: &CellArray, dims: usize, dim_idx: usize) -> BuiltinResult<usize> {
    if dims == 1 {
        let total = cell.data.len();
        if total == 0 {
            return Err(setfield_flow(
                "Index exceeds the number of array elements (0).",
            ));
        }
        return Ok(total);
    }
    if dims > 2 {
        return Err(setfield_flow(
            "setfield: indexing with more than two indices is not supported yet",
        ));
    }
    let len = if dim_idx == 0 { cell.rows } else { cell.cols };
    if len == 0 {
        return Err(setfield_flow(
            "Index exceeds the number of array elements (0).",
        ));
    }
    Ok(len)
}

fn string_array_dimension_length(
    array: &runmat_value::StringArray,
    dims: usize,
    dim_idx: usize,
) -> BuiltinResult<usize> {
    if dims == 1 {
        let total = array.data.len();
        if total == 0 {
            return Err(setfield_flow(
                "Index exceeds the number of array elements (0).",
            ));
        }
        return Ok(total);
    }
    if dims > 2 {
        return Err(setfield_flow(
            "setfield: indexing with more than two indices is not supported yet",
        ));
    }
    let len = if dim_idx == 0 { array.rows } else { array.cols };
    if len == 0 {
        return Err(setfield_flow(
            "Index exceeds the number of array elements (0).",
        ));
    }
    Ok(len)
}

fn logical_array_dimension_length(
    array: &LogicalArray,
    dims: usize,
    dim_idx: usize,
) -> BuiltinResult<usize> {
    if dims == 1 {
        let total = array.data.len();
        if total == 0 {
            return Err(setfield_flow(
                "Index exceeds the number of array elements (0).",
            ));
        }
        return Ok(total);
    }
    if dims > 2 {
        return Err(setfield_flow(
            "setfield: indexing with more than two indices is not supported yet",
        ));
    }
    if array.shape.len() < dims {
        return Err(setfield_flow(
            "Index exceeds the number of array elements (0).",
        ));
    }
    let len = array.shape[dim_idx];
    if len == 0 {
        return Err(setfield_flow(
            "Index exceeds the number of array elements (0).",
        ));
    }
    Ok(len)
}

fn char_array_dimension_length(
    array: &CharArray,
    dims: usize,
    dim_idx: usize,
) -> BuiltinResult<usize> {
    if dims == 1 {
        let total = array.data.len();
        if total == 0 {
            return Err(setfield_flow(
                "Index exceeds the number of array elements (0).",
            ));
        }
        return Ok(total);
    }
    if dims > 2 {
        return Err(setfield_flow(
            "setfield: indexing with more than two indices is not supported yet",
        ));
    }
    let len = if dim_idx == 0 { array.rows } else { array.cols };
    if len == 0 {
        return Err(setfield_flow(
            "Index exceeds the number of array elements (0).",
        ));
    }
    Ok(len)
}

fn complex_tensor_dimension_length(
    tensor: &ComplexTensor,
    dims: usize,
    dim_idx: usize,
) -> BuiltinResult<usize> {
    if dims == 1 {
        let total = tensor.materialize_f64().len();
        if total == 0 {
            return Err(setfield_flow(
                "Index exceeds the number of array elements (0).",
            ));
        }
        return Ok(total);
    }
    if dims > 2 {
        return Err(setfield_flow(
            "setfield: indexing with more than two indices is not supported yet",
        ));
    }
    let len = if dim_idx == 0 {
        tensor.rows
    } else {
        tensor.cols
    };
    if len == 0 {
        return Err(setfield_flow(
            "Index exceeds the number of array elements (0).",
        ));
    }
    Ok(len)
}

fn value_to_numeric_scalar(value: Value) -> BuiltinResult<NumericScalar> {
    match value {
        Value::Num(n) => Ok(NumericScalar::F64(n)),
        Value::Int(i) => Ok(NumericScalar::from(i)),
        Value::Bool(b) => Ok(NumericScalar::F64(if b { 1.0 } else { 0.0 })),
        Value::Tensor(t) if tensor::is_scalar_tensor(&t) => t
            .numeric_value_at(0)
            .ok_or_else(|| setfield_flow("setfield: invalid numeric tensor storage")),
        other => Err(setfield_flow(format!(
            "setfield: cannot assign {other:?} into a numeric tensor element"
        ))),
    }
}

fn value_to_bool(value: Value) -> BuiltinResult<bool> {
    match value {
        Value::Bool(b) => Ok(b),
        Value::Num(n) => Ok(n != 0.0),
        Value::Int(i) => Ok(!i.is_zero()),
        Value::Tensor(t) if tensor::is_scalar_tensor(&t) => {
            if let Some(storage) = t.integer_storage() {
                Ok(!storage
                    .value_at(0)
                    .ok_or_else(|| setfield_flow("setfield: invalid integer tensor storage"))?
                    .is_zero())
            } else {
                Ok(tensor::tensor_value_f64(&t, 0) != 0.0)
            }
        }
        other => Err(setfield_flow(format!(
            "setfield: cannot assign {other:?} into a logical array element"
        ))),
    }
}

fn is_struct_array(cell: &CellArray) -> bool {
    cell.data
        .iter()
        .all(|handle| matches!(handle, Value::Struct(_)))
}

#[cfg(test)]
pub(crate) mod tests {
    use super::*;
    use runmat_gc::gc_allocate;
    use runmat_value::{
        CellArray, HandleRef, IntValue, IntegerStorage, LogicalArray, ObjectInstance, StructValue,
    };

    fn error_message(err: crate::RuntimeError) -> String {
        err.message().to_string()
    }

    fn run_setfield(base: Value, rest: Vec<Value>) -> BuiltinResult<Value> {
        futures::executor::block_on(setfield_builtin(base, rest))
    }

    #[cfg_attr(target_arch = "wasm32", wasm_bindgen_test::wasm_bindgen_test)]
    #[test]
    fn setfield_creates_scalar_field() {
        let struct_value = StructValue::new();
        let updated = run_setfield(
            Value::Struct(struct_value),
            vec![Value::from("answer"), Value::Num(42.0)],
        )
        .expect("setfield");
        match updated {
            Value::Struct(st) => {
                assert_eq!(
                    st.fields.get("answer"),
                    Some(&Value::Num(42.0)),
                    "field should be inserted"
                );
            }
            other => panic!("expected struct result, got {other:?}"),
        }
    }

    #[cfg_attr(target_arch = "wasm32", wasm_bindgen_test::wasm_bindgen_test)]
    #[test]
    fn setfield_creates_nested_structs() {
        let struct_value = StructValue::new();
        let updated = run_setfield(
            Value::Struct(struct_value),
            vec![
                Value::from("solver"),
                Value::from("name"),
                Value::from("cg"),
            ],
        )
        .expect("setfield");
        match updated {
            Value::Struct(st) => {
                let solver = st.fields.get("solver").expect("solver field");
                match solver {
                    Value::Struct(inner) => {
                        assert_eq!(
                            inner.fields.get("name"),
                            Some(&Value::from("cg")),
                            "inner field should exist"
                        );
                    }
                    other => panic!("expected inner struct, got {other:?}"),
                }
            }
            other => panic!("expected struct result, got {other:?}"),
        }
    }

    #[cfg_attr(target_arch = "wasm32", wasm_bindgen_test::wasm_bindgen_test)]
    #[test]
    fn setfield_updates_struct_array_element() {
        let mut a = StructValue::new();
        a.fields
            .insert("id".to_string(), Value::Int(IntValue::I32(1)));
        let mut b = StructValue::new();
        b.fields
            .insert("id".to_string(), Value::Int(IntValue::I32(2)));
        let array = CellArray::new_with_shape(vec![Value::Struct(a), Value::Struct(b)], vec![1, 2])
            .unwrap();
        let indices =
            CellArray::new_with_shape(vec![Value::Int(IntValue::I32(2))], vec![1, 1]).unwrap();
        let updated = run_setfield(
            Value::Cell(array),
            vec![
                Value::Cell(indices),
                Value::from("id"),
                Value::Int(IntValue::I32(42)),
            ],
        )
        .expect("setfield");
        match updated {
            Value::Cell(cell) => {
                let second = &cell.data[1].clone();
                match second {
                    Value::Struct(st) => {
                        assert_eq!(st.fields.get("id"), Some(&Value::Int(IntValue::I32(42))));
                    }
                    other => panic!("expected struct element, got {other:?}"),
                }
            }
            other => panic!("expected cell array, got {other:?}"),
        }
    }

    #[test]
    fn setfield_index_selector_reads_typed_integer_storage_exactly() {
        let mut a = StructValue::new();
        a.fields
            .insert("id".to_string(), Value::Int(IntValue::I32(1)));
        let mut b = StructValue::new();
        b.fields
            .insert("id".to_string(), Value::Int(IntValue::I32(2)));
        let array = CellArray::new_with_shape(vec![Value::Struct(a), Value::Struct(b)], vec![1, 2])
            .unwrap();
        let index_tensor =
            Tensor::new_integer(IntegerStorage::U64(vec![2]), vec![1, 1]).expect("index tensor");
        let indices = CellArray::new_with_shape(vec![Value::Tensor(index_tensor)], vec![1, 1])
            .expect("index cell");

        let updated = run_setfield(
            Value::Cell(array),
            vec![
                Value::Cell(indices),
                Value::from("id"),
                Value::Int(IntValue::I32(42)),
            ],
        )
        .expect("setfield");
        match updated {
            Value::Cell(cell) => match &cell.data[1] {
                Value::Struct(st) => {
                    assert_eq!(st.fields.get("id"), Some(&Value::Int(IntValue::I32(42))));
                }
                other => panic!("expected struct element, got {other:?}"),
            },
            other => panic!("expected cell array, got {other:?}"),
        }

        assert!(parse_positive_scalar(&Value::Num(usize::MAX as f64)).is_err());
        assert!(parse_positive_scalar(&Value::Num(usize::MAX as f64 + 1.0)).is_err());
    }

    #[test]
    fn setfield_scalar_assignment_reads_typed_integer_storage_exactly() {
        let mut root = StructValue::new();
        root.fields.insert(
            "values".to_string(),
            Value::Tensor(Tensor::new(vec![10.0, 20.0], vec![1, 2]).unwrap()),
        );
        root.fields.insert(
            "mask".to_string(),
            Value::LogicalArray(LogicalArray::new(vec![0, 0], vec![1, 2]).unwrap()),
        );

        let index_tensor =
            Tensor::new_integer(IntegerStorage::U64(vec![2]), vec![1, 1]).expect("index tensor");
        let index =
            CellArray::new_with_shape(vec![Value::Tensor(index_tensor)], vec![1, 1]).unwrap();
        let rhs =
            Tensor::new_integer(IntegerStorage::U64(vec![77]), vec![1, 1]).expect("rhs tensor");
        let updated = run_setfield(
            Value::Struct(root),
            vec![
                Value::from("values"),
                Value::Cell(index),
                Value::Tensor(rhs),
            ],
        )
        .expect("numeric setfield");

        let logical_index =
            Tensor::new_integer(IntegerStorage::U64(vec![2]), vec![1, 1]).expect("logical index");
        let logical_index =
            CellArray::new_with_shape(vec![Value::Tensor(logical_index)], vec![1, 1]).unwrap();
        let logical_rhs =
            Tensor::new_integer(IntegerStorage::U64(vec![1]), vec![1, 1]).expect("logical rhs");
        let updated = run_setfield(
            updated,
            vec![
                Value::from("mask"),
                Value::Cell(logical_index),
                Value::Tensor(logical_rhs),
            ],
        )
        .expect("logical setfield");

        match updated {
            Value::Struct(st) => {
                match st.fields.get("values").expect("values") {
                    Value::Tensor(tensor) => {
                        assert_eq!(tensor.materialize_f64(), vec![10.0, 77.0])
                    }
                    other => panic!("expected tensor field, got {other:?}"),
                }
                match st.fields.get("mask").expect("mask") {
                    Value::LogicalArray(array) => assert_eq!(array.data, vec![0, 1]),
                    other => panic!("expected logical field, got {other:?}"),
                }
            }
            other => panic!("expected struct, got {other:?}"),
        }
    }

    #[test]
    fn setfield_preserves_exact_integer_destination_storage() {
        let large = 9_007_199_254_740_993_u64;
        let mut root = StructValue::new();
        root.fields.insert(
            "wide".to_string(),
            Value::Tensor(
                Tensor::new_integer(IntegerStorage::U64(vec![large, large + 1]), vec![1, 2])
                    .unwrap(),
            ),
        );
        let index =
            CellArray::new_with_shape(vec![Value::Int(IntValue::U8(2))], vec![1, 1]).unwrap();
        let updated = run_setfield(
            Value::Struct(root),
            vec![
                Value::from("wide"),
                Value::Cell(index),
                Value::Int(IntValue::U64(u64::MAX)),
            ],
        )
        .expect("exact integer setfield");

        let Value::Struct(root) = updated else {
            panic!("expected struct");
        };
        let Value::Tensor(tensor) = root.fields.get("wide").expect("wide field") else {
            panic!("expected tensor");
        };
        assert_eq!(tensor.numeric_value_at(0), Some(NumericScalar::U64(large)));
        assert_eq!(
            tensor.numeric_value_at(1),
            Some(NumericScalar::U64(u64::MAX))
        );
    }

    #[cfg_attr(target_arch = "wasm32", wasm_bindgen_test::wasm_bindgen_test)]
    #[test]
    fn setfield_assigns_into_cell_then_struct() {
        let mut inner1 = StructValue::new();
        inner1.fields.insert("value".to_string(), Value::Num(1.0));
        let mut inner2 = StructValue::new();
        inner2.fields.insert("value".to_string(), Value::Num(2.0));
        let cell = CellArray::new_with_shape(
            vec![Value::Struct(inner1), Value::Struct(inner2)],
            vec![1, 2],
        )
        .unwrap();
        let mut root = StructValue::new();
        root.fields.insert("samples".to_string(), Value::Cell(cell));

        let index_cell =
            CellArray::new_with_shape(vec![Value::Int(IntValue::I32(2))], vec![1, 1]).unwrap();
        let updated = run_setfield(
            Value::Struct(root),
            vec![
                Value::from("samples"),
                Value::Cell(index_cell),
                Value::from("value"),
                Value::Num(10.0),
            ],
        )
        .expect("setfield");

        match updated {
            Value::Struct(st) => {
                let samples = st.fields.get("samples").expect("samples field");
                match samples {
                    Value::Cell(cell) => {
                        let value = &cell.data[1].clone();
                        match value {
                            Value::Struct(inner) => {
                                assert_eq!(inner.fields.get("value"), Some(&Value::Num(10.0)));
                            }
                            other => panic!("expected struct, got {other:?}"),
                        }
                    }
                    other => panic!("expected cell array, got {other:?}"),
                }
            }
            other => panic!("expected struct, got {other:?}"),
        }
    }

    #[cfg_attr(target_arch = "wasm32", wasm_bindgen_test::wasm_bindgen_test)]
    #[test]
    fn setfield_struct_array_with_end_index() {
        let mut first = StructValue::new();
        first
            .fields
            .insert("id".to_string(), Value::Int(IntValue::I32(1)));
        let mut second = StructValue::new();
        second
            .fields
            .insert("id".to_string(), Value::Int(IntValue::I32(2)));
        let array = CellArray::new_with_shape(
            vec![Value::Struct(first), Value::Struct(second)],
            vec![1, 2],
        )
        .unwrap();
        let index_cell = CellArray::new_with_shape(vec![Value::from("end")], vec![1, 1]).unwrap();
        let updated = run_setfield(
            Value::Cell(array),
            vec![
                Value::Cell(index_cell),
                Value::from("id"),
                Value::Int(IntValue::I32(99)),
            ],
        )
        .expect("setfield");
        match updated {
            Value::Cell(cell) => {
                let second = &cell.data[1].clone();
                match second {
                    Value::Struct(st) => {
                        assert_eq!(st.fields.get("id"), Some(&Value::Int(IntValue::I32(99))));
                    }
                    other => panic!("expected struct element, got {other:?}"),
                }
            }
            other => panic!("expected cell array result, got {other:?}"),
        }
    }

    #[cfg_attr(target_arch = "wasm32", wasm_bindgen_test::wasm_bindgen_test)]
    #[test]
    fn setfield_assigns_object_property() {
        let mut class_def = crate::class_registry::RuntimeClass {
            name: "Simple".to_string(),
            parent: None,
            properties: Default::default(),
            methods: Default::default(),
        };
        class_def.properties.insert(
            "x".to_string(),
            crate::class_registry::RuntimeProperty {
                name: "x".to_string(),
                is_static: false,
                is_constant: false,
                is_dependent: false,
                get_access: MemberAccess::Public,
                set_access: MemberAccess::Public,
                default_value: None,
            },
        );
        crate::class_registry::register_class(class_def);

        let mut obj = ObjectInstance::new("Simple".to_string());
        obj.properties.insert("x".to_string(), Value::Num(0.0));

        let updated = run_setfield(Value::Object(obj), vec![Value::from("x"), Value::Num(5.0)])
            .expect("setfield");

        match updated {
            Value::Object(o) => {
                assert_eq!(o.properties.get("x"), Some(&Value::Num(5.0)));
            }
            other => panic!("expected object result, got {other:?}"),
        }
    }

    #[cfg_attr(target_arch = "wasm32", wasm_bindgen_test::wasm_bindgen_test)]
    #[test]
    fn setfield_errors_when_indexing_missing_field() {
        let struct_value = StructValue::new();
        let index_cell =
            CellArray::new_with_shape(vec![Value::Int(IntValue::I32(1))], vec![1, 1]).unwrap();
        let err = error_message(
            run_setfield(
                Value::Struct(struct_value),
                vec![
                    Value::from("missing"),
                    Value::Cell(index_cell),
                    Value::Num(1.0),
                ],
            )
            .expect_err("setfield should fail when field is missing"),
        );
        assert!(
            err.contains("Reference to non-existent field 'missing'."),
            "unexpected error message: {err}"
        );
    }

    #[cfg_attr(target_arch = "wasm32", wasm_bindgen_test::wasm_bindgen_test)]
    #[test]
    fn setfield_errors_on_static_property_assignment() {
        let mut class_def = crate::class_registry::RuntimeClass {
            name: "StaticSetfield".to_string(),
            parent: None,
            properties: Default::default(),
            methods: Default::default(),
        };
        class_def.properties.insert(
            "version".to_string(),
            crate::class_registry::RuntimeProperty {
                name: "version".to_string(),
                is_static: true,
                is_constant: false,
                is_dependent: false,
                get_access: MemberAccess::Public,
                set_access: MemberAccess::Public,
                default_value: None,
            },
        );
        crate::class_registry::register_class(class_def);

        let obj = ObjectInstance::new("StaticSetfield".to_string());
        let err = error_message(
            run_setfield(
                Value::Object(obj),
                vec![Value::from("version"), Value::Num(2.0)],
            )
            .expect_err("setfield should reject static property writes"),
        );
        assert!(
            err.contains("Property 'version' is static"),
            "unexpected error message: {err}"
        );
    }

    #[cfg_attr(target_arch = "wasm32", wasm_bindgen_test::wasm_bindgen_test)]
    #[test]
    fn setfield_rejects_inherited_static_property_assignment() {
        let parent_name = "runmat.unittest.StaticSetfieldParent";
        let child_name = "runmat.unittest.StaticSetfieldChild";

        let mut parent = crate::class_registry::RuntimeClass {
            name: parent_name.to_string(),
            parent: None,
            properties: Default::default(),
            methods: Default::default(),
        };
        parent.properties.insert(
            "version".to_string(),
            crate::class_registry::RuntimeProperty {
                name: "version".to_string(),
                is_static: true,
                is_constant: false,
                is_dependent: false,
                get_access: MemberAccess::Public,
                set_access: MemberAccess::Public,
                default_value: None,
            },
        );
        crate::class_registry::register_class(parent);
        crate::class_registry::register_class(crate::class_registry::RuntimeClass {
            name: child_name.to_string(),
            parent: Some(parent_name.to_string()),
            properties: Default::default(),
            methods: Default::default(),
        });

        let obj = ObjectInstance::new(child_name.to_string());
        let err = error_message(
            run_setfield(
                Value::Object(obj),
                vec![Value::from("version"), Value::Num(2.0)],
            )
            .expect_err("setfield should reject inherited static property writes"),
        );
        assert!(
            err.contains("Property 'version' is static"),
            "unexpected error message: {err}"
        );
    }

    #[cfg_attr(target_arch = "wasm32", wasm_bindgen_test::wasm_bindgen_test)]
    #[test]
    fn setfield_updates_handle_target() {
        let mut inner = ObjectInstance::new("PointHandle".to_string());
        inner.properties.insert("x".to_string(), Value::Num(0.0));
        let gc_ptr = gc_allocate(Value::Object(inner)).expect("gc allocation");
        let handle_ptr = gc_ptr;
        let handle = HandleRef {
            class_name: "PointHandle".to_string(),
            target: handle_ptr,
            valid: true,
        };

        let updated = run_setfield(
            Value::HandleObject(handle.clone()),
            vec![Value::from("x"), Value::Num(7.0)],
        )
        .expect("setfield handle update");

        match updated {
            Value::HandleObject(h) => assert!(crate::is_handle_valid(&h)),
            other => panic!("expected handle, got {other:?}"),
        }

        let pointee = runmat_gc::gc_clone_value(&gc_ptr).expect("valid handle target");
        match pointee {
            Value::Object(obj) => {
                assert_eq!(obj.properties.get("x"), Some(&Value::Num(7.0)));
            }
            other => panic!("expected object pointee, got {other:?}"),
        }
    }

    #[cfg_attr(target_arch = "wasm32", wasm_bindgen_test::wasm_bindgen_test)]
    #[test]
    #[cfg(feature = "wgpu")]
    fn setfield_gpu_tensor_indexing_gathers_to_host() {
        use runmat_accelerate::backend::wgpu::provider::{
            register_wgpu_provider, WgpuProviderOptions,
        };
        use runmat_accelerate_api::HostTensorView;

        if runmat_accelerate_api::provider().is_none()
            && register_wgpu_provider(WgpuProviderOptions::default()).is_err()
        {
            runmat_accelerate::simple_provider::register_inprocess_provider();
        }

        let provider = runmat_accelerate_api::provider().expect("accel provider");
        let data = [1.0, 2.0, 3.0, 4.0];
        let shape = [2usize, 2usize];
        let view = HostTensorView {
            data: &data,
            shape: &shape,
        };
        let handle = provider.upload(&view).expect("upload");

        let mut root = StructValue::new();
        root.fields
            .insert("values".to_string(), Value::GpuTensor(handle));

        let index_cell = CellArray::new_with_shape(
            vec![Value::Int(IntValue::I32(2)), Value::Int(IntValue::I32(2))],
            vec![1, 2],
        )
        .unwrap();

        let updated = run_setfield(
            Value::Struct(root),
            vec![
                Value::from("values"),
                Value::Cell(index_cell),
                Value::Num(99.0),
            ],
        )
        .expect("setfield gpu value");

        match updated {
            Value::Struct(st) => {
                let values = st.fields.get("values").expect("values field");
                match values {
                    Value::Tensor(tensor) => {
                        assert_eq!(tensor.shape, vec![2, 2]);
                        assert_eq!(tensor.numeric_value_at(3), Some(NumericScalar::F32(99.0)));
                    }
                    other => panic!("expected tensor after gather, got {other:?}"),
                }
            }
            other => panic!("expected struct result, got {other:?}"),
        }
    }

    #[cfg_attr(target_arch = "wasm32", wasm_bindgen_test::wasm_bindgen_test)]
    #[test]
    fn setfield_undefined_detection_requires_identifier() {
        let with_identifier = build_runtime_error("missing")
            .with_identifier(crate::IDENT_UNDEFINED_FUNCTION)
            .build();
        assert!(is_undefined_function(&with_identifier));

        let message_only =
            build_runtime_error(format!("{} message only", crate::IDENT_UNDEFINED_FUNCTION))
                .build();
        assert!(
            !is_undefined_function(&message_only),
            "message-only undefined markers should not trigger setter fallback"
        );
    }
}