---

Purpose

This is used to calculate a result based on other macros and calculations.

---

Compatibility

---

Usage

NCalc is used for expression evaluation (see NCalc documentation for built-in functions). In addition, the PanoramicData.NCalcExtensions library provides many additional functions - see the README for the full list. Note: Because ReportMagic uses commas to delimit parameters, either surround the condition with quotes or use backticks(`) instead of commas where needed. For example:

[Calculate:value="if(1<=2, 'AAA', 'BBB')"]

Note that you can use the shorthand for this macro i.e. '[=:' instead of '[Calculate:'. Some commonly used extension functions are shown below (this is not an exhaustive list):

• if(condition, trueValue, falseValue): returns one of two values depending on the condition
• in('needle', 'straw1', 'straw2', ...): returns true if the first value appears in the remaining values; also accepts a list variable as the second argument
• contains('haystack', 'needle'): returns true if the haystack string contains the needle
• startsWith / endsWith('haystack', 'needle'): string prefix/suffix tests
• indexOf / lastIndexOf('haystack', 'needle'): returns the integer offset, or -1 if not found
• length('string'): returns the integer length of the string or list
• toUpper / toLower / capitalize('string'): case conversion
• replace('input', 'find', 'replacement'): replaces all occurrences of a string
• substring('string', startIndex, length): extracts part of a string
• split('string', 'delimiter'): splits a string into a list
• trim('string'): removes leading and trailing whitespace
• timeSpan('fromDate', 'toDate', 'unit'): time between two dates in the given unit (Milliseconds, Seconds, Minutes, Hours, Days, Weeks, Years)
• dateAdd('date', amount, 'unit'): adds an interval to a DateTime
• now('timezone'): the current date/time, with optional timezone correction
• humanize(value, 'timeUnit'): converts a numeric duration to readable text e.g. humanize(1.5, 'days') = '1 day 12 hours'
• isNaN / isInfinite / isNull / isNullOrEmpty(value): value type/state tests
• list(items): creates a list; jObject(key, value, ...): creates a JSON object; jArray(items): creates a JSON array
• where(list, 'x', 'condition'): filters a list; select(list, 'x', 'expression'): transforms a list
• orderBy(list, 'x', 'expression'): sorts a list; first / last / skip / take: list navigation
• count(list) / sum(list) / min(list) / max(list): list aggregates
• countBy(list, 'x', 'expression'): groups and counts into a JObject
• jPath(obj, 'path'): selects a value from a JObject using a JPath expression
• getProperty(obj, 'name'): returns a property value from an object
• regexIsMatch('input', 'pattern'): tests a regex match; regexGroup('input', 'pattern', group): captures a group
• nullCoalesce(a, b, ...): returns the first non-null value
• try(expression, fallback): returns fallback if the expression throws
• switch(value, case1, result1, ..., default): multi-branch conditional
• round(value, decimalPlaces): rounds a number (see examples, below)

Note: The value will be stored in output variables (e.g. using storeAs, storeAsHidden or the '=>' shorthand) as the original type and at full precision. For example, if you output a DateTime, the full precision will be stored, including hours, minutes and seconds. For an integer of 12345, the integer value will be stored. However, the value output into the document must formatted as a string. The conversion from original output to string is achieved using the format parameter and the way in which this happens will depend on the type of the output. For example, the output of a DateTime written to the document might be '2023-02-17'. The integer may be formatted as '12,345'. If you would like to additionally store the formatted string to a variable, use the storeFormattedValueAs parameter.

.

---

---

Examples (44)

Example 1

---

Example 2

---

Example 3

---

Example 4

---

Example 5

---

Example 6

---

Example 7

---

Example 8

---

Example 9

---

Example 10

---

Example 11

---

Example 12

---

Example 13

---

Example 14

---

Example 15

---

Example 16

---

Example 17

---

Example 18

---

Example 19

---

Example 20

---

Example 21

---

Example 22

---

Example 23

---

Example 24

---

Example 25

---

Example 26

---

Example 27

---

Example 28

---

Example 29

---

Example 30

---

Example 31

Calculate and store the value 12.34 into a variable (at 1 decimal place precision), and DISPLAY at 1 decimal place too by using the 'format' parameter:

---

Example 32

Calculate and store the value 12.34 into a variable (at 1 decimal place precision), but DISPLAY at 1 decimal place (by omitting the 'format' parameter):

---

Example 33

---

Example 34

---

Example 35

Stores what you can see in ReportStudio (to 2 decimal places) as the variable B and stores the hidden output (to 0 decimal places) in A.

---

Example 36

You can create JObjects directly and access the values using the [.:] shorthand. Note this example uses the Calculate macro shorthand i.e. starts with '[=:' instead of '[Calculate:]' :

---

Example 37

This example creates a jArray:

---

Example 38

This example creates a jArray:

---

Example 39

This example creates a string URL and uses the Calculate macro shorthand i.e. starts with '[=:' instead of '[Calculate:]' :

---

Example 40

This example creates a string URL and uses the Calculate macro shorthand i.e. starts with '[=:' instead of '[Calculate:]' :

---

Example 41

Counts the number of characters in a string

---

Example 42

Counts the number of characters in a string

---

Example 43

Counts by how many of each number there are in a list, i.e. grouped by the values themselves, and stores the results as a new JObject (dictionary) variable:

---

Example 44Normal mode

This Normal Mode example counts 'Tickets' grouped by their name and stores the result as a new jObject (dictionary) variable: