uCalc API Version: 2.1.3-preview.2 Released: 6/16/2026

Warning

uCalc API Preview Release Notice:The documentation describes the intended behavior of the API. The current preview build contains incomplete features, unoptimized performance, and is subject to breaking changes.

ReturnPtr

Method

Product: 

Fast Math Parser

Class: 

Callback

Returns a pointer value from a callback function.

Syntax

ReturnPtr(IntPtr)

Parameters

value
IntPtr
The pointer or handle to be returned from the callback.

Return

void

This method does not return a value.

Remarks

ReturnPtr is the specialized method within a uCalc.Callback for returning a raw memory address (a pointer or handle) from a native function back to the uCalc expression engine. This is the primary mechanism for interoperability when an expression needs to work with references to host-application objects or internal data structures rather than their values.

🎯 Core Use Case: Host Application Interop

While standard Return functions deal with values that uCalc understands (like numbers and strings), ReturnPtr is used when the value is an opaque handle meaningful only to the host application or other specialized uCalc functions. Common scenarios include:

  • Returning handles to files, database connections, or UI elements.
  • Passing pointers to complex C/C++ structs or C# objects that will be used by other callback functions.
  • Implementing custom memory allocators or object factories within uCalc.

The expression that receives the pointer can then pass this handle to other custom functions that know how to use it (e.g., ReadFile(handle)).

⚙️ Pointer Safety and Semantics

The uCalc engine treats the returned pointer as an opaque integer value. It does not attempt to dereference, validate, or manage the memory at that address. All responsibility for the pointer's validity and lifetime rests with the host application.

⚠️ Important: Do not return pointers to stack-allocated variables within your callback function. The memory will be invalid as soon as the callback returns, leading to undefined behavior.

🆚 Comparative Analysis

  • vs. Native C++/C# Pointers: In native code, returning a pointer is a direct operation. ReturnPtr acts as the necessary bridge to safely transport that native pointer across the boundary into the sandboxed uCalc environment. The value is not in "improving" on native pointers, but in enabling their use within uCalc expressions.

  • vs. Return() / ReturnStr(): The standard Return methods pass values that are copied into uCalc's memory management system. ReturnPtr passes a reference that remains outside of uCalc's control. Use standard Return for data, and ReturnPtr for handles or references.

Example Breakdown

The practical example demonstrates creating a custom version of the built-in AddressOf function.

  1. A function GetAddressOf is defined with a ByHandle parameter, allowing it to inspect the argument's metadata.
  2. The callback uses cb.ArgItem(1).ValueAddr() to get the internal memory address of the variable passed to it.
  3. cb.ReturnPtr(...) sends this address back to the evaluator.
  4. The ValueAt() function is then used in the expression to dereference the pointer and retrieve the original variable's value, proving the round trip was successful.

This showcases a complete cycle: passing a reference into a callback, getting its address, returning the address as a pointer, and using that pointer in another function.

Examples

Returning a pointer with ReturnPtr
				
					using uCalcSoftware;

var uc = new uCalc();

static void GetAddressOf(uCalc.Callback cb) {
   cb.ReturnPtr(cb.ArgItem(1).ValueAddr());
}


// This example is for sake of illustration
// There is already a built-in AddressOf() function

uc.DefineFunction("GetAddressOf(ByHandle Variable As AnyType) As SameTypeAs:0 Ptr", GetAddressOf);

uc.DefineVariable("MyVariable = 123.456");
uc.DefineVariable("MyStr = 'Hello world!'");

Console.WriteLine(uc.EvalStr("ValueAt(GetAddressOf(MyVariable))"));
Console.WriteLine(uc.EvalStr("ValueAt(GetAddressOf(MyStr))"));
				
			
123.456
Hello world!
				
					#include <iostream>
#include "uCalc.h"

using namespace std;
using namespace uCalcSoftware;

void ucalc_call GetAddressOf(uCalcBase::Callback cb) {
   cb.ReturnPtr(cb.ArgItem(1).ValueAddr());
}
int main() {
   uCalc uc;

   // This example is for sake of illustration
   // There is already a built-in AddressOf() function

   uc.DefineFunction("GetAddressOf(ByHandle Variable As AnyType) As SameTypeAs:0 Ptr", GetAddressOf);

   uc.DefineVariable("MyVariable = 123.456");
   uc.DefineVariable("MyStr = 'Hello world!'");

   cout << uc.EvalStr("ValueAt(GetAddressOf(MyVariable))") << endl;
   cout << uc.EvalStr("ValueAt(GetAddressOf(MyStr))") << endl;
}
				
			
123.456
Hello world!
				
					Imports System
Imports uCalcSoftware
Public Module Program
   
   Public Sub GetAddressOf(ByVal cb As uCalc.Callback)
      cb.ReturnPtr(cb.ArgItem(1).ValueAddr())
   End Sub
   Public Sub Main()
      Dim uc As New uCalc()
      
      '// This example is for sake of illustration
      '// There is already a built-in AddressOf() function
      
      uc.DefineFunction("GetAddressOf(ByHandle Variable As AnyType) As SameTypeAs:0 Ptr", AddressOf GetAddressOf)
      
      uc.DefineVariable("MyVariable = 123.456")
      uc.DefineVariable("MyStr = 'Hello world!'")
      
      Console.WriteLine(uc.EvalStr("ValueAt(GetAddressOf(MyVariable))"))
      Console.WriteLine(uc.EvalStr("ValueAt(GetAddressOf(MyStr))"))
   End Sub
End Module
				
			
123.456
Hello world!
Previous
Next