> ## Knowledge Base Index
> Fetch the complete knowledge base index at: https://support.pdfgeneratorapi.com/sitemap.xml
> Use this file to discover available pages before exploring further.
> Pure-Markdown content can be obtained by appending a '.md' suffix to the content URLs listed in the sitemap (without the trailing slash).

# Functions


### Number functions

##### Format number
Format a number with grouped thousands and optionally decimal digits. 
```
{% number_format([float number], [decimal_places], [decimal_separator], [thousands_separator]) %}
```

##### Round
Round the float number based on the precision from the second parameter. 
```
{% round([float number], [integer precision]) %}
```

##### Ceil
Rounds to the nearest integer up. E.g. 2.1 => 3. 
```
{% ceil ([float number]) %}
```

##### Floor
Rounds to the nearest integer down. E.g. 2.8 => 2. 
```
{% floor ([float number]) %}
```

##### Pow
Number in power of. 
```
{% pow([float base value], [integer|float power of]) %}
```

##### Sqrt
Square root of a number. 
```
{% sqrt ([float base value])%}
```

### String functions

##### Uppercase
To display data field value in uppercase, use following expression. 
```
{% uppercase({dataFieldName}) %}
```

##### Lowercase
To display data field value in lowercase, use following expression. 
```
{% lowercase({dataFieldName}) %}
```

##### Capitalize
Uppercase the first character of each word in a string. 
```
{% capitalize({dataFieldName}) %}
```

##### Split
The **split(delimiter, string)** function allows to split string into an array. 
```
{% split("_", "Some_string") %} => ["Some", "string"]
```

##### Replace
The `str_replace([string: search], [string: replace], [string: the original string])` function replaces all occurrences of a substring within a string.
```
{% str_replace("dog", "cat", "this is dog") %}
```
 This expression output is: *this is cat*

|| The first two parameters can also be arrays that specify search and replace values e.g. {% str_replace(["dog", " is"], ["cat", " is not"], "this is dog") %} => this is not cat

##### Substring
The `substr ( string $string , int $offset , int|null $length = null )` returns the portion of string specified by the offset and length parameters.
```
{% substr("This is test", 0, 2) %} // Result: Th
{% substr("This is test", 1, 2) %} // Result: hi
{% substr("This is test", -2) %} // Result: st
```

##### Count
The **count({stringData})** returns the length of the string
```
{% count("abcd") %} // Result: 4
```

### Date functions

##### Date
Format date value.
```
{% date({dateString}, {timezone}, {addDays}, {outputFormat}, {inputFormat}) %}
```
*Examples of the function "Date":*
* Display current time
```
{% date('now') %}
```
* Specify timezone
```
{% date({dateValue}, 'UTC') %}
```
* Specify output format
```
{% date({dateValue}, 'UTC', 0, 'd/m/Y') %}
```
* Specify output and input format
```
{% date({dateValue}, 'UTC', 0, 'd/m/Y', 'm/d/Y') %}
```

##### Datetime
Format datetime value.
```
{% datetime({datetimeString}, {timezone}, {addDays}, {outputFormat}, {inputFormat}) %}
```
*Examples of the function "Datetime":*
* Display current time
```
{% datetime('now') %}
```
* Specify timezone
```
{% datetime({dateValue}, 'UTC') %}
```
* Specify output format
```
{% datetime({dateValue}, 'UTC', 0, 'd/m/Y H:i:s') %}
```
* Specify output and input format
```
{% datetime({dateValue}, 'UTC', 0, 'd/m/Y H:i:', 'm/d/Y H:i:') %}
```

||| When using the T separator in a date format you need to escape it like this

```
Y-m-d\THH:mm:ss
```

##### Date difference
The `date_diff` function calculates a difference between two dates. You can also specify the `{inputFormat}` to hint date format. If date strings use known format then it is handled automatically.

|| The {inputFormat} parameter in the date_diff function is by default 'Y-m-d H:i:s'

```
{% date_diff({datetimeString}, {datetimeString}, {inputFormat}) %}
```

You can use `date('now')` function as the date value to find difference between today and another date.
```
{% date_diff(date('now'), '2021-09-15', 'Y-m-d') %}
```

