Calculation

Calc Expression

Calculation functions calculate inner expression and write result as output. Currently, a function subset of our Calc engine has been adapted to use with the template engine and hence the feature supports various binary, unary and arithmetic operators, aggregate functions, constants, and text functions. The examples below show how to use aggregate and arithmetic operations to create expressions in Calc function.

Refer to the following example code to calculate the average using multiple arguments:

// Initialize GcWordDocument.
GcWordDocument doc = new GcWordDocument();
var ds = new int[] { 1, 2, -2, 16, 7, 5, 4 };

// Bind data source.       
doc.DataTemplate.DataSources.Add("ds", ds);

// Calculate average using multiple arguments.        
doc.Body.Paragraphs.Add("{{ calc Average(ds.value+Sum(ds.value)/2)}}");
doc.DataTemplate.Process();
doc.Save("complex-expression-inside-average.docx");

Refer to the following example code to calculate the sum using a constant:

// Initialize GcWordDocument.
var doc = new GcWordDocument();
var ds = new int[] { 1, 2, -2, 16, 7, 5, 4 };

// Bind data source.
doc.DataTemplate.DataSources.Add("ds", ds);

// Calculate sum using a constant.
doc.Body.Paragraphs.Add("{{ calc Sum(2 + ds.value)}}");
doc.DataTemplate.Process();
doc.Save("sum-with-constant.docx");

Refer to the following example code to calculate the average using two collections inside the aggregate function:

// Initialize GcWordDocument.
var doc = new GcWordDocument();
var ds = new int[] { 1, 2, -2, 16, 7, 5, 4 };
var ds2 = new int[] { 5, 3, };

// Bind data source.        
doc.DataTemplate.DataSources.Add("ds", ds);
doc.DataTemplate.DataSources.Add("ds2", ds2);

// Calculate average using two collections inside the aggregate function.            
doc.Body.Paragraphs.Add("{{ calc Average(ds.value+ds2.value)}}");
doc.DataTemplate.Process();
doc.Save("sum-with-two-colls.docx");

To view Calc functions in action, see Calculation demo sample.

Format Function

GcWord provides Format function that can calculate inner expressions and output the result in different formats and cultures. The Format function is used with the Calc Expression.

Refer to the following example code to display the data in date formatting:

// Add dates in date format and different locales.
var paras = doc.Body.Paragraphs;
var p = paras.Add("Date formatting examples:", style);
p.ListFormat.Template = list;
p = paras.Add("Date with default formatting:  {{calc Format(dsDate.value)}}", style);
p.ListFormat.Template = list;
p.ListFormat.LevelNumber = 1;
p = paras.Add("Date formatted as ('D', 'en-US'):  {{calc Format(dsDate.value, \"D\", \"en-US\")}}", style);
p.ListFormat.Template = list;
p.ListFormat.LevelNumber = 1;
p = paras.Add("Date formatted as ('D', 'fr-FR'):  {{calc Format(dsDate.value, \"D\", \"fr-FR\")}}", style);
p.ListFormat.Template = list;
p.ListFormat.LevelNumber = 1;
p = paras.Add("Date formatted as ('D', 'ja-JP'):  {{calc Format(dsDate.value, \"D\", \"ja-JP\")}}", style);
p.ListFormat.Template = list;
p.ListFormat.LevelNumber = 1;

Refer to the following example code to display the data in number formatting:

// Add number in different fromats and cultures.
p = paras.Add("Number formatting examples:", style);
p.ListFormat.Template = list;
p = paras.Add("Number with default formatting:  {{calc Format(dsNum.value)}}", style);
p.ListFormat.Template = list;
p.ListFormat.LevelNumber = 1;
p = paras.Add("Number formatted as ('C', 'en-US'):  {{calc Format(dsNum.value, \"C\", \"en-US\")}}", style);
p.ListFormat.Template = list;
p.ListFormat.LevelNumber = 1;
p = paras.Add("Number formatted as ('C', 'fr-FR'):  {{calc Format(dsNum.value, \"C\", \"fr-FR\")}}", style);
p.ListFormat.Template = list;
p.ListFormat.LevelNumber = 1;
p = paras.Add("Number formatted as ('C3', 'ja-JP'):  {{calc Format(dsNum.value, \"C3\", \"ja-JP\")}}", style);
p.ListFormat.Template = list;
p.ListFormat.LevelNumber = 1;

Refer to the following example code to display the data in expression formatting:

// Add expressions in different formats.
p = paras.Add("Expression formatting examples:", style);
p.ListFormat.Template = list;
p = paras.Add("Numeric expression:  {{calc Format(dsNum.value / 2)}}", style);
p.ListFormat.Template = list;
p.ListFormat.LevelNumber = 1;
p = paras.Add("Boolean expression:  {{calc Format(IsFirst(dsNum.value))}}", style);
p.ListFormat.Template = list;
p.ListFormat.LevelNumber = 1;

Limitations

Calc functions cannot be used without at least one datasource added to DataTemplate.
Function names are reserved and cannot be used inside data sources. This limitation is case in-sensitive and limits only simplified names. So if you have datasource field ds.count, you can use it as {{calc ds.count*5}}. Calc Engine fails to process if you use it as {{calc count*5}}.
When multiple collections of different lengths are used at the same level of expression, the engine will determine the minimal length of the used collections and use it for both collections. In the code example above, both collections ds and ds2 are used "at the same level" in the expression. So, only two elements from both collections will be used, as 2 is Min(ds.Length, ds2.Length).

Note:
Template values inside expression are used without usual {{ and }} braces.
In many cases, result type is double, even if original type was integer.