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.

ArgItem

Method

Product: 

Fast Math Parser

Class: 

Callback

Retrieves the full metadata object for a specific argument passed to a callback function.

Syntax

ArgItem(int)

Parameters

index
int
The 1-based index of the argument to retrieve (the first argument is at index 1).

Return

Item

Returns the Item object for the specified argument, providing access to its metadata such as name, data type, and underlying value pointer. Returns an empty item if the index is out of bounds.

Remarks

🔎 Introspection Power: Value vs. Metadata

The ArgItem method is the primary tool for introspection within a callback. While other Arg* functions (Arg(), ArgStr(), etc.) return the value of an argument, ArgItem returns the argument's underlying Item object. This gives you access to a wealth of metadata, allowing you to build highly dynamic and context-aware functions.

Arg() vs. ArgItem()

MethodReturnsUse Case
cb.Arg(1)double (the value)Simple numeric calculations.
cb.ArgStr(1)string (the value)Simple string manipulation.
cb.ArgItem(1)Item (the object)Accessing metadata: name, data type, original expression, value pointer.

🎯 Primary Use Cases

1. Handling ByHandle and ByRef Arguments

This is the most common use case. When a parameter is defined with ByHandle, its Item object is passed instead of its value. ArgItem is the only way to retrieve this object.

2. Variadic Functions (...)

For functions that accept a variable number of arguments, ArgItem allows you to loop through each argument and inspect its type and value, enabling you to create flexible functions like Sum() or Print().

3. Metaprogramming

By accessing an argument's metadata, you can change your function's behavior based on the caller's context. For example, you can check if an argument was a literal constant or a variable and process it differently.

⚖️ Comparative Analysis

  • vs. Reflection (C# ParameterInfo, Java Parameter):ArgItem provides functionality similar to reflection APIs in other languages but is more lightweight and integrated directly into the evaluation flow. Retrieving metadata is a simple method call, avoiding the complexity of navigating MethodInfo or Assembly objects.

  • vs. Dynamic Languages (Python *args, **kwargs):ArgItem brings the introspective power of dynamic languages into uCalc's strongly-typed (but flexible) environment. It provides a structured way to inspect arguments that is safer than simple type-checking in a fully dynamic context.

Examples

Passing arg ByHandle to retrieve meta data such as arg data type; and AnyType
				
					using uCalcSoftware;

var uc = new uCalc();

static void DisplayArgs(uCalc.Callback cb) {
   for (int x = 1; x <= cb.ArgCount(); x++) {
      Console.WriteLine(cb.ArgItem(x).ValueStr() + "  Type: " + cb.ArgItem(x).DataType.Name);
   }
}

uc.DefineFunction("DisplayArgs(ByHandle Arg As AnyType ...)", DisplayArgs);
uc.Eval("DisplayArgs(5, 3+2*#i, 'Hello', True, False, Int16(5+4.1))");
				
			
5  Type: double
3+2i  Type: complex
Hello  Type: string
true  Type: bool
false  Type: bool
9  Type: int16
				
					#include <iostream>
#include "uCalc.h"

using namespace std;
using namespace uCalcSoftware;

void ucalc_call DisplayArgs(uCalcBase::Callback cb) {
   for (int x = 1; x <= cb.ArgCount(); x++) {
      cout << cb.ArgItem(x).ValueStr() + "  Type: " + cb.ArgItem(x).DataType().Name() << endl;
   }
}
int main() {
   uCalc uc;
   uc.DefineFunction("DisplayArgs(ByHandle Arg As AnyType ...)", DisplayArgs);
   uc.Eval("DisplayArgs(5, 3+2*#i, 'Hello', True, False, Int16(5+4.1))");
}
				
			
5  Type: double
3+2i  Type: complex
Hello  Type: string
true  Type: bool
false  Type: bool
9  Type: int16
				
					Imports System
Imports uCalcSoftware
Public Module Program
   
   Public Sub DisplayArgs(ByVal cb As uCalc.Callback)
      For x  As Integer = 1 To cb.ArgCount()
         Console.WriteLine(cb.ArgItem(x).ValueStr() + "  Type: " + cb.ArgItem(x).DataType.Name)
      Next
   End Sub
   Public Sub Main()
      Dim uc As New uCalc()
      uc.DefineFunction("DisplayArgs(ByHandle Arg As AnyType ...)", AddressOf DisplayArgs)
      uc.Eval("DisplayArgs(5, 3+2*#i, 'Hello', True, False, Int16(5+4.1))")
   End Sub
End Module
				
			
5  Type: double
3+2i  Type: complex
Hello  Type: string
true  Type: bool
false  Type: bool
9  Type: int16
Passing arg ByExpr
				
					using uCalcSoftware;

var uc = new uCalc();

static void MySum(uCalc.Callback cb) {
   var Total = 0.0;
   var Expr = cb.ArgExpr(1);
   var Start = cb.Arg(2);
   var Finish = cb.Arg(3);
   var Variable = cb.ArgItem(4);

   for (double x = Start; x <= Finish; x++) {
      Variable.Value(x);
      Total += Expr.Evaluate();
   }
   cb.Return(Total);
}

uc.DefineVariable("x");
uc.DefineFunction("Sum(ByExpr Expr, Start, Finish, ByHandle Var)", MySum);
Console.WriteLine(uc.Eval("Sum(x ^ 2, 1, 10, x)"));

				
			
385
				
					#include <iostream>
#include "uCalc.h"

using namespace std;
using namespace uCalcSoftware;

void ucalc_call MySum(uCalcBase::Callback cb) {
   auto Total = 0.0;
   auto Expr = cb.ArgExpr(1);
   auto Start = cb.Arg(2);
   auto Finish = cb.Arg(3);
   auto Variable = cb.ArgItem(4);

   for (double x = Start; x <= Finish; x++) {
      Variable.Value(x);
      Total += Expr.Evaluate();
   }
   cb.Return(Total);
}
int main() {
   uCalc uc;
   uc.DefineVariable("x");
   uc.DefineFunction("Sum(ByExpr Expr, Start, Finish, ByHandle Var)", MySum);
   cout << uc.Eval("Sum(x ^ 2, 1, 10, x)") << endl;

}
				
			
385
				
					Imports System
Imports uCalcSoftware
Public Module Program
   
   Public Sub MySum(ByVal cb As uCalc.Callback)
      Dim Total = 0.0
      Dim Expr = cb.ArgExpr(1)
      Dim Start = cb.Arg(2)
      Dim Finish = cb.Arg(3)
      Dim Variable = cb.ArgItem(4)
      
      For x  As Double = Start To Finish
         Variable.Value(x)
         Total += Expr.Evaluate()
      Next
      cb.Return(Total)
   End Sub
   Public Sub Main()
      Dim uc As New uCalc()
      uc.DefineVariable("x")
      uc.DefineFunction("Sum(ByExpr Expr, Start, Finish, ByHandle Var)", AddressOf MySum)
      Console.WriteLine(uc.Eval("Sum(x ^ 2, 1, 10, x)"))
      
   End Sub
End Module
				
			
385
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