neuronapi: return nullptr from nrn_symbol_dataptr for non-scalar symbols (#3821)

Follow-up to #3815. nrn_symbol_dataptr returned sym->u.pval for any
symbol that was not a NOTUSER scalar, so asking for the dataptr of a
symbol with no double storage -- a function such as finitialize, a
top-level objref or strdef, or a section-level property (nseg/L/Ra/
rallbranch) -- handed back a reinterpreted union member (an Object*,
char*, function pointer, or a {type, index} pair) that dereferences to
garbage.

Return nullptr for those instead. The function now yields a real double*
only for a scalar/array VAR (USERDOUBLE, the typed USERINT/USERFLOAT that
alias sym->u.pval, and NOTUSER whose storage lives in the top-level
object-data array) and nullptr for everything else.

Extends test/api/global_scalar.cpp with the nullptr cases (null symbol,
finitialize, a top-level objref and strdef, and L) and updates the
capi.rst return doc to state the failure behavior.

Author: ec1dev

docs/capi.rst

@@ -742,8 +742,10 @@ Functions, objects, and the stack
     in the top-level object-data array rather than at ``sym->u.pval``.
 
     :param sym: Pointer to the symbol.
-    :returns: Pointer to the symbol's data, or the raw ``sym->u.pval`` for
-              symbols that are not top-level runtime scalars.
+    :returns: A pointer to the variable's storage, or ``NULL`` if ``sym`` is not
+              a scalar variable with a data pointer (a null symbol, a function,
+              an object, a string, or a section-level property such as ``L`` or
+              ``nseg``).
 
     **Usage Pattern:**
 

src/nrniv/neuronapi.cpp

@@ -258,19 +258,32 @@ int nrn_symbol_subtype(const Symbol* sym) {
 }
 
 double* nrn_symbol_dataptr(const Symbol* sym) {
-    // A NOTUSER runtime scalar (created in HOC by e.g. `x = 42`) does not store
-    // its value at sym->u.pval -- for that subtype the union member holds an
-    // object-data offset, not a pointer, so returning it hands back garbage that
-    // segfaults on dereference. The real storage is in the top-level
-    // object-data array (see the NOTUSER branch of eval() in oc/code.cpp, which
-    // reads *OPVAL(sym) == *hoc_top_level_data[sym->u.oboff].pval). Return that
-    // address so the result is a dereferenceable double*, as the name promises.
-    // Every other case (USERDOUBLE built-ins such as `t`, and the typed USER*
-    // subtypes that already alias sym->u.pval) is unchanged.
-    if (sym && sym->type == VAR && sym->subtype == NOTUSER) {
+    // Only a scalar/array VAR has a real double* to hand back. Anything else --
+    // a function (e.g. finitialize), an object, a string, a template (all with
+    // type != VAR), or a section-level property (USERPROPERTY: nseg/L/Ra/
+    // rallbranch, whose u member is a {membrane type, index} pair, not a
+    // pointer) -- has no dataptr, so return nullptr instead of a reinterpreted
+    // union member that the caller would dereference as garbage.
+    if (!sym || sym->type != VAR) {
+        return nullptr;
+    }
+    switch (sym->subtype) {
+    case NOTUSER:
+        // A NOTUSER runtime scalar (created in HOC by e.g. `x = 42`) does not
+        // store its value at sym->u.pval -- for that subtype the union member
+        // holds an object-data offset, not a pointer. The real storage is in
+        // the top-level object-data array (see the NOTUSER branch of eval() in
+        // oc/code.cpp, which reads *OPVAL(sym) ==
+        // *hoc_top_level_data[sym->u.oboff].pval). Return that address so the
+        // result is a dereferenceable double*, as the name promises.
         return hoc_top_level_data[sym->u.oboff].pval;
+    case USERPROPERTY:
+        return nullptr;
+    default:
+        // USERDOUBLE built-ins such as `t`, plus the typed USERINT/USERFLOAT
+        // scalars whose storage aliases sym->u.pval (callers cast as needed).
+        return sym->u.pval;
     }
-    return sym->u.pval;
 }
 
 bool nrn_symbol_is_array(const Symbol* sym) {

test/api/global_scalar.cpp

@@ -54,5 +54,31 @@ int main(void) {
     nrn_hoc_call("hoc_ac_ = t");
     ok &= eq(*ac, 12.0, "USERDOUBLE dataptr round-trips through HOC");
 
+    // Symbols with no data pointer must return nullptr, not a reinterpreted
+    // union member the caller would dereference as garbage.
+    ok &= check(nrn_symbol_dataptr(nullptr) == nullptr, "null symbol -> nullptr");
+
+    // A function symbol (finitialize) is non-null but has no dataptr.
+    Symbol* fi = nrn_symbol("finitialize");
+    ok &= check(fi != nullptr, "finitialize symbol exists");
+    ok &= check(nrn_symbol_dataptr(fi) == nullptr, "function symbol -> nullptr");
+
+    // Top-level object and string variables are not double storage.
+    nrn_hoc_call("objref myobj");
+    Symbol* obj = nrn_symbol("myobj");
+    ok &= check(obj != nullptr, "objref symbol exists");
+    ok &= check(nrn_symbol_dataptr(obj) == nullptr, "objref -> nullptr");
+
+    nrn_hoc_call("strdef mystr");
+    Symbol* str = nrn_symbol("mystr");
+    ok &= check(str != nullptr, "strdef symbol exists");
+    ok &= check(nrn_symbol_dataptr(str) == nullptr, "strdef -> nullptr");
+
+    // A section-level property (USERPROPERTY: L, nseg, ...) has no global
+    // storage pointer.
+    Symbol* len = nrn_symbol("L");
+    ok &= check(len != nullptr, "L symbol exists");
+    ok &= check(nrn_symbol_dataptr(len) == nullptr, "section-level property -> nullptr");
+
     return ok ? 0 : 1;
 }