ATL Functions

Index

ATL function groups

At the heart of ATL is a collection of functions that you can use to manipulate data. The functions are organized into the following groups:

Data access functions. These functions allow you to access parts of your input data. They take input data and return a value. This is typically some kind of data structure — list, table region, ATL object, etc. — that you can further interrogate with other functions.
Datetime functions. You can apply these functions to datetime objects to achieve many useful effects. For example, you can calculate durations, convert datetimes from one timezone to another, and format datetimes in the your preferred pattern.
Formatting functions. These functions apply highly specific formatting to numbers. They help you ensure that numerical values are formatted correctly and consistently throughout your narrative.
Language functions. These functions help you to improve the overall written quality of your narratives. For example, they help you to eliminate grammatical errors by handling tasks such as verb inflection and pronoun selection. They also allow you to build linguistic variation into your narratives.
Mathematical functions. These functions perform mathematical operations. You can use them for simple calculations (e.g. summing a list of numbers) or more complex tasks such as group-by aggregation or calculating percentage change across a series.
Statistics functions. These functions allow for advanced statistical analysis of your data. You might use them to detect different anomaly types, calculate variance, or perform a rolling correlation analysis.
Text functions. These functions enable you to manipulate text in a variety of helpful ways. For example, you can use them to change the casing of a text string, enter substitute text, or ensure that Studio processes certain text in your script as HTML.
Tools. The functions in the Tools group are developer tools. You would typically use these functions for testing or debugging while building a project. For example, you might use them to test a value's data type or to generate log statements in the console log area.
Advanced functions. These functions perform sophisticated filtering, sorting, grouping, and data validation tasks. Unlike the functions in the other groups, these are unavailable in the Function Builder. Advanced functions are typically used by experienced users who are comfortable writing raw ATL.

You can embed functions in your script using the Function Builder or by writing directly in ATL.

Tip

See Index of ATL functions for links to each function topic.

Examples in function topics

Each ATL function has its own topic in this docset. Each topic describes the function's purpose, explains the requirements for each parameter, and includes examples to demonstrate the function in action.

Tip

The Index of ATL functions includes links to each function topic.

The functions use raw ATL syntax for the examples. Calls to ATL functions are surrounded by pairs of square brackets, like this: [[functionCall]]. In other words, the examples assume you are using the script editor's ATL View.

Please note that the square brackets are not visible when you use the editor in Marked Up View. Also, the presentation of some functions may be simpler, to make it easier to read your scripts.

The different script editor views are explained in User Interface > Compose View.

Nesting ATL functions

Function calls can be nested arbitrarily deeply. So, for example, the following is a valid ATL expression:

[[numToWords(product(sum(Value1, Value2, Value3), Value4))]]

This block of ATL uses three functions:

The sum function calculates the sum total of Value1, Value2, and Value3.
The product function then multiples the summed total by Value4.
The numToWords function converts the output number to words.

Much of ATL’s power comes from being able to combine functions in this way.

How to format strings as arguments in functions

You often need to give a string as an argument to a function. Strings are delimited by single or double quotes and it usually doesn’t matter which you use. However, there are differences in the treatment of single-quoted and double-quoted strings:

If you use single quote marks, the string is treated as a verbatim string.
If you use double quote marks, then the contents of the string are treated as a script; that is, embedded ATL will be evaluated.

Tip

If you want to use a simple string, we recommend that you use single quotes. Also, be aware that when you input a string into a parameter using the Function Builder, you don’t need to include quote marks; the builder will add them for you.

Quotation marks within quotation marks

The following is an example of a string that contains an embedded statement with a single-quoted string. Notice that the nested quotes do not have to be escaped because they are part of a nested statement.

[[titleCase("he said [[upper('this is')]] good")]]

is equivalent to:

[[titleCase("he said [[upper("this is")]] good")]]

Though the former is preferred, both produce:

He Said THIS IS Good

There is no need to escape the quote because it is obvious from the context that it belongs to the syntax of the embedded statement rather than the outer double quote.

However, in the following example, we want to include double quotes in our output, so the nested double quotes have to be escaped so they aren’t considered as string delimiters:

[[titleCase("he said \"[[upper('this is')]] good\"")]]

produces:

He Said “THIS IS Good”