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.

Introduction

Product: 

Fast Math Parser

Class: 

Callback

An object passed to native callbacks, providing the interface to get arguments, set return values, and interact with the uCalc engine.

Remarks

🤝 The Callback Object: Bridging uCalc and Native Code

The uCalc.Callback class is the essential interface for communication between the uCalc engine and a native callback function in your host application (C#, C++, etc.). You do not create an instance of this class yourself; instead, a Callback object is automatically passed as the sole argument to any native function you register with DefineFunction or DefineOperator.

In all documentation examples, this object is referred to by the conventional name cb.

Its primary roles are:

  1. Getting Arguments: Retrieving the values passed from the expression to your native code.
  2. Setting Return Values: Sending a result from your native code back to the expression.
  3. Accessing Context: Interacting with the parent uCalc instance, introspecting the calling function, and handling errors.

📂 Argument Retrieval Methods

These methods are used to get the values passed to your function from the uCalc expression.

MemberDescription
ArgRetrieves a numeric argument as a double-precision float.
Arg1A high-performance shortcut for retrieving the first numeric argument.
Arg2A high-performance shortcut for retrieving the second numeric argument.
ArgAddrRetrieves a direct memory pointer to an argument's value, for low-level operations.
ArgBoolRetrieves a boolean argument, with automatic type conversion.
ArgCountGets the total number of arguments passed to the callback, essential for variadic functions.
ArgDblRetrieves a double-precision argument, functionally identical to Arg.
ArgExprRetrieves an argument as an unevaluated Expression object for lazy evaluation (ByExpr).
ArgInt16Retrieves a 16-bit integer argument.
ArgInt32Retrieves a 32-bit integer argument.
ArgInt64Retrieves a 64-bit integer argument.
ArgItemRetrieves the full metadata Item object for an argument, for introspection (ByHandle).
ArgPtrRetrieves the value of an argument that is a pointer.
ArgStrRetrieves an argument as a string, with automatic type conversion.

📤 Return Value Methods

These methods are used to send a result from your callback back to the uCalc engine.

MemberDescription
ReturnSets the double-precision return value for the callback.
ReturnBoolSets the boolean return value.
ReturnDblSets the double-precision return value, functionally identical to Return.
ReturnInt16Sets the 16-bit integer return value.
ReturnInt32Sets the 32-bit integer return value.
ReturnInt64Sets the 64-bit integer return value.
ReturnPtrSets a pointer as the return value.
ReturnStrSets the string return value.

⚙️ Context & Introspection

These properties provide access to the surrounding execution environment.

MemberDescription
uCalcRetrieves the parent uCalc instance that is executing the callback.
ItemRetrieves the Item object for the function or operator that triggered the callback.

💣 Error Handling

These members allow you to manage errors from within a callback.

MemberDescription
ErrorProvides access to the ErrorInfo object to raise errors or inspect error state.
RaiseTriggers a uCalc error with a predefined code or a custom message.

🔍 Low-Level & Diagnostics

MemberDescription
HandleRetrieves the internal, low-level identifier for the callback context object.

Examples

Defining a callback function with a variable number of arguments
				
					using uCalcSoftware;

var uc = new uCalc();

static void MyAverage(uCalc.Callback cb) {
   double Total = 0;
   for (int x = 1; x <= cb.ArgCount(); x++) {
      Total = Total + cb.Arg(x);
   }
   cb.Return(Total / cb.ArgCount());
}

uc.DefineFunction("Average(x ...)", MyAverage);
Console.WriteLine(uc.Eval("Average(10, 3, 7, 4)"));
				
			
6
				
					#include <iostream>
#include "uCalc.h"

using namespace std;
using namespace uCalcSoftware;

void ucalc_call MyAverage(uCalcBase::Callback cb) {
   double Total = 0;
   for (int x = 1; x <= cb.ArgCount(); x++) {
      Total = Total + cb.Arg(x);
   }
   cb.Return(Total / cb.ArgCount());
}
int main() {
   uCalc uc;
   uc.DefineFunction("Average(x ...)", MyAverage);
   cout << uc.Eval("Average(10, 3, 7, 4)") << endl;
}
				
			
6
				
					Imports System
Imports uCalcSoftware
Public Module Program
   
   Public Sub MyAverage(ByVal cb As uCalc.Callback)
      Dim Total As Double = 0
      For x  As Integer = 1 To cb.ArgCount()
         Total = Total + cb.Arg(x)
      Next
      cb.Return(Total / cb.ArgCount())
   End Sub
   Public Sub Main()
      Dim uc As New uCalc()
      uc.DefineFunction("Average(x ...)", AddressOf MyAverage)
      Console.WriteLine(uc.Eval("Average(10, 3, 7, 4)"))
   End Sub
End Module
				
			
6
Previous
Next