Format(string, DataType)

Method

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

Product:

Class:

uCalc

Warning

uCalc API Preview Release Notice:The uCalc engine has successfully transitioned to modern cross-platform environments.The next phase envolves some structural changes, performance optimizations, and API refinements.The API is subject to breaking changes prior to the stable release. Please evaluate the preview version thoroughly before production use.

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:

1. C++ `std::format` Style (Recommended)

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

using uCalcSoftware;

var uc = new uCalc();

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

Note: The C++ based format in uCalc works only in Windows as of this writing. This is because uCalc is currently compiled with C++ 20 to get the right balance between maximum compatibility across platforms and access to modern C++ functionality. std::format is technically part of C++ 20, but it's not universally implemented in different compilers using the C++ 20 compilation directive.

2. String Concatenation Style

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

using uCalcSoftware;

var uc = new uCalc();

// 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

A basic example that prepends text to all numeric output.

ID: 351

See: Format(string, DataType)

				
					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

using uCalcSoftware;&#13;&#13;var uc = new uCalc();&#13;// Define a format that only applies to Double data types.&#13;var doubleType = uc.DataTypeOf("Double");&#13;var fmt = uc.Format("Result = 'Value: ' + Result", doubleType);&#13;&#13;Console.WriteLine(uc.EvalStr("10 * 2.5"));&#13;Console.WriteLine(uc.EvalStr("'Hello'")); // String output is unaffected.&#13;&#13;// Clean up the format rule&#13;fmt.Release();&#13;Console.WriteLine(uc.EvalStr("10 * 2.5")); // No longer formatted

Format(string, DataType)

Method

Syntax

Parameters

Return

Item

Remarks

📜 Definition String Syntax

1. C++ std::format Style (Recommended)

2. String Concatenation Style

🔗 Chaining Formats

🧹 Cleanup

⚖️ Comparative Analysis

Examples

A basic example that prepends text to all numeric output.

Practical: Using the C++ style `Format()` function for currency and text alignment.

Internal Test: Verifies the layering and precedence of multiple format rules using `InsertAt`.

Output formatting without using a callback

Different output formats for different data types

Inserts formatting in specified sequence

1. C++ `std::format` Style (Recommended)