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.

NextOverload

Method

Product: 

Fast Math Parser

Class: 

Item

Retrieves the next item in a sequence of overloaded or shadowed symbols that share the same name.

Syntax

NextOverload()

Parameters

[None]

Return

Item

Returns the next Item object in the overload chain. If there are no more overloads, it returns an empty Item for which IsProperty(ItemIs::NotFound) is true.

Remarks

The NextOverload method provides a way to traverse the chain of items that share the same name within a uCalc instance. When multiple functions, operators, or even variables are defined with the same name, they form an implicit, stack-like list. This method acts as an iterator to walk through that list.

Core Concept: The Overload Chain

Think of symbols with the same name as a linked list:

  1. Head of the List: Calling ItemOf("MySymbol") retrieves the most recently defined item—the head of the chain.
  2. Walking the Chain: Calling NextOverload() on that item returns the previously defined item with the same name.
  3. End of the Chain: When no more items with that name exist, NextOverload() returns an empty Item object. You can check for this termination condition using item.NotEmpty() or item.IsProperty(ItemIs::NotFound) == false.

This mechanism is essential for introspection and managing complex symbol tables.

⚙️ Primary Use Cases

  • Inspecting Function/Operator Overloads: The most common use case is to programmatically discover all defined overloads for a function or operator, as shown in the practical example below.
  • Accessing Shadowed Variables: If you redefine a variable, the old definition is not destroyed but shadowed. NextOverload allows you to access the previous value or definition.
  • Resolving Transformer Rule Precedence: When multiple Transformer rules start with the same anchor text, the most recently defined rule takes precedence. They form an overload chain that you can inspect with this method.

Typical Loop Structure

A common pattern for iterating through all overloads is a while loop:

var item = uc.ItemOf("SymbolName");while (item.NotEmpty()) {   Console.WriteLine(item.Text()); // Process the current item   item = item.NextOverload(); // Move to the next one}

💡 Comparative Analysis

In compiled languages like C# or C++, function overloading is a compile-time concept. The compiler selects the correct method based on the arguments provided, and there is no built-in mechanism to programmatically iterate through all available overloads at runtime. This is a key differentiator for uCalc.

NextOverload gives uCalc powerful runtime introspection and metaprogramming capabilities. It allows your application to analyze its own defined symbol space, a feature more common in highly dynamic languages like LISP or Smalltalk, but made accessible here in a simple, procedural way.

Examples

Returning data type names for the different definitions of the "+" operator
				
					using uCalcSoftware;

var uc = new uCalc();
var PlusOperator = uc.ItemOf("+");

while (PlusOperator.NotEmpty()) {
   Console.WriteLine("Def: " + PlusOperator.Text + "  Type: " + PlusOperator.DataType.Name);
   PlusOperator = PlusOperator.NextOverload();
}
				
			
Def: Operator: 70 +{x}  Type: double
Def: Operator: 50 {x} + {y}  Type: double
Def: Operator: 50 {x As Int} + {y As Int} As Int  Type: int
Def: Operator: 50 {x As String} + {y As String} As String  Type: string
Def: Operator: 50 {x As Complex} + {y As Complex} As Complex  Type: complex
Def: Operator: 50 {ByHandle x As AnyType Ptr} + {y As Int} As SameTypeAs:0 Ptr  Type: sametypeas:ptr
Def: Operator: 50 {ByHandle x As AnyType} + {ByHandle y As String} As String  Type: string
Def: Operator: 50 {ByHandle x As String} + {ByHandle y As AnyType} As String  Type: string
				
					#include <iostream>
#include "uCalc.h"

using namespace std;
using namespace uCalcSoftware;

int main() {
   uCalc uc;
   auto PlusOperator = uc.ItemOf("+");

   while (PlusOperator.NotEmpty()) {
      cout << "Def: " + PlusOperator.Text() + "  Type: " + PlusOperator.DataType().Name() << endl;
      PlusOperator = PlusOperator.NextOverload();
   }
}
				
			
Def: Operator: 70 +{x}  Type: double
Def: Operator: 50 {x} + {y}  Type: double
Def: Operator: 50 {x As Int} + {y As Int} As Int  Type: int
Def: Operator: 50 {x As String} + {y As String} As String  Type: string
Def: Operator: 50 {x As Complex} + {y As Complex} As Complex  Type: complex
Def: Operator: 50 {ByHandle x As AnyType Ptr} + {y As Int} As SameTypeAs:0 Ptr  Type: sametypeas:ptr
Def: Operator: 50 {ByHandle x As AnyType} + {ByHandle y As String} As String  Type: string
Def: Operator: 50 {ByHandle x As String} + {ByHandle y As AnyType} As String  Type: string
				
					Imports System
Imports uCalcSoftware
Public Module Program
   Public Sub Main()
      Dim uc As New uCalc()
      Dim PlusOperator = uc.ItemOf("+")
      
      While PlusOperator.NotEmpty()
         Console.WriteLine("Def: " + PlusOperator.Text + "  Type: " + PlusOperator.DataType.Name)
         PlusOperator = PlusOperator.NextOverload()
      End While
   End Sub
End Module
				
			
Def: Operator: 70 +{x}  Type: double
Def: Operator: 50 {x} + {y}  Type: double
Def: Operator: 50 {x As Int} + {y As Int} As Int  Type: int
Def: Operator: 50 {x As String} + {y As String} As String  Type: string
Def: Operator: 50 {x As Complex} + {y As Complex} As Complex  Type: complex
Def: Operator: 50 {ByHandle x As AnyType Ptr} + {y As Int} As SameTypeAs:0 Ptr  Type: sametypeas:ptr
Def: Operator: 50 {ByHandle x As AnyType} + {ByHandle y As String} As String  Type: string
Def: Operator: 50 {ByHandle x As String} + {ByHandle y As AnyType} As String  Type: string
Previous
Next