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.

ByType

Method

Product: 

Transformer Library

Class: 

Tokens

Retrieves a token definition from the collection by its lexical category (TokenType) and optional index.

Syntax

ByType(TokenType, int)

Parameters

tokenType
TokenType
The lexical category to filter by, specified as a member of the [TokenType](/Reference/Enums/TokenType) enum.
nth
int
(Default = 0)
The zero-based index of the token to retrieve from the filtered list of matching types. Defaults to 0, which returns the first match.

Return

Item

An Item object representing the token. If no token is found at the specified index for the given type, an empty item is returned (for which IsEmpty() is true).

Remarks

The ByType method provides a way to query and retrieve token definitions based on their functional category, such as Literal, Whitespace, or Bracket. It is a key tool for introspecting and dynamically modifying the lexical rules of a Transformer or the main expression parser.

⚙️ How It Works

This method filters the entire token collection to find all tokens that match the specified tokenType. Since multiple tokens can belong to the same category (e.g., there are several built-in Literal tokens for different string and number formats), the optional nth parameter allows you to select a specific one from the filtered list.

The index nth is zero-based and applies only to the subset of tokens matching the type.

🎯 Primary Use Cases

  1. Introspection: Programmatically find all tokens of a certain type to inspect their regex patterns or other properties. This is useful for building debuggers or documentation tools.
  2. Dynamic Parser Modification: Retrieve a specific token to modify its behavior. For example, you might retrieve all Whitespace tokens to change their regex patterns.
  3. Language-Agnostic Logic: Write code that can find "the alphanumeric token" without needing to know its specific internal name (_token_alphanumeric).

🆚 Comparative Analysis: Why uCalc?

In a traditional parsing setup using tools like ANTLR or Flex/Bison, the token list is static and compiled. To find all tokens of a certain "type," you would need to manually inspect the generated source code or grammar files.

uCalc's token system is a dynamic, queryable collection. ByType provides a high-level, programmatic way to filter this collection that is analogous to using LINQ in C# or list comprehensions in Python to filter objects based on a property.

C# LINQ Analogy:

// The uCalc way is more direct and built-invar literalTokens = myTokens.Where(t => t.TypeOfToken == TokenType.Literal).ToList();

By providing a direct API for this common task, uCalc simplifies the process of building adaptable and introspective parsers.

For retrieving a token by its unique name, use the ByName method. For direct index-based access, use At.

Examples

Succinct: Retrieves the primary alphanumeric token definition using `ByType`.
				
					using uCalcSoftware;

var uc = new uCalc();
var tokens = uc.ExpressionTokens;
var alphaToken = tokens.ByType(TokenType.AlphaNumeric);

Console.WriteLine($"Name: {alphaToken.Name}");
Console.WriteLine($"Regex: {alphaToken.Regex}");
				
			
Name: _token_alphanumeric
Regex: [a-zA-Z_][a-zA-Z0-9_]*
				
					#include <iostream>
#include "uCalc.h"

using namespace std;
using namespace uCalcSoftware;

int main() {
   uCalc uc;
   auto tokens = uc.ExpressionTokens();
   auto alphaToken = tokens.ByType(TokenType::AlphaNumeric);

   cout << "Name: " << alphaToken.Name() << endl;
   cout << "Regex: " << alphaToken.Regex() << endl;
}
				
			
Name: _token_alphanumeric
Regex: [a-zA-Z_][a-zA-Z0-9_]*
				
					Imports System
Imports uCalcSoftware
Public Module Program
   Public Sub Main()
      Dim uc As New uCalc()
      Dim tokens = uc.ExpressionTokens
      Dim alphaToken = tokens.ByType(TokenType.AlphaNumeric)
      
      Console.WriteLine($"Name: {alphaToken.Name}")
      Console.WriteLine($"Regex: {alphaToken.Regex}")
   End Sub
End Module
				
			
Name: _token_alphanumeric
Regex: [a-zA-Z_][a-zA-Z0-9_]*
Practical: Iterates through all tokens categorized as 'Literal' to display their definitions.
				
					using uCalcSoftware;

var uc = new uCalc();
var tokens = uc.ExpressionTokens;
int i = 0;
var literalToken = new uCalc.Item();

