Functions

This reference article contains a complete list of functions available in DTL.

For an introduction to the concept of functions (alongside much more background information), see DTL language essentials.

As that article explains, functions take parameters and return a single value. They are identical in concept to the functions found in many programming languages. However, you cannot define your own functions in DTL - you can only call the built-in functions listed on this page.

base64_to_hex

Given a string representing binary data encoded in base 64, return the same binary data encoded as a string of hex digits (two digits per byte).

Signature

$result: String = base64_to_hex (original: String)

Parameters

Name Type Optional Comments
original String   The string containing the data encoded in base 64.

Notes

  1. For a description of base 64 encoding, see (for example) Wikipedia.
  2. The result is a series of hexadecimal digits (0 to 9 or a to f), with two digits for each byte in the decoded binary data. There are no spaces between the bytes.
  3. If original is not a valid encoding in base 64, an error is returned.

has_prefix

Determine whether a given string starts with a specific sequence of characters.

Signature

$result: Boolean = has_prefix (original: String, prefix: String)

Parameters

Name Type Optional Comments
original String   The string to assess.
prefix String   The prefix to check for.

Notes

  1. If prefix is the empty string, true is returned.
  2. The match is case-sensitive.

replace

Given an existing string, return a new string, with every instance of a specified substring replaced by another specified substring.

Signature

$result: String = replace (original: String, old: String, new: String)

Parameters

Name Type Optional Comments
original String   The string to be altered.
old String   The substring to be replaced wherever found.
prefix String   The replacement substring.

Notes

  1. It is permissible for old and new to be of different lengths.
  2. If the substring old is present more than once, each instance is replaced.
  3. If the substring old is not present, original is returned unchanged.
  4. If old is the empty string, original is returned unchanged.
  5. If new is the empty string, each instance of the substring old is removed without replacement.
  6. If old matches overlapping substrings, the left-most possible substring is replaced.

replace_prefix, replace_suffix

Given an existing string, return a new string, with a specified substring replaced by another specified substring:

  • replace_prefix: if it is present at the beginning of the string
  • replace_suffix: if it is present at the end of the string.

Signature

$result: String = replace_prefix (original: String, old: String, new: String)
$result: String = replace_suffix (original: String, old: String, new: String)

Parameters

Name Type Optional Comments
original

String

  The string to be altered. 
old String   The substring to be replaced, if present in the applicable position.
new String   The replacement substring.

Notes

  1. It is permissible for old and new to be of different lengths.
  2. Only one instance of the substring old is replaced, even if it appears repeatedly.
  3. If the substring old is not present in the relevant position, original is returned unchanged.
  4. If old is the empty string, original is returned unchanged.
  5. If new is the empty string and the substring old is present in the relevant position, the substring is removed without replacement.

substring

Given an existing string, extract the substring starting and ending at specified character positions.

Signature

$result: String = substring (original: String, start: Int, [length: Int])

Parameters

Name Type Optional Comments
original String   The original string from which the substring is to be extracted. 
start Int   The index of the first character to extract from original. The first character is numbered 1.
length Int Optional The number of characters to extract. If omitted, the whole string commercing at the start is returned.

Notes

  1. If start or length is negative, an error is raised.
  2. If length is zero, an empty string is returned.
  3. If start exceeds the length of original, an empty string is returned.
  4. If original is not long enough to extract length characters commencing at start, then the whole string commencing at start is returned. In this case, the string returned will be shorter than suggested by length.

to_int

Convert a string representation of a number into a value of type Int, truncating any fractional part.

Signature

$result: Int = to_int (original: String)

Parameters

Name Type Optional Comments
original String   The string to convert to an integer.

Notes

  1. The string must represent a number in base 10. Other radixes are not supported.
  2. If the string represents a non-integer number (containing a decimal point), then the fractional part is truncated. For example to_int ("1.9") returns 1, and to_int ("-1.9") returns -1.
  3. If the string contains characters other than digits and (optionally) a single decimal point, an error is raised.
  4. If the value represented by the string is too large in magnitude to be represented as a 64-bit signed integer, an error is raised.

to_str

Convert a value of any type to a string representation of that value.

Signature

$result: String = to_str (original: Any)

Parameters

Name Type Optional Comments
original Any   The value to convert to a string.

Notes

  1. Boolean values are converted to the string true or false.
  2. Int values are represented in base 10, with no leading zeros.
  3. Float values are represented in base 10, with no leading zeros, no trailing zeros after the decimal point, and as many digits after the decimal point as necessary to represent the value. If the float value is an integer, no decimal point or fractional part appear. Exponential notation is not used.
  4. String values are returned unchanged.
  5. If the parameter does not have one of the types listed above, an error is raised.

to_upper, to_lower

Given an existing string, return a new string with:

  • to_upper: all letters converted to upper case
  • to_lower: all letters converted to lower case

Signature

$result: String = to_upper (original: String)
$result: String = to_lower (original: String)

Parameters

Name Type Optional Comments
original String   The string to be converted to upper or lower case.

Notes

  1. Characters which are not letters are unchanged.

trim, trim_left, trim_right

Given an existing string, return a new string with any instances of specified characters removed:

  • trim: at the beginning and end of the string
  • trim_left: at the beginning of the string only
  • trim_right: at the end of the string only.

Signature

$result: String = trim (original: String, chars: String)
$result: String = trim_left (original: String, chars: String)
$result: String = trim_right (original: String, chars: String)

Parameters

Name Type Optional Comments
original String   The string to be trimmed.
chars String   The characters to be trimmed, concatenated into a single string value in any order.

Notes

  1. Characters are removed from the beginning and/or end of original, one at a time, as long as they are found in chars. As soon as a character is encountered which is not in chars, no further characters are removed.
  2. The match is case-sensitive.
  3. If chars is the empty string, original is returned unchanged.

trim_prefix, trim_suffix

Given an existing string, return a new string, with a specified substring removed:

  • trim_prefix: if it is present at the beginning of the string
  • trim_suffix: if it is present at the end of the string.

Signature

$result: String = trim_prefix (original: String, substring: String)
$result: String = trim_suffix (original: String, substring: String)

Parameters

Name Type Optional Comments
original String   The string to be trimmed.
substring String   The substring to remove, if present in the applicable position.

Notes

  1. Only one instance of the substring is removed, even if the substring appears repeatedly.
  2. If the substring is not present in the relevant position, original is returned unchanged.
  3. If substring is the empty string, original is returned unchanged.

years_since

Given a string representing a date, return the number of full years between that date and today's date.

Signature

$result: Int = years_since (date: String, format: String)

Parameters

Name Type Optional Comments
date

String

  The date to use in the calculation, representing as a string.
format String   A description of the format of date, in Python strftime format.

Notes

  1. For a description of the syntax of format, see .
  2. Only full years are counted. In other words, the result is rounded down to an integer number of years.
  3. At a minimum, datemust specify a year. If only a year (but no day or month) is specified, then the calculation is made based on 1 January of that year. If only a year and a month (but no day) is specified, then the calculation is made based on the first day of the month.
  4. If dateis in the future, zero is returned.
  5. If formatis not a valid Python strftimeformat string, an error is raised.
  6. If date is not in the format specified by format, an error is raised.