|| When configuring the outputFormat and inputFormat parameters of date/datetime/date_diff function, please refer to the table below for a clear explanation of the supported formats. This will ensure the Date component processes and displays dates as intended.

| **Format** | **Description** | **Example Output** |
| ---- |
| **Day** |  |  |
| `d` | The day of the month (two digits, leading zeros) | 01 to 31 |
| `D` | A textual representation of a day (three letters) | Mon through Sun |
| `j` | The day of the month without leading zeros | 1 to 31 |
| `l` | A full textual representation of the day | Sunday through Saturday |
| `N` | ISO-8601 numeric representation of the day (1 = Monday, 7 = Sunday) | 1 to 7 |
| `S` | English ordinal suffix for the day of the month (2 characters: st, nd, rd, or th) | 1st, 2nd, 3rd |
| `w` | Numeric representation of the day (0 = Sunday, 6 = Saturday) | 0 to 6 |
| `z` | The day of the year | 0 through 365 |
| **Week** |  |  |
| `W` | ISO-8601 week number of year (weeks starting on Monday) | 01 to 53 |
| **Month** |  |  |
| `F` | A full textual representation of a month | January through December |
| `m` | Numeric representation of a month (two digits, leading zeros) | 01 to 12 |
| `M` | A short textual representation of a month (three letters) | Jan through Dec |
| `n` | Numeric representation of a month (without leading zeros) | 1 to 12 |
| `t` | The number of days in the given month | 28 to 31 |
| **Year** |  |  |
| `L` | Whether it's a leap year (1 if it is a leap year, 0 otherwise) | 0 or 1 |
| `o` | ISO-8601 year number | 2023 |
| `Y` | A full numeric representation of a year (four digits) | 2023 |
| `y` | A two-digit representation of a year | 23 |
| **Time** |  |  |
| `a` | Lowercase am or pm | am, pm |
| `A` | Uppercase AM or PM | AM, PM |
| `B` | Swatch Internet time | 000 to 999 |
| `g` | 12-hour format of an hour (no leading zeros) | 1 to 12 |
| `G` | 24-hour format of an hour (no leading zeros) | 0 to 23 |
| `h` | 12-hour format of an hour (two digits, leading zeros) | 01 to 12 |
| `H` | 24-hour format of an hour (two digits, leading zeros) | 00 to 23 |
| `i` | Minutes with leading zeros | 00 to 59 |
| `s` | Seconds, with leading zeros | 00 to 59 |
| `u` | Microseconds | 654321 |
| **Timezone** |  |  |
| `e` | Timezone identifier | UTC, GMT, Europe/Paris |
| `I` | Whether the date is in Daylight Savings Time (1 if DST, 0 otherwise) | 0 or 1 |
| `O` | Difference to Greenwich time (GMT) in hours | +0200 |
| `P` | Difference to Greenwich time (GMT) with colon between hours and minutes | +02:00 |
| `T` | Timezone abbreviation | EST, MDT |
| `Z` | Timezone offset in seconds (west of UTC is negative, east of UTC is positive) | -43200 to 50400 |
| **Full Date/Time** |  |  |
| `c` | ISO-8601 date | 2023-01-14T23:59:59+00:00 |
| `r` | RFC 2822 formatted date | Sat, 14 Jan 2023 23:59:59 +0000 |
| `U` | Seconds since the Unix Epoch (January 1 1970 00:00:00 GMT) | 1673740799 |

### List (array) functions

##### Count
It is possible to count number of items in list. 
```
{% count({line_items}) > 3 ? 'More than three' : 'Less than three' %}
```

##### Max
Returns maximum value of list of elements or separate field values. 
```
{% max({line_items::quantity}) %}
```
or
```
{% max({dataField1}, {dataField2}, ..., {dataFieldN}) %}
```

##### Min
Returns minimum value of list of elements or separate field values. 
```
{% min({line_items::quantity}) %}
```
or
```
{% min({dataField1}, {dataField2}, ..., {dataFieldN}) %}
```

##### Sum
It is possible to calculate sum of table column using following code.
```
{% sum({line_items::amount}) %}
```