Console.WriteLine("--- All Literal Tokens ---");
do {
   literalToken = tokens.ByType(TokenType.Literal, i);
   if (literalToken.NotEmpty()) {
      Console.WriteLine($"{i}: {literalToken.Name} - {literalToken.Regex}");
   }
   i = i + 1;
} while (literalToken.NotEmpty());
				
			
--- All Literal Tokens ---
0: _token_string_singlequoted - '([^']*(?:''[^']*)*)'
1: _token_string_doublequoted - "([^"]*(?:""[^"]*)*)"
2: _token_string_tripledoublequoted - """([\s\S]*?)"""
3: _token_floatnumber - [0-9]*\.?[0-9]+([eE][+-]?[0-9]+)?
4: _token_imaginaryunit - #i
				
					#include <iostream>
#include "uCalc.h"

using namespace std;
using namespace uCalcSoftware;

int main() {
   uCalc uc;
   auto tokens = uc.ExpressionTokens();
   int i = 0;
   uCalc::Item literalToken;

   cout << "--- All Literal Tokens ---" << endl;
   do {
      literalToken = tokens.ByType(TokenType::Literal, i);
      if (literalToken.NotEmpty()) {
         cout << i << ": " << literalToken.Name() << " - " << literalToken.Regex() << endl;
      }
      i = i + 1;
   } while (literalToken.NotEmpty());
}
				
			
--- All Literal Tokens ---
0: _token_string_singlequoted - '([^']*(?:''[^']*)*)'
1: _token_string_doublequoted - "([^"]*(?:""[^"]*)*)"
2: _token_string_tripledoublequoted - """([\s\S]*?)"""
3: _token_floatnumber - [0-9]*\.?[0-9]+([eE][+-]?[0-9]+)?
4: _token_imaginaryunit - #i
				
					Imports System
Imports uCalcSoftware
Public Module Program
   Public Sub Main()
      Dim uc As New uCalc()
      Dim tokens = uc.ExpressionTokens
      Dim i As Integer = 0
      Dim literalToken As New uCalc.Item()
      
      Console.WriteLine("--- All Literal Tokens ---")
      Do
         literalToken = tokens.ByType(TokenType.Literal, i)
         If literalToken.NotEmpty() Then
            Console.WriteLine($"{i}: {literalToken.Name} - {literalToken.Regex}")
         End If
         i = i + 1
      Loop While literalToken.NotEmpty()
   End Sub
End Module
				
			
--- All Literal Tokens ---
0: _token_string_singlequoted - '([^']*(?:''[^']*)*)'
1: _token_string_doublequoted - "([^"]*(?:""[^"]*)*)"
2: _token_string_tripledoublequoted - """([\s\S]*?)"""
3: _token_floatnumber - [0-9]*\.?[0-9]+([eE][+-]?[0-9]+)?
4: _token_imaginaryunit - #i
Internal Test: Verifies that requesting an out-of-bounds index for a token type returns an empty item.
				
					using uCalcSoftware;

var uc = new uCalc();
var tokens = uc.ExpressionTokens;

// There is only one Alphanumeric token, so index 1 is out of bounds.
var outOfBoundsToken = tokens.ByType(TokenType.AlphaNumeric, 1);

Console.WriteLine($"Is token empty? {outOfBoundsToken.IsEmpty()}");
Console.WriteLine($"Was token found? {! outOfBoundsToken.IsProperty(ItemIs.NotFound)}");
				
			
Is token empty? True
Was token found? False
				
					#include <iostream>
#include "uCalc.h"

using namespace std;
using namespace uCalcSoftware;

#define tf(IsTrue) ((IsTrue) ? "True" : "False")

int main() {
   uCalc uc;
   auto tokens = uc.ExpressionTokens();

   // There is only one Alphanumeric token, so index 1 is out of bounds.
   auto outOfBoundsToken = tokens.ByType(TokenType::AlphaNumeric, 1);

   cout << "Is token empty? " << tf(outOfBoundsToken.IsEmpty()) << endl;
   cout << "Was token found? " << tf(not outOfBoundsToken.IsProperty(ItemIs::NotFound)) << endl;
}
				
			
Is token empty? True
Was token found? False
				
					Imports System
Imports uCalcSoftware
Public Module Program
   Public Sub Main()
      Dim uc As New uCalc()
      Dim tokens = uc.ExpressionTokens
      
      '// There is only one Alphanumeric token, so index 1 is out of bounds.
      Dim outOfBoundsToken = tokens.ByType(TokenType.AlphaNumeric, 1)
      
      Console.WriteLine($"Is token empty? {outOfBoundsToken.IsEmpty()}")
      Console.WriteLine($"Was token found? {not outOfBoundsToken.IsProperty(ItemIs.NotFound)}")
   End Sub
End Module
				
			
Is token empty? True
Was token found? False
Token(TokenType)
				
					using uCalcSoftware;

var uc = new uCalc();
Console.WriteLine(uc.ExpressionTokens[TokenType.AlphaNumeric].Name);
Console.WriteLine(uc.ExpressionTokens[TokenType.AlphaNumeric].Regex);
Console.WriteLine("");

// Note: In C# or VB you can simply use [TokenType::Literal, n]
// instead of ByType(TokenType::Literal, n)
Console.WriteLine(uc.ExpressionTokens.ByType(TokenType.Literal, 0).Name);
Console.WriteLine(uc.ExpressionTokens.ByType(TokenType.Literal, 1).Name);
Console.WriteLine(uc.ExpressionTokens.ByType(TokenType.Literal, 2).Name);
				
			
_token_alphanumeric
[a-zA-Z_][a-zA-Z0-9_]*

_token_string_singlequoted
_token_string_doublequoted
_token_string_tripledoublequoted
				
					#include <iostream>
#include "uCalc.h"

using namespace std;
using namespace uCalcSoftware;

int main() {
   uCalc uc;
   cout << uc.ExpressionTokens()[TokenType::AlphaNumeric].Name() << endl;
   cout << uc.ExpressionTokens()[TokenType::AlphaNumeric].Regex() << endl;
   cout << "" << endl;

   // Note: In C# or VB you can simply use [TokenType::Literal, n]
   // instead of ByType(TokenType::Literal, n)
   cout << uc.ExpressionTokens().ByType(TokenType::Literal, 0).Name() << endl;
   cout << uc.ExpressionTokens().ByType(TokenType::Literal, 1).Name() << endl;
   cout << uc.ExpressionTokens().ByType(TokenType::Literal, 2).Name() << endl;
}
				
			
_token_alphanumeric
[a-zA-Z_][a-zA-Z0-9_]*

_token_string_singlequoted
_token_string_doublequoted
_token_string_tripledoublequoted
				
					Imports System
Imports uCalcSoftware
Public Module Program
   Public Sub Main()
      Dim uc As New uCalc()
      Console.WriteLine(uc.ExpressionTokens(TokenType.AlphaNumeric).Name)
      Console.WriteLine(uc.ExpressionTokens(TokenType.AlphaNumeric).Regex)
      Console.WriteLine("")
      
      '// Note: In C# or VB you can simply use [TokenType::Literal, n]
      '// instead of ByType(TokenType::Literal, n)
      Console.WriteLine(uc.ExpressionTokens.ByType(TokenType.Literal, 0).Name)
      Console.WriteLine(uc.ExpressionTokens.ByType(TokenType.Literal, 1).Name)
      Console.WriteLine(uc.ExpressionTokens.ByType(TokenType.Literal, 2).Name)
   End Sub
End Module
				
			
_token_alphanumeric
[a-zA-Z_][a-zA-Z0-9_]*

_token_string_singlequoted
_token_string_doublequoted
_token_string_tripledoublequoted
Change characters accepted as alphanumeric in expressions using ExpressionTokens() & Token()
				
					using uCalcSoftware;

var uc = new uCalc();
// (See alternate version of this example using ItemOf instead of ExpressionTokens)

// In this section underscore, _, and numeric digits
// are accepted as part of alphanumeric tokens
uc.DefineVariable("My_Variable = 111");
Console.WriteLine(uc.Error.Message);
uc.DefineVariable("Variable123 = 222");
Console.WriteLine(uc.Error.Message);

Console.WriteLine(uc.ExpressionTokens[TokenType.AlphaNumeric].Regex);
Console.WriteLine(uc.EvalStr("My_Variable"));
Console.WriteLine(uc.EvalStr("Variable123"));
Console.WriteLine("---");

// Now we no longer want underscore, _, or numeric digits
// to be accepted in alphanumeric tokens; only A-Z
uc.ExpressionTokens[TokenType.AlphaNumeric].Regex = "[a-zA-Z]+";

uc.DefineVariable("Other_Variable = 333");
Console.WriteLine(uc.Error.Message);
uc.DefineVariable("OtherVariable123 = 444");
Console.WriteLine(uc.Error.Message);

Console.WriteLine(uc.EvalStr("Other_Variable"));
Console.WriteLine(uc.EvalStr("OtherVariable123 "));
Console.WriteLine(uc.EvalStr("My_Variable"));
Console.WriteLine(uc.EvalStr("Variable123"));
Console.WriteLine("---");

// We restore the alphanumeric regex to support _ and numbers again
// Note: My_Variable and Variable123 remained; they were simply inaccessible
uc.ExpressionTokens[TokenType.AlphaNumeric].Regex = "[a-zA-Z_][a-zA-Z0-9_]*";
Console.WriteLine(uc.EvalStr("My_Variable"));
Console.WriteLine(uc.EvalStr("Variable123"));
				
			
No error
No error
[a-zA-Z_][a-zA-Z0-9_]*
111
222
---
Invalid definition
Invalid definition
Undefined identifier
Undefined identifier
Undefined identifier
Undefined identifier
---
111
222
				
					#include <iostream>
#include "uCalc.h"

using namespace std;
using namespace uCalcSoftware;

int main() {
   uCalc uc;
   // (See alternate version of this example using ItemOf instead of ExpressionTokens)

   // In this section underscore, _, and numeric digits
   // are accepted as part of alphanumeric tokens
   uc.DefineVariable("My_Variable = 111");
   cout << uc.Error().Message() << endl;
   uc.DefineVariable("Variable123 = 222");
   cout << uc.Error().Message() << endl;

   cout << uc.ExpressionTokens()[TokenType::AlphaNumeric].Regex() << endl;
   cout << uc.EvalStr("My_Variable") << endl;
   cout << uc.EvalStr("Variable123") << endl;
   cout << "---" << endl;

   // Now we no longer want underscore, _, or numeric digits
   // to be accepted in alphanumeric tokens; only A-Z
   uc.ExpressionTokens()[TokenType::AlphaNumeric].Regex("[a-zA-Z]+");

   uc.DefineVariable("Other_Variable = 333");
   cout << uc.Error().Message() << endl;
   uc.DefineVariable("OtherVariable123 = 444");
   cout << uc.Error().Message() << endl;

   cout << uc.EvalStr("Other_Variable") << endl;
   cout << uc.EvalStr("OtherVariable123 ") << endl;
   cout << uc.EvalStr("My_Variable") << endl;
   cout << uc.EvalStr("Variable123") << endl;
   cout << "---" << endl;

   // We restore the alphanumeric regex to support _ and numbers again
   // Note: My_Variable and Variable123 remained; they were simply inaccessible
   uc.ExpressionTokens()[TokenType::AlphaNumeric].Regex("[a-zA-Z_][a-zA-Z0-9_]*");
   cout << uc.EvalStr("My_Variable") << endl;
   cout << uc.EvalStr("Variable123") << endl;
}
				
			
No error
No error
[a-zA-Z_][a-zA-Z0-9_]*
111
222
---
Invalid definition
Invalid definition
Undefined identifier
Undefined identifier
Undefined identifier
Undefined identifier
---
111
222
				
					Imports System
Imports uCalcSoftware
Public Module Program
   Public Sub Main()
      Dim uc As New uCalc()
      '// (See alternate version of this example using ItemOf instead of ExpressionTokens)
      
      '// In this section underscore, _, and numeric digits
      '// are accepted as part of alphanumeric tokens
      uc.DefineVariable("My_Variable = 111")
      Console.WriteLine(uc.Error.Message)
      uc.DefineVariable("Variable123 = 222")
      Console.WriteLine(uc.Error.Message)
      
      Console.WriteLine(uc.ExpressionTokens(TokenType.AlphaNumeric).Regex)
      Console.WriteLine(uc.EvalStr("My_Variable"))
      Console.WriteLine(uc.EvalStr("Variable123"))
      Console.WriteLine("---")
      
      '// Now we no longer want underscore, _, or numeric digits
      '// to be accepted in alphanumeric tokens; only A-Z
      uc.ExpressionTokens(TokenType.AlphaNumeric).Regex = "[a-zA-Z]+"
      
      uc.DefineVariable("Other_Variable = 333")
      Console.WriteLine(uc.Error.Message)
      uc.DefineVariable("OtherVariable123 = 444")
      Console.WriteLine(uc.Error.Message)
      
      Console.WriteLine(uc.EvalStr("Other_Variable"))
      Console.WriteLine(uc.EvalStr("OtherVariable123 "))
      Console.WriteLine(uc.EvalStr("My_Variable"))
      Console.WriteLine(uc.EvalStr("Variable123"))
      Console.WriteLine("---")
      
      '// We restore the alphanumeric regex to support _ and numbers again
      '// Note: My_Variable and Variable123 remained; they were simply inaccessible
      uc.ExpressionTokens(TokenType.AlphaNumeric).Regex = "[a-zA-Z_][a-zA-Z0-9_]*"
      Console.WriteLine(uc.EvalStr("My_Variable"))
      Console.WriteLine(uc.EvalStr("Variable123"))
   End Sub
End Module
				
			
No error
No error
[a-zA-Z_][a-zA-Z0-9_]*
111
222
---
Invalid definition
Invalid definition
Undefined identifier
Undefined identifier
Undefined identifier
Undefined identifier
---
111
222
Previous
Next