neuronapi: add top-level objref/strdef get and set accessors (#3830)

* neuronapi: add top-level objref/strdef get and set accessors

Adds nrn_symbol_object_get/set and nrn_symbol_str_get/set. A top-level
objref or strdef stores its Object*/char* in the top-level object-data
array (hoc_top_level_data[sym->u.oboff].pobj/.ppstr), not at sym->u.pval,
so nrn_symbol_dataptr cannot return it. These read and write that storage:
object_set follows HOC's assignment refcounting (unref old, ref new; NULL
clears), and str_set copies via hoc_assign_str. Non-matching symbol types
return NULL / nonzero rather than crashing.

Author: ec1dev

docs/capi.rst

@@ -752,6 +752,57 @@ Functions, objects, and the stack
     Provides direct access to variable data for efficient reading/writing.
     e.g., use this for getting/setting the value of ``t`` (time).
 
+.. c:function:: Object* nrn_symbol_object_get(const Symbol* sym)
+
+    Get the object bound to a top-level ``objref``.
+
+    :param sym: Symbol for a top-level ``objref``.
+    :returns: The bound object, or ``NULL`` if the objref is nil or ``sym`` is
+        not an objref.
+
+    The object is returned *borrowed* -- its reference count is not
+    incremented. Call :c:func:`nrn_object_ref` to retain it beyond the next
+    assignment to the objref. Complements :c:func:`nrn_symbol_dataptr`, which
+    returns ``NULL`` for an objref because it is not a ``double*``.
+
+.. c:function:: bool nrn_symbol_object_set(Symbol* sym, Object* obj)
+
+    Bind an object to a top-level ``objref``.
+
+    :param sym: Symbol for a top-level ``objref``.
+    :param obj: The object to bind, or ``NULL`` to make the objref nil.
+    :returns: ``true`` on success, ``false`` if ``sym`` is not an objref.
+
+    Follows HOC's assignment reference-counting: the previously bound object is
+    released and the new one retained.
+
+.. c:function:: const char* nrn_symbol_str_get(const Symbol* sym)
+
+    Get the string held by a top-level ``strdef``.
+
+    :param sym: Symbol for a top-level ``strdef``.
+    :returns: The string, or ``NULL`` if ``sym`` is not a strdef.
+
+.. c:function:: bool nrn_symbol_str_set(Symbol* sym, const char* value)
+
+    Set the string held by a top-level ``strdef``.
+
+    :param sym: Symbol for a top-level ``strdef``.
+    :param value: The string to copy in.
+    :returns: ``true`` on success, ``false`` if ``sym`` is not a strdef.
+
+    The value is copied into the strdef's storage (the previous string is
+    freed).
+
+    **Python Equivalent:**
+
+    .. code-block:: python
+
+        n.s = "cell"     # nrn_symbol_str_set
+        name = n.s       # nrn_symbol_str_get
+        n.obj = vec      # nrn_symbol_object_set
+        bound = n.obj    # nrn_symbol_object_get
+
 .. c:function:: bool nrn_symbol_is_array(const Symbol* sym)
 
     Check if a symbol represents an array.

src/nrniv/neuronapi.cpp

@@ -286,6 +286,53 @@ double* nrn_symbol_dataptr(const Symbol* sym) {
     }
 }
 
+Object* nrn_symbol_object_get(const Symbol* sym) {
+    // A top-level objref (`objref o`) stores its Object* in the top-level
+    // object-data array, not at sym->u.pval. Returns the bound object, or NULL
+    // if the objref is nil or `sym` is not an objref. The object is returned
+    // borrowed (its reference count is not incremented); call nrn_object_ref to
+    // retain it past the next assignment to this objref.
+    if (!sym || sym->type != OBJECTVAR) {
+        return nullptr;
+    }
+    return hoc_top_level_data[sym->u.oboff].pobj[0];
+}
+
+bool nrn_symbol_object_set(Symbol* sym, Object* obj) {
+    // Bind `obj` to a top-level objref, following HOC's assignment refcount
+    // rules: release the previously bound object and retain the new one. A NULL
+    // obj clears the objref (makes it nil). Returns true on success, false if
+    // `sym` is not an objref.
+    if (!sym || sym->type != OBJECTVAR) {
+        return false;
+    }
+    Object** cell = hoc_top_level_data[sym->u.oboff].pobj;
+    hoc_dec_refcount(cell);  // unref the old content and NULL the cell
+    *cell = obj;
+    hoc_obj_ref(obj);  // NULL-safe
+    return true;
+}
+
+const char* nrn_symbol_str_get(const Symbol* sym) {
+    // A top-level strdef (`strdef s`) stores its char* in the top-level
+    // object-data array. Returns the string, or NULL if `sym` is not a strdef.
+    if (!sym || sym->type != STRING) {
+        return nullptr;
+    }
+    return hoc_top_level_data[sym->u.oboff].ppstr[0];
+}
+
+bool nrn_symbol_str_set(Symbol* sym, const char* value) {
+    // Copy `value` into a top-level strdef's storage (freeing the previous
+    // string), via the same helper HOC string assignment uses. Returns true on
+    // success, false if `sym` is not a strdef.
+    if (!sym || sym->type != STRING) {
+        return false;
+    }
+    hoc_assign_str(hoc_top_level_data[sym->u.oboff].ppstr, value);
+    return true;
+}
+
 bool nrn_symbol_is_array(const Symbol* sym) {
     return sym->arayinfo != nullptr;
 }

