gh-104: Add APPEND.

Author: python-processing-unit

docs/SPECIFICATION.html

@@ -807,6 +807,8 @@
 
 - `TNS: SCAT(TNS: src, TNS: dst, TNS: ind)` = MUST return a copy of `dst` with a rectangular slice replaced by `src`. `ind` MUST encode one inclusive `[lo, hi]` range pair per destination dimension. The selected slice shape MUST exactly match the shape of `src`, and out-of-range indices MUST raise a runtime error.
 
+- `TNS: APPEND(ANY: elem, TNS: tns)` = MUST return a new one-dimensional tensor equal to `tns` with `elem` appended as the last element. If `tns` is not one-dimensional the operator MUST raise a runtime error. Prefix `TNS` values MAY contain heterogeneous element types; `APPEND` therefore MUST accept any element type and simply append it as the last element.
+
 - `TNS: FILL(TNS: tensor, ANY: value)` = MUST return a new tensor with the same shape as `tensor`, filled with `value`. `value` MUST satisfy the target tensor's element-type constraints.
 
 - `TNS: CONV(TNS: x, TNS: kernel, INT: stride_w = 1, INT: stride_h = 1, INT: pad_w = 0, INT: pad_h = 0, TNS: bias = [])` = MUST support both the legacy two-argument N-dimensional convolution form and the extended 2-D multi-output form. In the legacy form, `kernel` MUST have the same rank as `x`, every kernel dimension length MUST be odd, boundary sampling MUST clamp to the nearest valid index, and the result MUST have the same shape as `x`. In the extended form, when any keyword argument is supplied and `x` is rank 3 while `kernel` is rank 4 with shape `[kw, kh, in_c, out_c]`, the operator MUST perform 2-D convolution with the given strides, explicit zero padding, and optional per-output-channel bias, returning shape `[out_w, out_h, out_c]`. Where both inputs are `INT`, the output MUST be `INT`; otherwise it MUST be `FLT`.

src/builtins.c

@@ -3716,6 +3716,46 @@ static Value builtin_fill(Interpreter* interp, Value* args, int argc, Expr** arg
     return out;
 }
 
+// APPEND: append a single element to a 1-D tensor and return a new tensor
+static Value builtin_append(Interpreter* interp, Value* args, int argc, Expr** arg_nodes, Env* env, int line, int col) {
+    (void)arg_nodes; (void)env; (void)argc;
+    if (args[1].type != VAL_TNS) {
+        RUNTIME_ERROR(interp, "APPEND expects (ANY, TNS)", line, col);
+    }
+    Tensor* t = args[1].as.tns;
+    if (!t) {
+        RUNTIME_ERROR(interp, "Invalid target tensor", line, col);
+    }
+    if (t->ndim != 1) {
+        RUNTIME_ERROR(interp, "APPEND target must be 1-D TNS", line, col);
+    }
+
+    size_t old_len = t->shape[0];
+    size_t new_len = old_len + 1;
+    size_t shape[1] = { new_len };
+    Value out = value_tns_new(t->elem_type, 1, shape);
+    Tensor* ot = out.as.tns;
+
+    // copy existing elements
+    for (size_t i = 0; i < old_len; i++) {
+        ot->data[i] = value_copy(t->data[i]);
+    }
+
+    // append the provided element (deep-copy containers to avoid shared mutation)
+    if (args[0].type == VAL_TNS || args[0].type == VAL_MAP) {
+        ot->data[new_len - 1] = value_deep_copy(args[0]);
+    } else {
+        ot->data[new_len - 1] = value_copy(args[0]);
+    }
+
+    if (!writeback_ptr_node(interp, arg_nodes ? arg_nodes[1] : NULL, env, out, "APPEND", line, col)) {
+        value_free(out);
+        return value_null();
+    }
+
+    return out;
+}
+
 // SCAT: return a copy of dst with a rectangular slice replaced by src.
 // Args: SCAT(TNS: src, TNS: dst, TNS: ind)
 static Value builtin_scat(Interpreter* interp, Value* args, int argc, Expr** arg_nodes, Env* env, int line, int col) {
@@ -8043,6 +8083,7 @@ static BuiltinFunction builtins_table[] = {
     {"TLEN", 2, 2, builtin_tlen},
     {"TFLIP", 2, 2, builtin_tflip},
     {"SCAT", 3, 3, builtin_scat},
+    {"APPEND", 2, 2, builtin_append},
     {"MADD", 2, 2, builtin_madd},
     {"MSUB", 2, 2, builtin_msub},
     {"MMUL", 2, 2, builtin_mmul},

tests/test2.pre

@@ -459,6 +459,24 @@ DEL(src_scat)
 DEL(ind_scat)
 PRINT("SCAT: PASS\n")
 
+! --- APPEND operator ---
+PRINT("Testing APPEND...")
+TNS: a_append = [0d1, 0d2]
+TNS: b_append = APPEND(0d3, a_append)
+ASSERT(EQ(b_append, [0d1, 0d2, 0d3]))
+DEL(a_append)
+DEL(b_append)
+
+TNS: t_append = [0d1, 0d2]
+APPEND(0d3, @t_append)
+ASSERT(EQ(t_append[0d3], 0d3))
+DEL(t_append)
+
+TNS: s_append = ["a", "b"]
+ASSERT(EQ(APPEND("c", s_append), ["a", "b", "c"]))
+DEL(s_append)
+PRINT("APPEND: PASS\n")
+
 ! --- Tensor-scalar arithmetic operators ---
 PRINT("Testing tensor-scalar arithmetic...")
 TNS: ta = [0b1, 0b10]