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:

csharp
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.