##### Sumproduct
The sumproduct function multiplies the corresponding items in the arrays and returns the sum of the results. 
```
{% sumproduct({line_items::amount},{line_items::price}, {line_items::anotherColumn}) %}
```

##### Average
It is possible to calculate average of table column using following code.
```
{% avg({line_items::amount}) %}
```

| Tip: Use the Number Component or apply "Number" formatting within tables, when creating calculations or using functions like sum, average and sumproduct.

##### Join
The **join(delimiter, array)** function concatenates field values with specified separator. Last argument is always used as the separator. 
```
{% join(";", {field1}, {field2}, {field3}, ..., {fieldN}) %}
{% join(";", [{field1}, {field2}, {field3}, ..., {fieldN}]) %}
```

##### Iterate list of elements (array map)
Iterates over list of elements and executes expression for each element. Returns new list. 
```
{% iterate({line_items}, 'quantity*price') %}
```

```
{% map({line_items}, 'quantity*price') %}
```

##### Filter list of elements
Filters a list of elements by executing the given expression for each element. Returns new list.
```
{% filter({line_items}, 'price > 10.1') %}
```

|| Iterate, map, and filter functions also accept a third parameter, which can be used as a 'reference' in the expression:

```
{% iterate({list}, 'value === reference', 3) %} // reference = 3
{% map({list}, 'value === reference', 3) %} // reference = 3
{% filter({list}, 'value === reference', 3) %} // reference = 3
```

##### Collect unique values from list
Collects unique values from and counts them. Returns new list with following structure: 
```
[{"value": "Value", "count": 3, "raw_value": "Value"}, {"value": "Value 2", "count": 1, "raw_value": "Value 2"}]
{% collect_unique_values({array}, {array_of_values_to_exclude}, {expression_to_execute_for_each_item}) %}
```

**Example use case**:
This is the JSON example dataset to demonstrate the functionality of collect_unique_values function.
```json
[{"array_of_names":[{"name":"marian"},{"name":"bruno"},{"name":"erik"},{"name":"tanel"},{"name":"michal"},{"name":"erik"},{"name":"erik"}]}]
```

Lets say we want to make a list of unique values from the "array_of_names" data field, but exclude the names "tanel" and "michal".
The expression to do that would look like this:
```
{% join(", ", iterate((collect_unique_values({array_of_names}, ["michal","tanel"], "name")), "value")) %}
```

##### Flatten list
Flattens list. 
```
{% flatten(iterate({orders}, "{line_items}")) %}
```

##### Sort list
The function `sort([array], [expression], [direction]))` allows you to sort list of elements by the key value. The `direction` can be either `ASC` or `DESC`. The function returns new array with sorted items.

```
{% sort({line_items}, "quantity", "DESC") %}
{% sort({line_items}, "quantity*price", "ASC") %} 
{% sort({line_items}, "quantity > 10 ? 1 : 0", "ASC") %}
```

### Utility functions

##### Empty
The **empty(value)** checks if the variable exists and if the value is not “falsy”. Returns true if var does not exist or has a value that is empty or equal to zero, aka falsely. Otherwise, it returns false.
```
{% empty({dataField}) ? 'No value' : 'Field has value' %}
```

What qualifies as "falsy"?
* Anything that returns false if cast to boolean
* Empty array
* Zero as number
* Zero as string
* Empty string
* null
* false
* undefined

##### JSON decode
Decode JSON string to use in an expression. 
```
{% json_decode('{"key": "value"}', true) %}
```
Example datafield:
```
{
    "json_field": "{\"name\":\"value\"}"
}
```
Example expressions for JSON decode
```
{% json_decode({json_field}).name %}
{% json_decode({json_field}, true)['name'] %}
```
---
### Related articles you may find helpful

* [How to add page numbers?](https://support.pdfgeneratorapi.com/en/article/how-to-add-page-numbers-1re50ta/)
* [Is it possible to conditionally change the component style or hide the component?](https://support.pdfgeneratorapi.com/en/article/is-it-possible-to-conditionally-change-the-component-style-or-hide-the-component-z8nmwg/)
* [Text Component](https://support.pdfgeneratorapi.com/en/article/text-component-c3s12i/)