src/nrniv/neuronapi.h

@@ -81,6 +81,10 @@ void nrn_symbol_push(Symbol* sym);
 int nrn_symbol_type(const Symbol* sym);
 int nrn_symbol_subtype(const Symbol* sym);
 double* nrn_symbol_dataptr(const Symbol* sym);
+Object* nrn_symbol_object_get(const Symbol* sym);
+bool nrn_symbol_object_set(Symbol* sym, Object* obj);
+const char* nrn_symbol_str_get(const Symbol* sym);
+bool nrn_symbol_str_set(Symbol* sym, const char* value);
 bool nrn_symbol_is_array(const Symbol* sym);
 void nrn_double_push(double val);
 double nrn_double_pop(void);

test/api/CMakeLists.txt

@@ -8,6 +8,7 @@ foreach(
   object_new_wrap.cpp
   segment_diam.cpp
   sections.cpp
+  symbol_object_string.cpp
   vclamp.cpp)
   string(REPLACE "." "_" api_test_name "${api_test_file}")
   add_executable(${api_test_name} ${api_test_file})

test/api/symbol_object_string.cpp

@@ -0,0 +1,76 @@
+// NOTE: this assumes neuronapi.h is on your CPLUS_INCLUDE_PATH
+// Exercises the top-level objref and strdef accessors: nrn_symbol_object_get/set
+// and nrn_symbol_str_get/set. These read and write the Object* / char* that a
+// top-level `objref`/`strdef` stores in the top-level object-data array, which
+// nrn_symbol_dataptr cannot return (it is not a double*).
+#include <array>
+#include <cstring>
+#include <iostream>
+#include "neuronapi.h"
+
+using std::cerr;
+using std::endl;
+
+extern "C" void modl_reg(){/* No modl_reg */};
+
+static bool check(bool cond, const char* msg) {
+    if (!cond) {
+        cerr << "FAIL: " << msg << endl;
+    }
+    return cond;
+}
+
+int main(void) {
+    static std::array<const char*, 4> argv = {"symbol_object_string",
+                                              "-nogui",
+                                              "-nopython",
+                                              nullptr};
+    nrn_init(3, argv.data());
+
+    bool ok = true;
+
+    // --- strdef get/set ---
+    nrn_hoc_call("strdef s");
+    nrn_hoc_call("s = \"hello\"");
+    Symbol* s = nrn_symbol("s");
+    ok &= check(s != nullptr, "strdef symbol resolves");
+    const char* sval = nrn_symbol_str_get(s);
+    ok &= check(sval != nullptr && std::strcmp(sval, "hello") == 0,
+                "str_get reads the strdef value");
+
+    ok &= check(nrn_symbol_str_set(s, "world") == true, "str_set succeeds on a strdef");
+    ok &= check(std::strcmp(nrn_symbol_str_get(s), "world") == 0, "str_set updated the value");
+    // Confirm HOC sees the written value too (aliases the same storage).
+    nrn_hoc_call("hoc_ac_ = strcmp(s, \"world\")");
+    ok &= check(*nrn_symbol_dataptr(nrn_symbol("hoc_ac_")) == 0.0, "HOC reads the str_set value");
+
+    // --- objref get/set ---
+    nrn_hoc_call("objref o");
+    nrn_hoc_call("o = new Vector(3)");
+    Symbol* o = nrn_symbol("o");
+    ok &= check(o != nullptr, "objref symbol resolves");
+    Object* vec = nrn_symbol_object_get(o);
+    ok &= check(vec != nullptr, "object_get reads the bound object");
+    ok &= check(nrn_vector_capacity(vec) == 3, "the bound object is the Vector(3)");
+
+    // Rebind the objref to a different Vector via object_set.
+    Object* vec5 = nrn_object_new(nrn_symbol("Vector"), 0);  // empty Vector
+    nrn_object_ref(vec5);
+    ok &= check(nrn_symbol_object_set(o, vec5) == true, "object_set succeeds on an objref");
+    ok &= check(nrn_symbol_object_get(o) == vec5, "object_set rebound the objref");
+    // HOC sees the new binding.
+    nrn_hoc_call("hoc_ac_ = o.size()");
+    ok &= check(*nrn_symbol_dataptr(nrn_symbol("hoc_ac_")) == 0.0, "HOC sees the rebound object");
+
+    // Clearing to nil.
+    ok &= check(nrn_symbol_object_set(o, nullptr) == true, "object_set(NULL) clears the objref");
+    ok &= check(nrn_symbol_object_get(o) == nullptr, "objref is nil after clear");
+
+    // --- type mismatches return NULL / false, not a crash ---
+    ok &= check(nrn_symbol_object_get(s) == nullptr, "object_get on a strdef returns NULL");
+    ok &= check(nrn_symbol_str_get(o) == nullptr, "str_get on an objref returns NULL");
+    ok &= check(nrn_symbol_object_set(s, vec5) == false, "object_set on a strdef is rejected");
+    ok &= check(nrn_symbol_str_set(o, "x") == false, "str_set on an objref is rejected");
+
+    return ok ? 0 : 1;
+}