uCalc API Version: 2.1.3-preview.2 Released: 6/17/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.

Format(string, DataType)

Method

Product: 

Fast Math Parser

Class: 

uCalcBase

Defines a declarative rule for transforming the string output of evaluation functions.

Syntax

Format(string, DataType)

Parameters

definition
string
A string containing the formatting rule definition.
targetType
DataType
(Default = Empty)
The specific data type this format applies to. If omitted, the format applies to all data types.

Return

Item

Returns the Item object representing the newly created format rule. This item can be used to .Release() the format later.

Remarks

The Format() method allows you to define powerful, declarative rules that automatically transform the string output of EvalStr and EvaluateStr. This is ideal for ensuring consistent formatting for currency, scientific notation, or custom displays without cluttering your application logic with string manipulation code.

📜 Definition String Syntax

The Definition string specifies the transformation rule and can contain several optional components:

[DataType: <TypeName>,] [InsertAt: <index>,] [Def: <variable> = <expression>]

  • DataType: Scopes the rule to a specific type (e.g., Double, String, Bool). This can also be set via the method's second parameter.
  • InsertAt: Controls the order of application when multiple formats are active. See the 'Chaining Formats' section below.
  • Def: The core expression that defines the transformation. It uses a temporary variable (e.g., Result, val) to represent the original output string.

There are two primary styles for writing the format expression:

This modern approach uses a built-in Format() function within the expression, mirroring the syntax of C++ std::format or Python f-strings.

// Format numbers to two decimal places.uc.Format("Result = Format('{:.2f}', double(Result))");

Note: The placeholder variable (Result) is always a string. For numeric format specifiers, you must cast it back to a number using double(Result), int(Result), etc.

Use ListOfItems(ItemIs.Format) to see the list of active formats.

2. String Concatenation Style

This legacy style builds the new string using the + operator.

// Wrap the output in brackets.uc.Format("Result = '[' + Result + ']'");

🔗 Chaining Formats

You can define multiple format rules, which are applied sequentially like a stack (Last-In, First-Out). The most recently defined format is applied first.

The InsertAt keyword gives you precise control over this order:

  • InsertAt: 0: Places the rule at the front of its type-specific chain (it will be applied last).
  • InsertAt: -1 or omitting it: Places the rule at the end of the chain (it will be applied first).
  • InsertAt: n: Inserts the rule at the nth position in the chain.

🧹 Cleanup

To remove all defined formats, call FormatRemove. To remove a single format rule, call .Release() on the Item object returned by this method.

⚖️ Comparative Analysis

Unlike traditional formatting (printf, C# string.Format), which requires you to wrap every output call, uCalc's Format method is declarative. You define the rules once, and they are applied automatically by EvalStr everywhere in your application for a given uCalc instance. This leads to cleaner, more maintainable code by separating calculation logic from presentation logic.

Examples

Succinct: A basic example that prepends text to all numeric output.
				
					using uCalcSoftware;

var uc = new uCalc();
// Define a format that only applies to Double data types.
var doubleType = uc.DataTypeOf("Double");
var fmt = uc.Format("Result = 'Value: ' + Result", doubleType);

Console.WriteLine(uc.EvalStr("10 * 2.5"));
Console.WriteLine(uc.EvalStr("'Hello'")); // String output is unaffected.

// Clean up the format rule
fmt.Release();
Console.WriteLine(uc.EvalStr("10 * 2.5")); // No longer formatted
				
			
Value: 25
Hello
25
				
					#include <iostream>
#include "uCalc.h"

using namespace std;
using namespace uCalcSoftware;

int main() {
   uCalc uc;
   // Define a format that only applies to Double data types.
   auto doubleType = uc.DataTypeOf("Double");
   auto fmt = uc.Format("Result = 'Value: ' + Result", doubleType);

   cout << uc.EvalStr("10 * 2.5") << endl;
   cout << uc.EvalStr("'Hello'") << endl; // String output is unaffected.

   // Clean up the format rule
   fmt.Release();
   cout << uc.EvalStr("10 * 2.5") << endl; // No longer formatted
}
				
			
Value: 25
Hello
25
				
					Imports System
Imports uCalcSoftware
Public Module Program
   Public Sub Main()
      Dim uc As New uCalc()
      '// Define a format that only applies to Double data types.
      Dim doubleType = uc.DataTypeOf("Double")
      Dim fmt = uc.Format("Result = 'Value: ' + Result", doubleType)
      
      Console.WriteLine(uc.EvalStr("10 * 2.5"))
      Console.WriteLine(uc.EvalStr("'Hello'")) '// String output is unaffected.
      
      '// Clean up the format rule
      fmt.Release()
      Console.WriteLine(uc.EvalStr("10 * 2.5")) '// No longer formatted
   End Sub
End Module
				
			
Value: 25
Hello
25
Practical: Using the C++ style `Format()` function for currency and text alignment.
				
					using uCalcSoftware;

var uc = new uCalc();
// Rule 1: Format Doubles as currency with two decimal places.
var doubleType = uc.DataTypeOf(BuiltInType.Float_Double);
uc.Format("Result = '$' + Format('{:.2f}', double(Result))", doubleType);

// Rule 2: Center-align strings in a 15-character field padded with '-'.
var strType = uc.DataTypeOf(BuiltInType.String);
uc.Format("Result = Format('{:-^15}', Result)", strType);

Console.WriteLine($"Price: {uc.EvalStr("199.999")}");
Console.WriteLine($"Discount: {uc.EvalStr("7.5")}");
Console.WriteLine($"Label: {uc.EvalStr("'Summary'")}");
				
			
Price: $200.00
Discount: $7.50
Label: ----Summary----
				
					#include <iostream>
#include "uCalc.h"

using namespace std;
using namespace uCalcSoftware;

int main() {
   uCalc uc;
   // Rule 1: Format Doubles as currency with two decimal places.
   auto doubleType = uc.DataTypeOf(BuiltInType::Float_Double);
   uc.Format("Result = '$' + Format('{:.2f}', double(Result))", doubleType);

   // Rule 2: Center-align strings in a 15-character field padded with '-'.
   auto strType = uc.DataTypeOf(BuiltInType::String);
   uc.Format("Result = Format('{:-^15}', Result)", strType);

   cout << "Price: " << uc.EvalStr("199.999") << endl;
   cout << "Discount: " << uc.EvalStr("7.5") << endl;
   cout << "Label: " << uc.EvalStr("'Summary'") << endl;
}
				
			
Price: $200.00
Discount: $7.50
Label: ----Summary----
				
					Imports System
Imports uCalcSoftware
Public Module Program
   Public Sub Main()
      Dim uc As New uCalc()
      '// Rule 1: Format Doubles as currency with two decimal places.
      Dim doubleType = uc.DataTypeOf(BuiltInType.Float_Double)
      uc.Format("Result = '$' + Format('{:.2f}', double(Result))", doubleType)
      
      '// Rule 2: Center-align strings in a 15-character field padded with '-'.
      Dim strType = uc.DataTypeOf(BuiltInType.String)
      uc.Format("Result = Format('{:-^15}', Result)", strType)
      
      Console.WriteLine($"Price: {uc.EvalStr("199.999")}")
      Console.WriteLine($"Discount: {uc.EvalStr("7.5")}")
      Console.WriteLine($"Label: {uc.EvalStr("'Summary'")}")
   End Sub
End Module
				
			
Price: $200.00
Discount: $7.50
Label: ----Summary----
Internal Test: Verifies the layering and precedence of multiple format rules using `InsertAt`.
				
					using uCalcSoftware;

var uc = new uCalc();
var strType = uc.DataTypeOf("String");

// Rule A (will be applied second)
uc.Format("val = '[' + val + ']'");

// Rule B (will be applied first)
uc.Format("val = 'inner:(' + val + ')'");

Console.WriteLine($"Default layering: {uc.EvalStr("'text'")}");

// Rule C: Insert this rule at position 0, making it apply LAST.
uc.Format("InsertAt: 0, Def: val = 'outer: {' + val + '}'");

Console.WriteLine($"With InsertAt: {uc.EvalStr("'text'")}");
				
			
Default layering: [inner:(text)]
With InsertAt: outer: {[inner:(text)]}
				
					#include <iostream>
#include "uCalc.h"

using namespace std;
using namespace uCalcSoftware;

int main() {
   uCalc uc;
   auto strType = uc.DataTypeOf("String");

   // Rule A (will be applied second)
   uc.Format("val = '[' + val + ']'");

   // Rule B (will be applied first)
   uc.Format("val = 'inner:(' + val + ')'");

   cout << "Default layering: " << uc.EvalStr("'text'") << endl;

   // Rule C: Insert this rule at position 0, making it apply LAST.
   uc.Format("InsertAt: 0, Def: val = 'outer: {' + val + '}'");

   cout << "With InsertAt: " << uc.EvalStr("'text'") << endl;
}
				
			
Default layering: [inner:(text)]
With InsertAt: outer: {[inner:(text)]}
				
					Imports System
Imports uCalcSoftware
Public Module Program
   Public Sub Main()
      Dim uc As New uCalc()
      Dim strType = uc.DataTypeOf("String")
      
      '// Rule A (will be applied second)
      uc.Format("val = '[' + val + ']'")
      
      '// Rule B (will be applied first)
      uc.Format("val = 'inner:(' + val + ')'")
      
      Console.WriteLine($"Default layering: {uc.EvalStr("'text'")}")
      
      '// Rule C: Insert this rule at position 0, making it apply LAST.
      uc.Format("InsertAt: 0, Def: val = 'outer: {' + val + '}'")
      
      Console.WriteLine($"With InsertAt: {uc.EvalStr("'text'")}")
   End Sub
End Module
				
			
Default layering: [inner:(text)]
With InsertAt: outer: {[inner:(text)]}
Output formatting without using a callback
				
					using uCalcSoftware;

var uc = new uCalc();
// The output is surrounded by < and >, and prepended with Answer:
uc.Format("Result = 'Answer: <' + Result + '>'");

Console.WriteLine(uc.EvalStr("10+20"));
Console.WriteLine(uc.EvalStr("'Hello '+'world'"));
Console.WriteLine(uc.EvalStr("5 > 10"));

uc.FormatRemove();
				
			
Answer: <30>
Answer: <Hello world>
Answer: <false>
				
					#include <iostream>
#include "uCalc.h"

using namespace std;
using namespace uCalcSoftware;

int main() {
   uCalc uc;
   // The output is surrounded by < and >, and prepended with Answer:
   uc.Format("Result = 'Answer: <' + Result + '>'");

   cout << uc.EvalStr("10+20") << endl;
   cout << uc.EvalStr("'Hello '+'world'") << endl;
   cout << uc.EvalStr("5 > 10") << endl;

   uc.FormatRemove();
}
				
			
Answer: <30>
Answer: <Hello world>
Answer: <false>
				
					Imports System
Imports uCalcSoftware
Public Module Program
   Public Sub Main()
      Dim uc As New uCalc()
      '// The output is surrounded by < and >, and prepended with Answer:
      uc.Format("Result = 'Answer: <' + Result + '>'")
      
      Console.WriteLine(uc.EvalStr("10+20"))
      Console.WriteLine(uc.EvalStr("'Hello '+'world'"))
      Console.WriteLine(uc.EvalStr("5 > 10"))
      
      uc.FormatRemove()
   End Sub
End Module
				
			
Answer: <30>
Answer: <Hello world>
Answer: <false>
Different output formats for different data types
				
					using uCalcSoftware;

var uc = new uCalc();
// String results will be surrounded by << and >>, while Boolean will be surrounded by [[ and ]]
uc.Format("DataType: String, Def: val = '<<' + val + '>>' ");
uc.Format("Bool, val = '[[' + val + ']]'"); // Shortcut notation without "DataType" or "Def"

Console.WriteLine(uc.EvalStr("10+20"));
Console.WriteLine(uc.EvalStr("'Hello '+'world'"));
Console.WriteLine(uc.EvalStr("5 > 10"));
Console.WriteLine(uc.EvalStr("5 < 10"));

uc.FormatRemove();
Console.WriteLine("---");
Console.WriteLine(uc.EvalStr("10+20"));
Console.WriteLine(uc.EvalStr("'Hello '+'world'"));
Console.WriteLine(uc.EvalStr("5 > 10"));
Console.WriteLine(uc.EvalStr("5 < 10"));
				
			
30
<<Hello world>>
[[false]]
[[true]]
---
30
Hello world
false
true
				
					#include <iostream>
#include "uCalc.h"

using namespace std;
using namespace uCalcSoftware;

int main() {
   uCalc uc;
   // String results will be surrounded by << and >>, while Boolean will be surrounded by [[ and ]]
   uc.Format("DataType: String, Def: val = '<<' + val + '>>' ");
   uc.Format("Bool, val = '[[' + val + ']]'"); // Shortcut notation without "DataType" or "Def"

   cout << uc.EvalStr("10+20") << endl;
   cout << uc.EvalStr("'Hello '+'world'") << endl;
   cout << uc.EvalStr("5 > 10") << endl;
   cout << uc.EvalStr("5 < 10") << endl;

   uc.FormatRemove();
   cout << "---" << endl;
   cout << uc.EvalStr("10+20") << endl;
   cout << uc.EvalStr("'Hello '+'world'") << endl;
   cout << uc.EvalStr("5 > 10") << endl;
   cout << uc.EvalStr("5 < 10") << endl;
}
				
			
30
<<Hello world>>
[[false]]
[[true]]
---
30
Hello world
false
true
				
					Imports System
Imports uCalcSoftware
Public Module Program
   Public Sub Main()
      Dim uc As New uCalc()
      '// String results will be surrounded by << and >>, while Boolean will be surrounded by [[ and ]]
      uc.Format("DataType: String, Def: val = '<<' + val + '>>' ")
      uc.Format("Bool, val = '[[' + val + ']]'") '// Shortcut notation without "DataType" or "Def"
      
      Console.WriteLine(uc.EvalStr("10+20"))
      Console.WriteLine(uc.EvalStr("'Hello '+'world'"))
      Console.WriteLine(uc.EvalStr("5 > 10"))
      Console.WriteLine(uc.EvalStr("5 < 10"))
      
      uc.FormatRemove()
      Console.WriteLine("---")
      Console.WriteLine(uc.EvalStr("10+20"))
      Console.WriteLine(uc.EvalStr("'Hello '+'world'"))
      Console.WriteLine(uc.EvalStr("5 > 10"))
      Console.WriteLine(uc.EvalStr("5 < 10"))
   End Sub
End Module
				
			
30
<<Hello world>>
[[false]]
[[true]]
---
30
Hello world
false
true
Inserts formatting in specified sequence
				
					using uCalcSoftware;

var uc = new uCalc();
uc.Format("Result = 'Answer: ' + Result");
uc.Format("DataType: String, Def: val = '<<' + val + '>>' ");
uc.Format("DataType: Bool, Def: val = '[[' + val + ']]'");

// Note the difference between where "Bool: " and "String: " are displayed in the result
uc.Format("InsertAt: 0, DataType: Bool, Def: val = 'Bool: ' + val");  // Inserts at 0th position of Bool
uc.Format("InsertAt: 1, DataType: String, Def: val = 'String: ' + val"); // Inserts at 1st position of String
Console.WriteLine(uc.EvalStr("10+20"));
Console.WriteLine(uc.EvalStr("'Hello '+'world'"));
Console.WriteLine(uc.EvalStr("5 > 10"));
Console.WriteLine("---");

// This fomratting will be the last one to take effect
uc.Format("InsertAt: 0, Def: val = 'Outer: ' + val");
Console.WriteLine(uc.EvalStr("10+20"));
Console.WriteLine(uc.EvalStr("'Hello '+'world'"));
Console.WriteLine(uc.EvalStr("5 > 10"));
Console.WriteLine("---");

// This formatting will be the first one to take effect
uc.Format("val = 'Inner: ' + val"); // Optionally InsertAt: -1 could have been used
Console.WriteLine(uc.EvalStr("10+20"));
Console.WriteLine(uc.EvalStr("'Hello '+'world'"));
Console.WriteLine(uc.EvalStr("5 > 10"));
Console.WriteLine("---");

uc.FormatRemove();

Console.WriteLine(uc.EvalStr("10+20"));
Console.WriteLine(uc.EvalStr("'Hello '+'world'"));
Console.WriteLine(uc.EvalStr("5 > 10"));
				
			
Answer: 30
Answer: String: <<Hello world>>
Bool: Answer: [[false]]
---
Outer: Answer: 30
Outer: Answer: String: <<Hello world>>
Outer: Bool: Answer: [[false]]
---
Outer: Answer: Inner: 30
Outer: Answer: String: <<Inner: Hello world>>
Outer: Bool: Answer: [[Inner: false]]
---
30
Hello world
false
				
					#include <iostream>
#include "uCalc.h"

using namespace std;
using namespace uCalcSoftware;

int main() {
   uCalc uc;
   uc.Format("Result = 'Answer: ' + Result");
   uc.Format("DataType: String, Def: val = '<<' + val + '>>' ");
   uc.Format("DataType: Bool, Def: val = '[[' + val + ']]'");

   // Note the difference between where "Bool: " and "String: " are displayed in the result
   uc.Format("InsertAt: 0, DataType: Bool, Def: val = 'Bool: ' + val");  // Inserts at 0th position of Bool
   uc.Format("InsertAt: 1, DataType: String, Def: val = 'String: ' + val"); // Inserts at 1st position of String
   cout << uc.EvalStr("10+20") << endl;
   cout << uc.EvalStr("'Hello '+'world'") << endl;
   cout << uc.EvalStr("5 > 10") << endl;
   cout << "---" << endl;

   // This fomratting will be the last one to take effect
   uc.Format("InsertAt: 0, Def: val = 'Outer: ' + val");
   cout << uc.EvalStr("10+20") << endl;
   cout << uc.EvalStr("'Hello '+'world'") << endl;
   cout << uc.EvalStr("5 > 10") << endl;
   cout << "---" << endl;

   // This formatting will be the first one to take effect
   uc.Format("val = 'Inner: ' + val"); // Optionally InsertAt: -1 could have been used
   cout << uc.EvalStr("10+20") << endl;
   cout << uc.EvalStr("'Hello '+'world'") << endl;
   cout << uc.EvalStr("5 > 10") << endl;
   cout << "---" << endl;

   uc.FormatRemove();

   cout << uc.EvalStr("10+20") << endl;
   cout << uc.EvalStr("'Hello '+'world'") << endl;
   cout << uc.EvalStr("5 > 10") << endl;
}
				
			
Answer: 30
Answer: String: <<Hello world>>
Bool: Answer: [[false]]
---
Outer: Answer: 30
Outer: Answer: String: <<Hello world>>
Outer: Bool: Answer: [[false]]
---
Outer: Answer: Inner: 30
Outer: Answer: String: <<Inner: Hello world>>
Outer: Bool: Answer: [[Inner: false]]
---
30
Hello world
false
				
					Imports System
Imports uCalcSoftware
Public Module Program
   Public Sub Main()
      Dim uc As New uCalc()
      uc.Format("Result = 'Answer: ' + Result")
      uc.Format("DataType: String, Def: val = '<<' + val + '>>' ")
      uc.Format("DataType: Bool, Def: val = '[[' + val + ']]'")
      
      '// Note the difference between where "Bool: " and "String: " are displayed in the result
      uc.Format("InsertAt: 0, DataType: Bool, Def: val = 'Bool: ' + val")  '// Inserts at 0th position of Bool
      uc.Format("InsertAt: 1, DataType: String, Def: val = 'String: ' + val") '// Inserts at 1st position of String
      Console.WriteLine(uc.EvalStr("10+20"))
      Console.WriteLine(uc.EvalStr("'Hello '+'world'"))
      Console.WriteLine(uc.EvalStr("5 > 10"))
      Console.WriteLine("---")
      
      '// This fomratting will be the last one to take effect
      uc.Format("InsertAt: 0, Def: val = 'Outer: ' + val")
      Console.WriteLine(uc.EvalStr("10+20"))
      Console.WriteLine(uc.EvalStr("'Hello '+'world'"))
      Console.WriteLine(uc.EvalStr("5 > 10"))
      Console.WriteLine("---")
      
      '// This formatting will be the first one to take effect
      uc.Format("val = 'Inner: ' + val") '// Optionally InsertAt: -1 could have been used
      Console.WriteLine(uc.EvalStr("10+20"))
      Console.WriteLine(uc.EvalStr("'Hello '+'world'"))
      Console.WriteLine(uc.EvalStr("5 > 10"))
      Console.WriteLine("---")
      
      uc.FormatRemove()
      
      Console.WriteLine(uc.EvalStr("10+20"))
      Console.WriteLine(uc.EvalStr("'Hello '+'world'"))
      Console.WriteLine(uc.EvalStr("5 > 10"))
   End Sub
End Module
				
			
Answer: 30
Answer: String: <<Hello world>>
Bool: Answer: [[false]]
---
Outer: Answer: 30
Outer: Answer: String: <<Hello world>>
Outer: Bool: Answer: [[false]]
---
Outer: Answer: Inner: 30
Outer: Answer: String: <<Inner: Hello world>>
Outer: Bool: Answer: [[Inner: false]]
---
30
Hello world
false
Previous
Next